SYNCING

   1 Preamble
   2 ========
   3
   4 Tmux portable relies on  repositories "tmux" and "tmux-openbsd".
   5 Here's a description of them:
   6
   7 * "tmux" is the portable version, the one which contains code for other
   8   operating systems, and autotools, etc., which isn't found or needed in the
   9   OpenBSD base system.
  10
  11 * "tmux-openbsd" is the version of tmux in OpenBSD base system which provides
  12   the basis of the portable tmux version.
  13
  14 Note:  The "tmux-openbsd" repository is actually handled by "git cvsimport"
  15 running at 15 minute intervals, so a commit made to OpenBSD's tmux CVS
  16 repository will take at least that long to appear in this git repository.
  17 (It might take longer, depending on the CVS mirror used to import the
  18 OpenBSD code).
  19
  20 If you've never used git before, git tracks meta-data about the committer
  21 and the author, as part of a commit, hence:
  22
  23 % git config [--global] user.name "Your name"
  24 % git config [--global] user.email "you@yourdomain.com"
  25
  26 Note that, if you already have this in the global ~/.gitconfig option, then
  27 this will be used.  Setting this per-repository would involve not using the
  28 "--global" flag above.   If you wish to use the same credentials always,
  29 pass the "--global" option, as shown.
  30
  31 This is a one-off operation once the repository has been cloned, assuming
  32 this information has ever been set before.
  33
  34 Cloning repositories
  35 ====================
  36
  37 This involves having both tmux and tmux-openbsd cloned, as in:
  38
  39 % cd /some/where/useful
  40 % git clone https://github.com/tmux/tmux.git
  41 % git clone https://github.com/ThomasAdam/tmux-openbsd.git
  42
  43 Note that you do not need additional checkouts to manage the sync -- an
  44 existing clone of either repositories will suffice.  So if you already have
  45 these checkouts existing, skip that.
  46
  47 Adding in git-remotes
  48 =====================
  49
  50 Because the portable "tmux" git repository and the "tmux-openbsd"
  51 repository do not inherently share any history between each other, the
  52 history has been faked between them.  This "faking of history" is something
  53 which has to be told to git for the purposes of comparing the "tmux" and
  54 "tmux-openbsd" repositories for syncing.  To do this, we must reference the
  55 clone of the "tmux-openbsd" repository from the "tmux" repository, as
  56 shown by the following command:
  57
  58 % cd /path/to/tmux
  59 % git remote add obsd-tmux file:///path/to/tmux-openbsd
  60
  61 So that now, the remote "obsd-tmux" can be used to reference branches and
  62 commits from the "tmux-openbsd" repository, but from the context of the
  63 portable "tmux" repository, which makes sense because it's the "tmux"
  64 repository which will have the updates applied to them.
  65
  66 Fetching updates
  67 ================
  68
  69 To ensure the latest commits from "tmux-openbsd" can be found from within
  70 "tmux", we have to ensure the "master" branch from "tmux-openbsd" is
  71 up-to-date first, and then reference that update in "tmux", as in:
  72
  73 % cd /path/to/tmux-openbsd
  74 % git checkout master
  75 % git pull
  76
  77 Then back in "tmux":
  78
  79 % cd /path/to/tmux
  80 % git fetch obsd-tmux
  81
  82 Creating the necessary branches
  83 ===============================
  84
  85 Now that "tmux" can see commits and branches from "tmux-openbsd" by way
  86 of the remote name "obsd-tmux", we can now create the master branch from
  87 "tmux-openbsd" in the "tmux" repository:
  88
  89 % git checkout -b obsd-master obsd-tmux/master
  90
  91 Adding in the fake history points
  92 =================================
  93
  94 To tie both the "master" branch from "tmux" and the "obsd-master"
  95 branch from "tmux-openbsd" together, the fake history points added to the
  96 "tmux" repository need to be added.  To do this, we must add an
  97 additional refspec line, as in:
  98
  99 % cd /path/to/tmux
 100 % git config --add remote.origin.fetch '+refs/replace/*:refs/replace/*'
 101 % git fetch origin
 102
 103 Performing the Sync
 104 ===================
 105
 106 Make sure the "master" branch is checked out:
 107
 108 % git checkout master
 109
 110 The following will show commits on OpenBSD not yet synched with "tmux":
 111
 112 % git log master..obsd-master
 113
 114 From there, merge the result in, fixing up any conflicts which might arise.
 115
 116 % git merge obsd-master
 117
 118 Then ensure things look correct by BUILDING the result of that sync:
 119
 120 % make clean && ./autogen.sh && ./configure && make
 121
 122 Compare the git merge result with what's on origin/master -- that is, check
 123 which commits you're about to push:
 124
 125 % git log origin/master..master
 126
 127 And if happy:
 128
 129 % git push origin master
 130
 131 Keeping an eye on libutil in OpenBSD
 132 ====================================
 133
 134 A lot of the compat/ code in tmux comes from libutil, especially imsg.
 135 Sometimes the API can change, etc., which might cause interesting problems
 136 trying to run the portable version of tmux.  It's worth checking
 137 periodically for any changes to libutil in OpenBSD and syncing those files
 138 to compat/ as and when appropriate.
 139
 140 Release tmux for next version
 141 =============================
 142
 143 1. Update and commit README and CHANGES.  The former should be checked for
 144    anything outdated and updated with a list of things that might break
 145    upgrades and the latter should mention all the major changes since
 146    the last version.
 147
 148 2. Make sure configure.ac has the new version number.
 149
 150 3. Tag with:
 151
 152    % git tag -a 2.X
 153
 154    Where "2.X" is the next version.
 155
 156    Push the tag out with:
 157
 158    % git push --tags
 159
 160 4. Build the tarball with 'make dist'.
 161
 162 5. Check the tarball.  If it's good, go here to select the tag just pushed:
 163
 164    https://github.com/tmux/tmux/tags
 165
 166    Click the "Add release notes", upload the tarball and add a link in the
 167    description field to the CHANGES file.
 168
 169 6. Clone the tmux.github.io repository, and change the RELEASE version in the
 170    Makefile.  Commit it, and run 'make' to replace %%RELEASE%%.  Push the
 171    result out.
 172
 173 7. Change version back to master in configure.ac.