This document contains a series of Bazaar VCS command examples that project maintainers can use to maintain their projects. Note that this document covers modules, but themes, theme engines, and translations are essentially the same. If you have problems or questions, please review the Bazaar FAQ to see if your question is answered there.

NOTE: if you are new to Bazaar and how Drupal.org uses it, you should follow more detailed instructions for Starting a new project and to Manage a project. This document provides very little context and assumes you know what you are doing.

There is a video about creating a new release that shows some of the steps on this page, specifically it applies a patch, commits the change, tags the release and then makes a new release node.

Before you start

Before you get started, you really should understand some basic concepts about Distributed Version Control Systems, of which Bazaar is one. Please read the Bazaar Introduction and make sure you have a basic understanding before proceeding, particularly pay attention to the concepts of branches and tags.

Take some time to figure out the directory structure for your module. Renaming files in Bazaar is easy, and moving around directories is really easy. If you have your directories structured and files named how you want them before your first Bazaar commit, you will save yourself very little time.

When your module is ready for release, you'll need to apply for a Bazaar account and upload your SSH public key. Also, note that you will need to create your project page on drupal.org before you start working with Bazaar. Check the step-by-step guide to creating new projects for more information.

Basics

Identifying yourself with Bazaar

if you have not already done so, upload your SSH public key to your user profile.

The first time you use Bazaar on a computer, set the name you want associated with your changes:

bzr whoami "FirstName LastName <email@example.com>"

Adding a new module with Bazaar

First, create a directory on your computer and put the module files in it.

From within that directory, run:

bzr init
bzr add
bzr commit -m "Initial commit."
bzr push --create-prefix bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/trunk
bzr bind :push

TODO: We can drop --create-prefix if we create the MODULE-NAME directory for users when a project page is saved.

Saving changes to your module

Bugs and features are tracked in your project's issue queue. It is customary in the commit to reference the node ID of the issue where the bug/feature request was raised, and mention any contributors who helped with the code. After making the changes in your local repository, you need to commit them to the Bazaar repository:

bzr commit --fixes=12345 -m "username: Brief description of changes."

Obtaining latest changes

Both before you begin editing and before you save your changes, it's a good idea to grab the latest changes from Bazaar with the update command:

bzr update

The bzr update command updates your local copy to the current state of the repository, and you can run it from the top level of your local copy or anywhere else. It always updates the entire local copy.

Removing files from Bazaar

While you cannot remove existing releases or actually remove files from Bazaar, it is possible to remove files from a branch. Sometimes a newer version of a module doesn't require a certain file anymore. If this file is foo.bar.inc, you need the following command to remove it:

bzr remove foo.bar.inc
bzr commit -m "some sort of a message as to why you removed the file"

Like bzr add, bzr remove tells Bazaar you want to remove the file, and it isn't actually removed on Drupal.org until the bzr commit.

Branching and tagging

TODO: This section could also be written with shorter commands but the requirement of having a checkout. Better or worse?

Bazaar allows you to keep different versions of your code active on different branches, and to tag different versions of your code. Drupal modules use Bazaar branches and tags in very specific ways, which are described fully on other pages:

The sections below cover the Bazaar commands used for branching and tagging, and assume you have already figured out why you are branching and tagging, and what branch/tag ID you want to use.

Before branching or tagging

If you have just made the initial commit to a new module, you should have created a project on drupal.org before you started. If you didn't, do that now, before before proceeding with creating a branch or tag.

Before you enter the command to create a tag, verify that the directory you're about to tag has the correct version of your code in it, that the code has been committed and that you are on the correct branch.

Branching for a specific Drupal core version

Branching indicates the code's compatibility with Drupal core. For more information on when to branch and why, read the overview of contributions branches and tags documentation.

For example, if you want to create a branch called "DRUPAL-6--1", you would use the following command:

bzr branch bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/trunk bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/DRUPAL-6--1

Once you have created the branch, assuming you now want to work with that branch (modify code and check code in), you need to check out that branch. To do that:

bzr checkout bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/DRUPAL-6--1

You can go back to using the trunk branch by issuing this command:

bzr switch bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/trunk

Also, you may find it helpful to keep one local directory pointing to the trunk branch, and other local directories pointing to each of your other branches. That way, you can have copies of each branch available at all times. To create a new local directory on a particular branch, use the CVS checkout (co) command:

bzr checkout bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/BRANCH-NAME new_local_directory_name

Creating an official release

Once your module is stable, it's time to create an official release for it. Just as Drupal comes out with 5.0, 5.1, and such, you can (and should!) do this with your module. You do that by tagging your code.

Assuming you are already using the correct branch (see above), and that all of your changes have been committed, you can tag your code with DRUPAL-6--1-0 (the correct tag for the 6.x-1.0 release) with the following commands:

cd contributions/modules/example
bzr tag DRUPAL-6--1-0

The bzr tag command tags all of the files in your project as belonging to a particular release. Note that you can tag a release as a "beta" by adding a suffix to the tag. For example:

bzr tag DRUPAL-6--1-2-BETA1

After tagging the module for your release, you also need to create a release node for it, so that it shows up in the list of downloads on your project page on drupal.org.

Note that normally, releases should only be made after major bug fixes or security patches; not for minor bugs like whitespace fixes, small text fixes, and so on.

NOTE: If you find a security bug, please report the vulnerability to the Security team and do not commit fixes for the security vulnerability until told to do so by the security team. This gives the security team time to send an announcement out via the security newsletter and to make sure that the proposed fix for the bug actually fixes the security vulnerability.

Branching for new development versions of your module

Once a stable release of a module is created, you may want to continue to add features, leaving the original release of your module intact.

To create a branch for a new major version of your module (for example, version 2.0 of the Drupal 6.0 compatible version of your module), use the following commands:

bzr branch bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/trunk bzr+ssh://USERNAME@drupal.org/contrib/modules/MODULE-NAME/DRUPAL-6--2

TODO: We may actually want to branch from the old major release instead of trunk in Bazaar.

Eventually, when version 2.0 is ready to be released you would tag the 2.0 version using the following commands:

cd DRUPAL-6--2
bzr tag DRUPAL-6--2-0

You may want to edit your project node and click the 'releases' subtab and bump the major release also.

Creating a development snapshot release of your module

In order to allow people to test your module while it is in development, you may wish to make a development snapshot. This will create a "dev" snapshot which will always point to the newest version of the module in a particular branch.

To do so, make sure that the module is branched for the appropriate Drupal core version, and then create a release node pointing to that branch, rather than a specific release tag.

Note: Developer snapshots are only generated 2 times per day.

Deleting a tag

Note that it's a very bad idea to delete a branch once you have started committing changes to it.

Release nodes on drupal.org are typically never deleted. For more info about this please read the handbook page on Fixing releases. If you believe that it really is necessary to delete a release node, please submit an issue to the drupal.org webmasters queue, and one of the site maintainers will be able to delete the release node from drupal.org, but only if there is a very good reason for it.

To delete a tag that was created in error, use the command:

bzr tag --delete DRUPAL-5--1-0

If you need to delete a branch that was created in error, use the command:

bzr ???? DRUPAL-5

TODO: Deleting a branch will require some thought.

Saving changes to multiple branches

When you commit bug fixes, if they span more than one version, they need to be committed to each affected branch.

So for example, if you have a 4.7.x-1.x and 4.7.x-2.x and 5.x-1.x version of your module, changes that affect both the 4.7.x and 5.x versions need to be committed to the DRUPAL-4-7, DRUPAL-4-7--2, and DRUPAL-5 branches.

TODO: In Bazaar, this should be handled through the excellent merge support.

Comments

David Strauss’s picture

While this represents the closest possible copy of what we do now, I think it would be prudent to make branch management part of the web interface and not allow users to create or delete branches on Drupal.org from the shell client.

pwolanin’s picture

deleting files can be even easier I think. If I just delete a normal file within the working director, bzr status reports it as deleted.

Also, bzr delete with no argument should remove from bzr all files that are missing form the working copy.

probably using is as described is the safest, but useful to know about these other options.

---
Work: BioRAFT