This site is a static archive of the Aegir community site. Documentation has moved to http://docs.aegirproject.org. Other community resources can be found on the Contacting the community page.
Skip navigation

Revision of Advanced git workflow: branches and releases from Mon, 04/04/2011 - 18:46

Help

Advanced git workflow: branches and releases

Aegir development makes a heavy use of git branches to keep development stable. We use feature branches to do large development work and have release branches to keep stable releases maintained while development happen on the development branches.

1. Branch naming conventions

All branches are either development branches, stable branches or feature branches. Development and stable branches have the same naming convention: Warning: 6.x-1.x or 7.x-2.x. The only different between the two is that a stable branch is the branch where stable releases are published from.

Note: since the great git.drupal.org migration, we are back on Drupal.org and have been forced to change some of our naming convention, especially to include the core release number in the tag (so 6.x-1.x), which is a source of confusion for our provision module which supports any Drupal core version. See this issue on drupal.org for followup.

1.1. Main development branch

The main development branch is created after a fully stable release is published. For example, the 7.x-2.x branch will be created once the 1.0 release is published. It will be a development branch until it is considered feature-complete and goes through the alpha/beta/rc release cycle, at which point it will be declared a stable branch and a new development branch will be created (probably 8.x-3.x at that point).

Note that we have dropped the master branch as it is not well supported on Drupal.org for releases.

1.2. Stable release branches

Stable releases are performed from stable release branches. A branch is declared stable only after it went through the complete 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, 6.x-1.0 will come after 6.x-1.0-alpha1, 6.x-1.0-beta1, 6.x-1.0-rc1 at least, and then be followed directly by 6.x-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.

Only one stable branch is maintained at a time.

1.3. 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.

Feature branches should be based of a known stable baseline as much as possible. For example, you should branch off the last alpha release if you want to make merging with other dev branches and master easier. See this article for a thorough discussion on this practice

2. 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 6.x-x.y tag (e.g. 6.x-0.4, 6.x-0.4-alpha15 or 6.x-1.0). Those tags are usually laid on the stable branches, except for alpha/beta/rc releases which are laid on the development branch.

3. 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.

Need help?

Documentation

The notebook section provides a way for you to store and share information with your group members. With the book feature you can:

  • Add book pages and organize them hierarchically into different books.
  • Attach files to pages to share them with others.
  • Track changes that others have made and revert changes as necessary.
  • Archive books that are no longer of interest to the group. Archived books can be reactivated later if needed.

The revisions let you track differences between multiple versions of a post.