SYNCING - tmux - Rivoreo Source Code Repositories

 Preamble
 ========

 Tmux on SourceForge has two git repositories [1] "tmux-code" and "tmux-openbsd".
 Here's a description of them:

 * "tmux-code" 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).

 It is assumed that the person doing the sync has read/write access to the
 tmux-code 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-code and tmux-openbsd cloned, as in:

 % cd /some/where/useful
 % git clone ssh://${USER}@git.code.sf.net/p/tmux/tmux
 % git clone ssh://${USER}@git.code.sf.net/p/tmux/tmux-openbsd

 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-code" 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-code" repository, as
 shown by the following command:

 % cd /path/to/tmux-code
 % 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-code" 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-code", we have to ensure the "master" branch from "tmux-openbsd" is
 up-to-date first, and then reference that update in "tmux-code", as in:

 % cd /path/to/tmux-openbsd
 % git checkout master
 % git pull

 Then back in "tmux-code":

 % cd /path/to/tmux-code
 % git fetch obsd-tmux-code

 Creating the necessary branches
 ===============================

 Now that "tmux-code" 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-code" repository:

 % git checkout -b obsd-master obsd-tmux/master

 Adding in the fake history points
 =================================

 To tie both the "master" branch from "tmux-code" and the "obsd-master"
 branch from "tmux-openbsd" together, the fake history points added to the
 "tmux-code" repository need to be added.  To do this, we must add an
 additional refspec line, as in:

 % cd /path/to/tmux-code
 % 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-code":

 % 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 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

 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. Comment the "found_debug=yes" line in configure.ac, since releases
    don't have debugging enabled, otherwise make(1) aborts when
    preparing the distribution.

 2. 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.

 3. Tag with:

    % git tag -a 1.X

    Where "1.X" is the next version.

    Push the tag out with:

    % git push 1.X

 4. Build the tarball with make dist.  Now that it's using autoconf there
    shouldn't be any weird files (such as the original and rejection files
    from patch(1)) but it doesn't hurt taking a quick look at it.

 5. Split the release changes into a new file.  This should be named
    tmux-$VERSION-readme to make sourceforge show it automagically in specific
    parts of the project page.

 6. Upload the tarball and the above file. Make the tarball the default
    download by selecting all operating systems under the file details.

 7. Run make update-index.html upload-index.html to replace %%VERSION%%.

 8. Bump version in configure.ac and uncomment "found_debug=yes" to create
    a debug build by default.

 9. Update freshmeat.

 [1] https://sourceforge.net/p/tmux/_list/git
	Preamble
	========

	Tmux on SourceForge has two git repositories [1] "tmux-code" and "tmux-openbsd".
	Here's a description of them:

	* "tmux-code" 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).

	It is assumed that the person doing the sync has read/write access to the
	tmux-code 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-code and tmux-openbsd cloned, as in:

	% cd /some/where/useful
	% git clone ssh://${USER}@git.code.sf.net/p/tmux/tmux
	% git clone ssh://${USER}@git.code.sf.net/p/tmux/tmux-openbsd

	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-code" 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-code" repository, as
	shown by the following command:

	% cd /path/to/tmux-code
	% 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-code" 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-code", we have to ensure the "master" branch from "tmux-openbsd" is
	up-to-date first, and then reference that update in "tmux-code", as in:

	% cd /path/to/tmux-openbsd
	% git checkout master
	% git pull

	Then back in "tmux-code":

	% cd /path/to/tmux-code
	% git fetch obsd-tmux-code

	Creating the necessary branches
	===============================

	Now that "tmux-code" 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-code" repository:

	% git checkout -b obsd-master obsd-tmux/master

	Adding in the fake history points
	=================================

	To tie both the "master" branch from "tmux-code" and the "obsd-master"
	branch from "tmux-openbsd" together, the fake history points added to the
	"tmux-code" repository need to be added. To do this, we must add an
	additional refspec line, as in:

	% cd /path/to/tmux-code
	% 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-code":

	% 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 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

	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. Comment the "found_debug=yes" line in configure.ac, since releases
	don't have debugging enabled, otherwise make(1) aborts when
	preparing the distribution.

	2. 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.

	3. Tag with:

	% git tag -a 1.X

	Where "1.X" is the next version.

	Push the tag out with:

	% git push 1.X

	4. Build the tarball with make dist. Now that it's using autoconf there
	shouldn't be any weird files (such as the original and rejection files
	from patch(1)) but it doesn't hurt taking a quick look at it.

	5. Split the release changes into a new file. This should be named
	tmux-$VERSION-readme to make sourceforge show it automagically in specific
	parts of the project page.

	6. Upload the tarball and the above file. Make the tarball the default
	download by selecting all operating systems under the file details.

	7. Run make update-index.html upload-index.html to replace %%VERSION%%.

	8. Bump version in configure.ac and uncomment "found_debug=yes" to create
	a debug build by default.

	9. Update freshmeat.

	[1] https://sourceforge.net/p/tmux/_list/git