Branching strategy for git

Sat Mar 22 13:18:42 EDT 2014

On Mar 22, 2014, at 3:24 AM, Geert Janssens <janssens-geert at telenet.be> wrote:

> This topic has been brought up before but we never really came to a consensus on how we 
> want to organize our branches in the official git repository. Yet I want to get a final decision on 
> this before we open a master for feature development again.
> 
> To refresh memory here is a link to the thread on gnucash-devel last year January about this 
> topic:
> 
> http://lists.gnucash.org/pipermail/gnucash-devel/2013-January/034843.html
> 
> The model I defended in that thread is more or less this (quoted from 
> http://lists.gnucash.org/pipermail/gnucash-devel/2013-February/034878.html )
> 
> - one branch for future development (features, refactoring, anything too complex for a stable 
> release)
> - there can be subbranches for separate features or refactoring efforts 
> that get merged into the main development branch when they are 
> considered ready
> - one branch for stable development (bugfixes, translation updates). 
> This branch gets merged into development regularly to get all bugfixes 
> into the future development as well
> - one release branch. The only direct commits here are those purely 
> related to releasing, like updating the version number. Other than that 
> it receives bugfixes and translation updates merged in from the stable 
> branch.
> 
> This setup leverages the git history to keep track of which changes go where. It solves the 
> problem of forgotten backports (there no longer are any) and makes sure that all bugfixes 
> eventually end up in all branches that should carry them.
> 
> This obsoletes our current BP/AUDIT machinery which was adopted because svn history was not 
> capable of managing this on its own.
> 
> At some point we had some kind of a gatekeeper to tell which bugfixes were allowed on stable 
> and which aren't. This person tracked the AUDIT mails to know which commits to verify. If we 
> want to re-establish this function in the future I think the easiest way would be as follows:
> - only the gatekeeper can push to the central stable branch.
> - bugfixes are done on their local stable branches and they send pull requests (or patches) for 
> review to the gatekeeper
> - the gatekeeper evaluates the pull requests/patches and accepts or rejects.
> 
> Using pull requests once more leverages one of the powers of git.
> 
> 
> 
> Since that long-winded thread I have found some workflows as recommended by other projects 
> managed in git. I have collected some links to such workflows in our wiki [1]. Reading those you 
> will find they all more or less start on a similar basis. I find it rather amusing we got to such a 
> similar result by independently thinking about this. Some workflows add more branches in the 
> mix, like an integration branch. We may want to discuss if those extra's make sense in the small 
> team we currently are.
> 
> Please give your feedback on whether or not we  want to adopt such a workflow. If so we really 
> need to review the Backporting stuff on our Git wiki page.

I think the key point from that earlier discussion is that git merge is a lot more powerful than is apparent on the surface. One example is 'rerere' [1], which was mentioned in passing in the Petsc branching article you linked on the wiki. I wasn't aware of that option until now, but contrary to the implications of the Petsc mention, it must be deliberately enabled.

There's a lot of good insight in the git workflows manpage [2], also linked in the wiki, including some rules about managing what to merge into which branch. One of the more interesting of those is the recommendation to fix bugs in the *most stable* branch and merge upwards. That's consistent with your 'stable' branch recommendation.

There are two things about a separate release branch containing only the release commits that require a bit more thought:

1. Those commits have 3 changes: The version number in configure.ac, the git log -> ChangeLog, and the release blurb summarizing the bug fixes and translation updates in NEWS. One could argue persuasively that NEWS and ChangeLog are obsolete thanks to git's vastly better logging facility and that we should just remove them. If we decide not to do that, we'll need to figure out a branching strategy that carries them into new release branches. Regardless, the 'stable' branch needs to have *something* in AC_INIT. What should that be?

2. The release tags will be on the release branch, so `git describe` will make sense only there. The same is true for history on Github, which admittedly doesn't do a good job of highlighting tags anyway. They will show up in the 'network' display there (though that's so slow I seldom use it) and in a multi-branch display in any of the graphical repo browsers, so maybe this isn't a big deal.

What are the implications of not doing a separate release branch and doing releases from 'stable', more or less as we do now? Only that every time we merge 'stable' to 'master' after a release there will be a conflict at the AC_INIT line because the version number in 'master' will be either 2.6.99 or 2.7.x. That conflict always gets resolved in favor of 'master'. NEWS and ChangeLog will fast-forward until we start doing unstable releases from 'master', after which they'll have to be hand-merged. I think that's less work and produces clearer history than separating the 'stable' and 'release' branches.

All of the guidance and discussion so far has been in the context of 'fix bugs and add features' development, but we're planning major architectural and language changes that are going to diverge 'master' from 'stable' rather radically. Ideally that would mean that many bug fixes won't need to be merged up because the bug won't exist in 'master', but the reality is more likely to be that it does, but the solution must be written differently. Do we still do the merge and make the new version a "conflict resolution"?

Is 'stable' going to be per-release-series, i.e., will we have 'stable-2.6' and in two years 'stable-2.8'? Or do we have a single 'stable' that gets 'master' merged into it at the time of an x.x.0 release?

Should 'master' be the stable branch with a 'devel' branch getting the new stuff, so that someone cloning the repo gets the stable code by default? PetSC goes one further and makes 'master' the release branch so a cloner gets the last release as their default, but I think that runs a bit counter to what most people expect when they clone a repo.

Regards,
John Ralls

[1] http://git-scm.com/2010/03/08/rerere.html
[2] https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html