BEP 6: Branching policy

Proposal:

• Milestones:

  • future (or x.0) – the next major, breaking release
  • next – x.y or x.y.z release, whichever comes first
  • x.y – major minor changes, non-user breaking
  • x.y.z – minor patch changes, regression fixes from x.{y-1} or x.y.{z-1} release

• Branches:

  • future – aligns with future milestone
  • master – the next x.y milestone
  • release_x.y – branch off master after feature freeze (master becomes x.{y+1})
  • release_x.y.z – the next x.y.z release

The main assumption behind this proposal is that the majority work is done on master for the next x.y milestone. I assume that most changes will require a “break-in” period that can’t be (and shouldn’t be guaranteed) by minor patch releases. I additionally assume that it will be easier for all contributors to target master branch, instead of targeting specific branches, which I leave for project/release maintainers. Thus I assume most external contributions will be made available in x.y releases, unless we (the maintainers) backport those changes to x.{y-1}.z releases.

Minor Patch releases (x.y.z) should not contain any new features and/or major changes of other kind, and thus shouldn’t have more that a dozen (roughly speaking) PRs merged. This will ensure that they can be released quickly and without major breakage, and won’t require extensive testing, which should be left for x.y releases.

Details will need to be figured out, e.g. when exactly release_x.y.z is branched of master, etc.

The alternative is to have only release_x, release_x.y and release_x.y.z branches, but I’m certain that this would cause chaos for external contributors, and make master branch an archive of old releases, instead of what it typically means in git, which is the current development branch.

[bryevdv]

@mattpap I have updated the Wiki document I think that restricted to only branching, things are simple enough to not need examples, so I have deleted that empty section. I also made a few tweaks re: prefer to land on current base and cherry-pick backports. Can you look and see if there are any other changes you would like to make before voting to adopt this BEP? I’d like to mark is as implemented by next week at the lastes.

Regarding “dev” branch, I think things have been going well just having branch-x.y be the current branch and switching it right at release. It’s very clear and explicit where changes are landing and it’s also the way some other (fairly larger) projects handle things. So I would propose to keep the new status quo.

[mattpap]

I will comment soon, though I agree with most of the suggestions.