Git Development Model

Last modified by Sergiu Dumitriu on 2011/04/19 10:53

This is work in progress, to be moved in the platform development documentation when agreed on and voted.

This proposal is inspired by http://nvie.com/posts/a-successful-git-branching-model/ but is simplified to satisfy the needs of XWiki. Please read that document before or after this one, as it contains better definitions for the various branches, useful images and git commands about how to do all this.

Short story

There will be one single main branch, master, where everybody commits. If subgroups need it, they can create feature branches for sharing experimental work, but it is strongly encouraged that things are integrated as soon as possible in the master, for continuous integration purposes.

For every release, we'll create a branch, of whose maintenance the release master is responsible. Tags will be made "on this branch", when the release is done. Since a branch, as well as a tag, are only pointers to a commit (which can actually determine an unique path in the repository's directed graph), the branch can be deleted after, and the tag will stay.

If subsequent releases are needed after x.y.0, for example, a "hotfix" branch will be created from the x.y.0 tag, cherrypick fixes in it from the master, release and tag as x.y.1.

Long story

Main branches

  • master

The master branch is where the latest development version of the software is (the "develop" branch in [SGM]). From this branch, the release branches will be created when the release process is started.

Purpose: have a central place to store the latest "in development" version of the software
Created when: N/A
Created from: was imported from SVN
Committers: all committers (as the "trunk" was on SVN), freely (no need for pull requests, no need for prior feature branches).
Commits: features, bugfixes, etc. All development.
Lifetime: forever

Release branches

  • release-x.y[.z|-milestone-t]

Check the description of the "release" branches in [SGM].

There are 3 cases when a release branch will be created:

  1. when a milestone is to be released, branch name will be release-x.y-milestone-t. When the release is done, a x.y-milestone-t tag is created on this branch and the branch can be deleted.
    Purpose: allow the other committers to keep working on master while release master is handling the release on the release branch
    Created from: master
    Created when: the release process for milestone-t is started (when the due date for milestone-t is reached)
    Committers: the release master
    Commits: only the maven release related commits. No features nor bugfixes should go in this branch
    Lifetime: from the moment the milestone-t release process is started, until it is done (a couple of hours usually).
  2. when a final version is to be released, branch name will be release-x.y. This is the branch that prepares a release, through its RC phase to final release. There will be frequent exchanges between this branch and the master, for bugfix merges. When the release is done, a x.y tag will be created on this branch and the branch can be deleted.
    Purpose: allow committers to continue developing and committing features on the master for x.(y+1) release while only bugfixes will go in the x.y final release
    Created from: master
    Created when: the release for version x.y enters the RC phase (after milestone 2 is released). We could as well postpone the creation of this branch until the first new feature needs to be committed on the master
    Committers: the release master. Also, we could allow all committers to push their bugfixes to this branch, as we were doing on SVN, to spare some time for the release master (?)
    Commits: bugfixes that should go in x.y final release, maven release related commits. No features should go in this branch.
    Lifetime: from the moment release x.y enters RC phase, until the release is done (a couple of weeks usually).
  3. when a bugfix release is to be done, branch name will be x.y.z. This is the branch where the bugfixes for the bugfix version will be applied on the released x.y.(z-1) tag and from which it will be released. When the release is done, the tag x.y.z will be created on this branch and then the branch can be deleted.
    Purpose: allow a bugfixes to be merged from master on the x.y.(z-1) tag to create a fixed x.y.(z-1)
    Created from: tag x.y.(z-1) or tag x.y if z = 1
    Created when: x.y.(z-1) is released, or when the first bug that should be included in a bugfix version is discovered (a need for a bugfix rel is noticed)
    Committers: the release master. Also, we could allow all committers to push their bugfixes to this branch, as we were doing on SVN, to spare some time for the release master (?)
    Commits: bugfixes that should go in the bugfix release, maven release related commits. No features should go in this branch.
    Lifetime: from the moment a need for a bugfix release is discovered, until the release is done (usually, it depends on the type of bugs discovered and the needs or more stable versions).

Note that the release branch created in case number 2 can be "renamed" in release-x.y.1 (case number 3 for the first bugfix release) immediately after the release of x.y.

(??) Another option is to get rid of case number 3, and keep alive release branch created in case 2 for as long as needed (and tag subsequent x.y.1, x.y.2,... on it) -- which would match the current process of having one bugfix branch alive besides the trunk. This global release-x.y branch will be deleted when the final x.(y+1) will be released.

Feature branches

  • any name besides master and release-*

Can be created by comitters to share experimental work with eachother, without committing in the master branch, or share their work with the world in situations that prevent it to be pushed on master (long feature that takes too long to be ready, commit freeze (though there should never be any commit freeze on master)). Also check the description of the "feature" branches in [SGM].

Purpose: allow a subgroup of committers to work together on a feature which will be merged later in the master, or not (it can be an experiment which turns out unsuccessful)
Created from: master or tag
Created when: whenever a dev feels the need to
Committers: all committers, and non-committers if github allows to grant rights only on specific branches
Commits: anything
Lifetime: as long as it's needed / wanted

Usecases

I want to develop and contribute an extension for XWiki

TODO: document me, and point to the contrib

I want to develop and contribute a core feature / bugfix for XWiki

TODO: document me

I need to patch an older release of XWiki and rebuild it from sources

TODO: document me

Tags:
   

Get Connected