Add SYNCING document

This explains how to keep the tmux and tmux-openbsd repositories in sync
with one another during the course of tmux development.

1 files changed, 142 insertions, 0 deletions

diff --git a/SYNCING b/SYNCING
new file mode 100644
index 00000000..fe5263d9
--- /dev/null
+++ b/SYNCING
@@ -0,0 +1,142 @@
+Preamble
+========
+
+Tmux on SourceForge has two git repositories [1] "tmux" and "tmux-openbsd".
+Here's a description of them:
+
+* "tmux" is the portable version, the one which contains code for other
+  operating systems, and autotools, etc., which isn't found or needed in the
+  OpenBSD base system.
+
+* "tmux-openbsd" is the version of tmux in OpenBSD base system which provides
+  the basis of the portable tmux version.
+
+Note:  The "tmux-openbsd" repository is actually handled by "git cvsimport"
+running at 15 minute intervals, so a commit made to OpenBSD's tmux CVS
+repository will take that long to appear in this git repository.
+
+It is assumed that the person doing the sync has read/write access to the
+tmux repository on SourceForge already.
+
+If you've never used git before, git tracks meta-data about the committer
+and the author, as part of a commit, hence:
+
+% git config [--global] user.name "Your name"
+% git config [--global] user.email "you@yourdomain.com"
+
+Note that, if you already have this in the global ~/.gitconfig option, then
+this will be used.  Setting this per-repository would involve not using the
+"--global" flag above.   If you wish to use the same credentials always,
+pass the "--global" option, as shown.
+
+This is a one-off operation once the repository has been cloned, assuming
+this information has ever been set before.
+
+Cloning repositories
+====================
+
+This involves having both tmux and tmux-openbsd cloned, as in:
+
+% cd /some/where/useful
+% git clone ssh://${USER}@tmux.git.sf.net/gitroot/tmux/tmux
+% git clone ssh://${USER}@tmux.git.sf.net/gitroot/tmux/tmux-openbsd
+
+Note that you do not need additoinal checkouts to manage the sync -- an
+existing clone of either repositories will suffice.  So if you already have
+these checkouts existing, skip that.
+
+Adding in git-remotes
+=====================
+
+Because the portable "tmux" git repository and the "tmux-openbsd" repository do
+not inherently share any history between each other, the history has been
+faked between them.  This "faking of history" is something which has to be
+told to git for the purposes of comparing the "tmux" and "tmux-openbsd"
+repositories for syncing.  To do this, we must reference the clone of the
+"tmux-openbsd" repository from the "tmux" repository, as shown by the
+following command:
+
+% cd /path/to/tmux
+% git remote add obsd-tmux file:///path/to/tmux-openbsd
+
+So that now, the remote "obsd-tmux" can be used to reference branches and
+commits from the "tmux-openbsd" repository, but from the context of the
+portable "tmux" repository, which makes sense because it's the "tmux"
+repository which will have the updates applied to them.
+
+Fetching updates
+================
+
+To ensure the latest commits from "tmux-openbsd" can be found from within
+"tmux", we have to ensure the "master" branch from "tmux-openbsd" is
+up-to-date first, and then reference that update in "tmux", as in:
+
+% cd /path/to/tmux-openbsd
+% git checkout master
+% git pull
+
+Then back in "tmux":
+
+% cd /path/to/tmux
+% git fetch obsd-tmux
+
+Creating the necessary branches
+===============================
+
+Now that "tmux" can see commits and branches from "tmux-openbsd" by way of
+the remote name "obsd-tmux", we can now create the master branch from
+"tmux-openbsd" in the "tmux" repository:
+
+% git checkout -b obsd-master obsd-tmux/master
+
+Adding in the fake history points
+================================= 
+
+To tie both the "master" branch from "tmux" and the "obsd-master" branch
+from "tmux-openbsd" together, the fake history points added to the "tmux"
+repository need to be added.  To do this, we must add an additional refspec
+line, as in:
+
+% cd /path/to/tmux
+% git config --add remote.origin.fetch '+refs/replace/*:refs/replace/*'
+% git fetch origin --all
+
+Performing the Sync
+===================
+
+Make sure the "master" branch is checked out:
+
+% git checkout master
+
+The following will show commits on OpenBSD not yet synched with tmux
+portable:
+
+% git log master..obsd-master
+
+From there, the merge should be a fast-forward, using the OURS strategy to
+tell git that conflicts coming from OpenBSD respect the existing code in
+tmux where those conflicts wouldn't arise.  Hence:
+
+% git merge -s ours obsd-master
+
+Then ensure things look correct by BULDING the result of that sync:
+
+% make clean && ./autogen.sh && ./configure && make
+
+Compare the git merge result with what's on origin/master -- that is, check
+which commits you're about to push:
+
+% git log origin/master..master
+
+And if happy:
+
+% git push origin master
+
+-- Thomas Adam
+
+RELEASE TMUX FOR NEXT VERSION
+=============================
+
+TODO:  git tag, CHANGES, etc.
+
+[1] http://tmux.git.sourceforge.net/git/gitweb-index.cgi