Branch maintenance policy

Last modified
Friday, May 19, 2017 - 12:29

Release branches ('1.x')

The branches numbered 'X.Y' (e.g. '1.2', '1.3', '1.4', etc) exist to support bugfixing on stable releases (as well as pending releases, e.g. during the release beta period).

No changes can be submitted to these branches without having been integrated into the "higher release" branches first (with the notable exception when a change does not apply to higher releases): e.g. when 1.5 is the latest release and a fix is wanted for 1.4, the bugfix is applied to 'master', then to the '1.5' branch and only then to the '1.4' branch (when all are applicable).

Also, no changes will be merged to release branches unless required to fix bugs and the changes proposed for backport will be minimal. In other words, user experience improvements should not be part of the proposed fix. Additionally, changes which don't fix bugs - i.e. those that add functionality or change user experience - should not be proposed for backport.

'master' branch

The 'master' branch is considered to be "the next-up release version"; it's operated under a "stable master" policy: all changes integrated into the master branch should be covered by test coverage, should be tested and should not have destabilizing effects for the remainder of the code base. In case of new features, the features proposed for inclusion should be "feature complete" to the extent that the feature presents a well-rounded user experience. (Note that this does not mean that there can't be a list of known improvements for the proposed feature!)

At no time should there be feature integration requests (Pull Requests) which bring into the code base unused APIs, unless the purpose of the change is to present a coherent external API. At all times externally presented APIs should be proposed with tests - minimally on the outer-most API level, but preferably on each of the levels 'Database', 'Perl' and 'Web Service'.

Feature branches

New features start out on feature branches and remain on such branches as long as necessary to develop "feature completeness", tests and "sufficient stability". While this can mean that they have to exist for an extended period of time (and there is no limit set that), this brings the risk of increased chances for merge conflicts. Instead of creating a single all-encompassing integration request, it's generally better to define a minimally scoped (valuable to a user, acceptable to the community) feature which can be integrated initially, with a list of further feature improvements and expansions to work on after the initial feature is integrated.

An example of a long-lived feature branch is the multi-currency-improvement branch (a.k.a. "MC branch"), which lived for more than two years before it could be merged to 'master'. During that period, prerequisite features were developed and merged to master, working into master the smaller (minimally scoped) features to build the final MC change upon.