Last updated May 19, 2013.

Feature branches

In a distributed version control system workflow, like Git, it's common to spin off separate branches for features, for bug fixes, or heck, just because you feel like it. On drupal.org's Git server, there are no branch/tag naming restrictions at the version control system level. You are free to name your branches whatever you like for your day-to-day work.

awesome-new-feature, experimental-redesign, performance-bugfix are all acceptable branch names.

Git's default master branch should not be used and no downloadable releases can be tied to that branch. Master branch cleanup information here. Use 6.x-1.x, 7.x-1.x or 8.x-1.x as your main development branch (see below).

Quick Aside for new Module Developers

If you are new to Git and/or module contribution, please see Creating a branch or tag in Git. If you are looking to publish your release, please view "Creating a project release" for more information.

Release branches

While there are no naming restrictions for branch and tag names in Git itself, when you want to make your changes available for download by the community on Drupal.org, branch and tag names need to follow a convention.

This naming convention is important for Drupal's community infrastructure, such as Update Status and the testing bot. Note that release tags must be made on the properly named release branch. Any tags/branches you intend to translate into actual downloadable releases on Drupal.org (as tarballs and zip files) need to follow this convention:

Branch name Branch Description Downloadable release
7.x 7.x-dev release (core) drupal-7.x-dev.tar.gz,
drupal-7.x-dev.zip
7.x-1.x 7.x-1.x-dev release (contrib) myproject-7.x-1.x-dev.tar.gz,
myproject-7.x-1.x-dev.zip
7.x-2.x 7.x-2.x-dev release (contrib) myproject-7.x-2.x-dev.tar.gz,
myproject-7.x-2.x-dev.zip

Packages for development releases are only created twice a day, so there may be as much as a 12 hour delay.

Tag name Tag Description Downloadable release
7.0 7.0 release (core) drupal-7.0.tar.gz,
drupal-7.0.zip
8.0-beta1 8.0-beta1 release (core) drupal-8.0-beta1.tar.gz,
drupal-8.0-beta1.zip
7.x-2.3 7.x-2.3 release (contrib) myproject-7.x-2.3.tar.gz,
myproject-7.x-2.3.zip
8.x-2.0-alpha6 8.x-2.0-alpha6 release (contrib) myproject-8.x-2.0-alpha6.tar.gz,
myproject-8.x-2.0-alpha6.zip

There is a five minute delay before the creation of release packages.

Important note about release tags: Only the following labels, lowercase, can be used in release tags:

  • unstable
  • alpha
  • beta
  • rc

Read more about the distinctions between Alpha, Beta and RC here.

7.x-1.0-rc1 will appear as a valid tag, but the following will NOT:

  • 7.x-1.0-release1 (wrong word)
  • 7.x-1.0-rc (doesn't end in a digit)
  • 7.x-1.0-UNSTABLE1 (uppercase)

Git naming conventions compared with CVS

On the old drupal.org CVS servers, you were restricted to branch names meeting a specific pattern (DRUPAL-6--2, DRUPAL-7--1, and so on). If the branch name didn't match the pattern, it was rejected. This was nice for enforcing consistency in our diverse contributor community, especially considering the limited branch and merge capabilities of CVS.

Here's how old CVS branch and tag names map to Git branch and tag names:

Branch Description CVS branch name Git branch name
7.x-dev release (core) DRUPAL-7 7.x
7.x-1.x-dev release (contrib) DRUPAL-7--1 7.x-1.x
7.x-2.x-dev release (contrib) DRUPAL-7--2 7.x-2.x
the default branch HEAD master*

* Note: Git's default master branch can be used, but no downloadable releases can be tied to that branch.

Tag Description CVS tag name Git tag name
7.0 release (core) DRUPAL-7-0 7.0
7.0-beta1 release (core) DRUPAL-7-0-BETA1 7.0-beta1
6.x-2.3 release (contrib) DRUPAL-6--2-3 6.x-2.3
6.x-2.0-alpha6 release (contrib) DRUPAL-6--2-0-ALPHA6 6.x-2.0-alpha6

So in summary, compared to CVS, Git will give you the freedom to branch early and branch often while in development, and use much less obtuse names for your tags/branches when you're ready to release. Yeehaw!

@todo: Delete this section of the page by July, 2011, as no one will care about CVS by then Delete this section when no one remembers anything about CVS. These messages serve as a reminder of CVS's existence thereby negating their purpose.

Comments

Please don't remove comparison with CVS version.
Drupal developers may not use CVS anymore, but there may still be websites that use CVS versions out there.
CVS comparison information should still be available for maintainers when transitioning these sites.
In any case I don't see this section becoming obsolete as soon as july 2011!

I agree. What's the harm of leaving this up?

-Karlheinz

This might not be the place to put it, but I don't know which page to pinpoint.
Could instructions be put up for contrib developers, so they have the same strategy used as in core. E.g. 8.x is now HEAD, no master branch.
By default git creates a master branch for local repos and no branch for bare repos, which means that you need to delete your local master branch or rename it.
Also instructions on how you can change the remote HEAD pointer would be handy.

I believe these are the instructions for that. Moving from a master to a major version branch

If git branches are called e.g. A.x-B.x, then the sudden appearance of -dev in the "branch description" and the zipfile name can be confusing: I've just had to iron this out in the office.

Going forwards, it'd be good if we could drop the whole -dev thing altogether. Or add it to the git branch naming convention too, if we really want it. Right now it makes it look like there are two branches for each actual single A.x-B.x branch.

(I appreciate these naming conventions have historical weight too, and we need to clarify especially for people coming from CVS, when the branch name was nothing like the branch description; but if anything the close similarity in git is more confusing!)

--
J-P Stacey, freelance Drupal developer | www.jpstacey.info

Is there a code that prevents the update?