diff options
Diffstat (limited to 'SYNCING')
-rw-r--r-- | SYNCING | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/SYNCING b/SYNCING new file mode 100644 index 00000000..a0d0404c --- /dev/null +++ b/SYNCING @@ -0,0 +1,172 @@ +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. Tag with: + + % git tag -a 2.X + + Where "2.X" is the next version. + + Push the tag out with: + + % git push --tags + +3. Build the tarball with 'make dist'. + +4. 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. + +5. Clone the tmux.github.io repository, and change the RELEASE version in the + Makefile. Commit it, and run 'make' to replace %%VERSION%%. Push the + result out. + +6. Bump version in tmux/tmux.git configure.ac and uncomment "enable_debug=yes" + to create a debug build by default. |