Branching strategy for git

[Geert Janssens]

On Saturday 22 March 2014 10:18:42 John Ralls wrote:
> 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/03487
> > 8.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.
> 
I hadn't heard of rerere either. Looks like a very useful support tool. If I understand correctly, it's 
a local-only tool. rerere cache doesn't propagate with pushes or pulls. Which means that if one 
contributor has a rerere cache on his local machine to get his feature branch merged into the 
development branch, this cache is not available to you or me when we try to merge a pull 
request. That's probably why the git workflow man page suggests the integrator can ask a 
feature author to perform the merge.

> 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.
> 
In the git workflows man page the release tags can be on either the development branch or the 
maintenance branch. 

> 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.
> 
I'm fine with not doing a separate release branch. This came up in the earlier discussion to allow 
for a gatekeeper role. But there are other ways to do that. The petsc workflow calls this 
'gatekeeper' a maintainer. By limiting commit access to one or a few people on the stable 
branch, you can equally have control over what goes into stable or not.

>From that point of view I agree that having a separate branch for stable development and 
releases is more overhead than benefit.

> 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