From a043b975ca0ed13d590fe334b36a896172c44ab7 Mon Sep 17 00:00:00 2001 From: Thomas Adam Date: Sun, 16 Sep 2012 22:53:58 +0100 Subject: 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. --- SYNCING | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 SYNCING (limited to 'SYNCING') 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 -- cgit v1.2.3