You are here: Home / Devel Env / Bazaar / Particulars

Particulars of the use of bzr for ABINIT 

The ABINIT Central Archive (aka "The Forge")

Before being officially released, all contributions have to pass through the ABINIT Forge, which is a collection of Bazaar repositories, one per developer. Each repository contains many branches, each labelled following the characteristic of a particular version of ABINIT (concerning either development or production releases, e.g. 6.6.1 for production, 6.7.0 for development), as well as the usage type : public branches following strict naming conventions, and corresponding private branches . There might also be training branches and additional private branches, that would not correspond to public ones.

Branch names

A public branch name will be of the form



x is a major version number, 6 for the 2 or 3-year period started in Summer 2009 ;

y is a minor version number, even for production branches, and odd for development branch ;

z is an integer number, typically between 0 and 3 or 4, changing typically once a month.

A private branch is automatically created for each existing public branch, replacing "public" by "private" in the name. The creation of training branches, or additional private branches, has to be requested to a forge maintainer. A training branch is created for the new user's of bzr, or might be requested by other users.


In addition to the repository named after the login of each developer, there is a reference repository, codename trunk, from which all the other ones are initialised, and to which all merges converge. All committers are supposed to keep their branches in sync with the corresponding ones in trunk when requested to by the gatekeeper. All merges to trunk are performed from the public branches only.

All committers are kindly requested to use their public branches wisely. Each time they commit there, a nightly build followed by a run of the test suite is automatically performed. A report is then sent to the gatekeeper who decides whether the branch involved may be merged into the trunk.

A private branch is to be used as a "back-up" of the branch on the local machine of the developer. Committing to a private branch will not trigger a nightly build, and the gatekeeper does not care about private branches.

A training branch, on the other hand, is between private and public : committing to a training branch will trigger the nightly build, but the gatekeeper does not care about training branches.


Access to the ABINIT Forge is possible through SSH only, and may be activated upon request to the project leader. Using the bzr-over-ssh protocol is highly recommended for performance reasons, while sftp will work very slowly but fine. The full URL of a branch reads:


where each repository is named after the login of its owner. For instance, to access Matteo Giantomassi's public development branch of ABINIT 6.6.1, one will use:


In order to facilitate the downloading from / uploading to the forge, a helper script has been made available and may be found with its documentation in the developers/bzr_helpers/ subdirectory of the ABINIT source tree.

Typical workflow

When a new version of ABINIT is started (typically once a month), all the registered developer have their private and public branches started on the repository.
The repository is not aimed to support the development effort. The developer must create a local repository on his/her development machine. For this purpose, he/she must use his private branch.  Let's work out the example of branch 6.6.1 of gmatteo. The first command to be issued (mandatory when a new version is started) is :

bzr branch bzr+ssh://

After some time, a local directory entitled 6.6.1-private is created. The developer now uses that directory as his/her working directory.
When appropriate he/she will commit his development. In order to do this :

  1. Check the working tree with bzr status.
  2. Process files marked as unknown. Go back to step 1 until no file is marked as unknown.
  3. If your changes are numerous, write a changelog (or you will input one comment line at the time of the next command )
  4. bzr commit --strict [-F logfile] (use the -F option only if your changelog is in a file).

Make sure that the EDITOR environment variable is set before committing.

Thus :

bzr commit --strict

This command does not store your modifications on the ABINIT repository, but only in the local repository. You can indeed work locally, with the advantages of a control version system. From time to time, especially when your development has reached a noticeable point, your might want to store the current version on the ABINIT repository. For this purpose, you have to issue, after the commit :

bzr push bzr+ssh://

This provides a remote back-up of your development. Although your private branch on the repository can be seen by all ABINIT developers, e.g. using Browse Forge, nobody is supposed to merge the content of your private into his/her own branch. Indeed, although it is supposed that you have already gone through some testing before committing and pushing, your private branch is not tested systematically. By contrast, your public branch will be tested.

In order to store your development in your public branch, issue (after the push to your private branch) :

bzr push bzr+ssh://

The availability of some development in your public branch means that you think that your development is ready to be used by others, and in particular, that it is ready to be tested then merged in the trunk. Automatically, the content of a public branch that has been modified is tested, see the tables in some subdirectories of Nightly builds . You will receive a mail indicating whether the test succeeded or failed. In the first case, others (including the trunk) can merge your branch in theirs. In the second case, you are supposed to try to fix the problems. Perhaps you will need some help from the maintainers to achieve this.

Merging the trunk in your branch

From time to time, typically once per week, there will be a request to merge the trunk into your branch, before continuing your development. In this case, first lead your developments to the point where they pass the nightly tests. Then, issue, in your working directory (no other modification after the last commmit) :

bzr merge bzr+ssh://

where you have to use the proper x.y.z label (e.g. 6.6.1 for the above-mentioned example) . Solve the possible conflicts, then commit to your local repository, before starting to do any new development, and possibly push to the ABINIT repository (private and possibly public).

You might be proactive, and merge the trunk into yours regularly. This is an excellent strategy, to avoid potential conflicts due to development by other ABINIT developers.

The end of the development of a branch

At some point, you will receive a mail, stating that some branch will soon be frozen. Such deadlines are also announced in the Planning of merges . This means that, beyond the freezing point, the modification you might store in your public branch will not be merged anymore in the trunk. Note however, that the private and public branches will continue to be available for your work.

When a freezing is announced, try to finalize your development, and push to the corresponding public and private branches your development. You might continue to use these beyond the freezing point, but in this case, you will have to merge your latest modifications in the newly created branches, by yourself.

As an example, suppose the branch 6.6.1 has been frozen, but you have continued to develop inside your private branch, and you have committed your latest developements. Then, the branches 6.6.2 are initialized, and the announcement comes, that you can use them for your development. Then, issue :

bzr branch bzr+ssh://

cd 6.6.2-private

bzr merge bzr+ssh://

possibly solve the conflicts, and issue

bzr commit

bzr push


then, continue to develop, as usual ...

Development branches and bug fixing branches

In order to secure the delivery of some production versions of ABINIT, several versions are active at each time, usually two. One of these versions is for bug fixing only, while the other is for further development. Indeed, this is needed to avoid the introduction of bugs that is associated with all development activities ...

Supposing that versions 6.6.1 and 6.7.0 are under development, the first for bug fixing and the second for further development, ideally the following procedure must be followed when you fix a bug :

  • fix this bug in your 6.6.1-private branch, then commit, push, and push in your 6.6.1-public branch
  • after the nightly tests, merge the content of your 6.6.1-public into your 6.7.0-private branch

However, if you want to act faster, you can directly merge the content of your 6.6.1-private branch into your 6.7.0-private branch, without waiting for the nightly results. Well, it is your own organization in your own branches ...

NOTE however : do not fix the bug in your 6.7.0 branch, followed by merge of your 6.7.0 into your 6.6.1 . This might corrupt irremediably your 6.6.1 branch !