1 files changed, 173 insertions, 0 deletions
diff --git a/SYNCING b/SYNCING
new file mode 100644
index 00000000..b8cc4b5c
--- /dev/null
+++ b/SYNCING
@@ -0,0 +1,173 @@
+Preamble
+========
+
+Tmux portable relies on  repositories "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 at least that long to appear in this git repository.
+(It might take longer, depending on the CVS mirror used to import the
+OpenBSD code).
+
+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 https://github.com/tmux/tmux.git
+% git clone https://github.com/ThomasAdam/tmux-openbsd.git
+
+Note that you do not need additional 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
+
+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":
+
+% git log master..obsd-master
+
+From there, merge the result in, fixing up any conflicts which might arise.
+
+% git merge obsd-master
+
+Then ensure things look correct by BUILDING 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
+
+Keeping an eye on libutil in OpenBSD
+====================================
+
+A lot of the compat/ code in tmux comes from libutil, especially imsg.
+Sometimes the API can change, etc., which might cause interesting problems
+trying to run the portable version of tmux.  It's worth checking
+periodically for any changes to libutil in OpenBSD and syncing those files
+to compat/ as and when appropriate.
+
+Release tmux for next version
+=============================
+
+1. Update and commit README and CHANGES.  The former should be checked for
+   anything outdated and updated with a list of things that might break
+   upgrades and the latter should mention all the major changes since
+   the last version.
+
+2. Make sure configure.ac has the new version number.
+
+3. Tag with:
+
+   % git tag -a 2.X
+
+   Where "2.X" is the next version.
+
+   Push the tag out with:
+
+   % git push --tags
+
+4. Build the tarball with 'make dist'.
+
+5. Check the tarball.  If it's good, go here to select the tag just pushed:
+
+   https://github.com/tmux/tmux/tags
+
+   Click the "Add release notes", upload the tarball and add a link in the
+   description field to the CHANGES file.
+
+6. Clone the tmux.github.io repository, and change the RELEASE version in the
+   Makefile.  Commit it, and run 'make' to replace %%RELEASE%%.  Push the
+   result out.
+
+7. Change version back to master in configure.ac.