Branching strategy for git

[John Ralls]

On Mar 22, 2014, at 4:01 PM, Geert Janssens <janssens-geert at telenet.be> wrote:

> On Saturday 22 March 2014 10:18:42 John Ralls wrote:
> > 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. 

The release tag should be attached to whatever commit is used to make the tarball. If we’re releasing directly off of the maint or master branches (per where you settled out later), then none of this is a concern.
 
>  
> > 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
> > make the new version a "conflict resolution"?
> > 
> I think you can't skip the merge in such cases. Future commits on stable that you do want to merge (in code that is still similar between the branches for example) will pull in the merge conflict anyway.
>  
> How exactly to handle the merge will probably depend a little on the issue at hand and the git knowledge of the person doing the merge.
> The one-commit approach would be merge-resolve conflicts-commit resolved merge. If the stable fix has no resemblance anymore with what's needed on devel to get the same bug fixed we might also do a merge dropping all stable branch changes for that fix, then add a new commit with the proper fix after the merge. The second option feels more cluttered though and makes it harder to read the history later on.
>  
> So I'd prefer to do the fix straight away in the merge commit when possible.

Always. ;-) “When possible” is of course the catch. 
>  
> > 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?
> > 
> I like the workflow as proposed in the git workflows man page (section Branch management for a release and following). They propose a long-term maintenance branch. Only when a new feature release is done, a separate maintenance branch for the previous stable series is created. So when 2.8.0 gets tagged, the current head of stable is branched off into stable-2.6. Then stable is fast forwarded to the 2.8.0 release tag.

It won’t quite fast-forward because of ChangeLog and NEWS, but those are minor issues; the releaser can just resolve to the new version.

>  
> This looks like a good approach to me as it allows us to do what we did with 2.4.15 and 2.6.1. We still wanted to release one version on the old stable, while there was already a new stable.
>  
> > 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.
> > 
> That's not PetSC but the third example I had found doing so. I think having a branch for releases only doesn't work very well if you want to have releases in different stable series (like 2.4.15 when 2.6.0 already exists). So for me that third example is less suited for gnucash. Both the git workflows man page and the PetSC workflow assume master to be the development branch. The stable series is called 'maint'.
>  
> For me what git workflows and PetSC do makes most sense. In all the projects that I have encountered so far, the default checkout is the development branch (trunk in svn, master in git). So I'd keep it that way.
>  
> Do we want an integration branch (called 'next' by both examples) ? It can help predict merge conflicts and experiment with conflict resolution before merging from stable to master. Or is our team too small for that ? It can be added in a later phase as well of course. It would be an upgrade of the basic workflow, not a different workflow.

‘Next’ and ‘maint’ are just different names for ‘stable’ and ‘release’ in your original proposal.

As long as we’re not listening to the Github siren (the Odyssey kind, not the one on police cars) and merging directly into the public repo, there’s every opportunity to test-merge and reset back as necessary in one’s private repo and no need for a public branch on which to commit before merging.

>  
> And what names do we want to use for our public branches ? Should we just stick to the git workflow examples (maint, master, next) ? That would make it easier to refer to the man page as the reference for our workflow.
>  

I’m fine with ‘master’ and ‘maint’.

Regards,
John Ralls