Aegir development makes a heavy use of git branches to keep the main branch stable. We use feature branches to do most development work and have release branches to keep stable releases maintained while development happen on the main (and dev) branches.

Branch naming conventions

Warning: this documentation was written before the great git.drupal.org migration. Since we are back on Drupal.org, we may be forced to change some of those, as the standard to create release nodes now includes the supported core version (so 6.x-1.x), which is a problem for our provision module which supports any Drupal core version... See this issue on drupal.org for followup.

Main development branch

master is always the main development branch. Think of it as CVS HEAD. Most commits should go through that branch before hitting a stable development branch. When you commit there, you make everyone suffer, so unless you are confident your change needs to be in the mainline, you are likely to want to use feature branches (below).

Stable release branches

Stable releases are performed from stable release branches, which are named provision-1.x or hostmaster-1.x. Commits to those branches should be first be done on the master branch (if possible) for testing and them merged (git cherry-pick) into the stable branch.

Those branches are created from the master branch after a thorough alpha/beta/rc release cycle (see release process for more information). Once the branch is declared stable, new releases are quickly done as "hotfixes", without intervening alpha/beta/rc releases. So for example, provision-1.0 will come after provision-1.0-alpha1, provision-1.0-beta1, provision-1.0-rc1 at least, and then be followed directly by provision-1.1.

Releases on the same stable branch are API-compatible with each other (so 1.1 is compatible with 1.0). The upgrade path is supported between major stable releases (so you can upgrade from 1.0 to 1.1 or 2.0).

Special case: during the 0.x release cycle, releases were not API-compatible with each other, ie. 0.4 was not compatible with 0.3, and you could barely upgrade from 0.3 to 0.4. However, this may change after the 0.4 release, and we'll consider the 0.x API stable as we focus on the 1.0 release, and further releases will be hotfixes on top of 0.4 (so 0.5 will immediately follow 0.4).

Feature branches

More complex development goes into development or "feature" branches, to avoid making master too unstable. Feature branches must be prefixed with "dev-" and use the issue number (if available or relevant) and a short name. So for example, there could be work on a dev-12345-mybug branch or dev-dns branch for a larger feature (DNS, in that case) which doesn't fit in a single issue.

Development branches should be based of a known stable baseline as much as possible. For example, you can branch off the last alpha release if you want to be certain you have a sane environment (see this article for a thorough discussion on this practice). Since the master branch is usually fairly stable, you can usually keep that as a baseline, but keep in mind it will make merging with other dev branches more difficult as you will start from different baselines and therefore merge unrelated commits.

Tag naming convention

Every release is tagged with a aegir-x.y tag (e.g. provision-0.4, hostmaster-0.4-alpha15 or provision-1.0). Those tags are usually laid on the stable branches, except for alpha/beta/rc releases which are laid on how this works.) So if a tag named provision-0.4.0 is pushed, the master branch.

CVS and git history

The CVS tags and branches are still accessible in git and will be kept there for posterity. They respect the traditional Drupal.org naming convention.

They have also been converted to the new git.drupal.org conventions during the great git.drupal.org migration.

Since that migration (february 2011), history has been rewritten to clean up the authors in the history.