Bazaar

Bazaar is a distributed revision control system, currently developed by Canonical. More information can be found at:

• ​Bazaar Official Web Site
• ​Bazaar Official Documentation

Accessing Repositories

To get access to the bazaar repositories, please, create a ticket and attach your public SSH key. When access is granted, you can get the source out of the repository using following command:

bzr branch bzr+ssh://user@ufo.kit.edu/repo/branch

For example, to get the latest revision of PyHST from main tree, issue:

bzr branch bzr+ssh://user@ufo.kit.edu/pyhst/pyhst

If you'll prefer the version maintained by Matthias, issue:

bzr branch bzr+ssh://user@ufo.kit.edu/vogelgesang/pyhst

Read-only access (all repositories are only accessible from IPE and ISS networks, all other networks are restricted to selected public repositories):

bzr branch http://ufo.kit.edu/sources/pyhst/pyhst/

Committing changes

Any changes that you make, are locally stored with the commit command

bzr commit

which asks you for a commit message.

Similar to Git, Bazaar handles the very first line of a commit message in a special way. For example bzr log --line prints the whole log with revision number, author, date and first line. To keep things nice and tidy, this first line should summarize the commit in 50 characters or less. To increase readability of these lines you may use the <prefix>: <description> format, with the following possible prefixes:

• Fix (e.g. Fix: segmentation fault or Fix: bug #1234)
• Add (e.g. Add: web interface)
• Update (e.g. Update: version)

Because, this line is limited to only 50 characters, you can use several paragraphs divided by newlines to explain not only what you did, but more importantly why you changed something. These paragraphs must be wrapped at 72 characters.

You should definately make use of Bazaar's builtin bug-tracker support. To enable this for the UFO project add this line to your bazaar.conf (located in ~/.bazaar):

[DEFAULT]
trac_ufo_url = http://ufo.kit.edu/ufo

Now, for each bug that has an associated ticket, you can mark the fixing commit with

bzr commit --fixes ufo:123

Public Repositories

Repository	Description
framework	The stable version of UFO framework and support libraries. New versions are only accepted after thorough testing/code review.
cmake	CMake scripts to detect libraries you are maintaining.
opencl	Various CMake libraries required for UFO filters.
<user_name>	Development branches of all UFO related code belonging to the user_name.

Publishing Source

All the source code should first go to the user private repository. The repository is created with following command:

  bzr init-repo bzr+ssh://user_name@ufo.kit.edu/user_name/

The created repository will be only writable by its creator, but readable by all members of UFO project. The new repository will not automatically appear in Trac. It should be first added through the Trac configuration page. If you don't have administrative rights, you need to create a ticket.

Then, the branches are created as follows (new branches will immediately appear in Trac):

  bzr init bzr+ssh://user_name@ufo.kit.edu/user_name/branch1

After branch initialization you can create local repository. Just call 'bzr init' in root of the source folder. Files can be added with bzr add command and revision can be commited with bzr commit -m some_comment. This will work with local repository on your desktop computer. To submit a revision to the server, for public use, please issue:

  bzr push bzr+ssh://user_name@ufo.kit.edu/user_name/branch1

Alternatively, it is possible to instruct bazaar to synchronize with the server after each commit. Just bind the local branch with the server using the following command:

  bzr bind bzr+ssh://user_name@ufo.kit.edu/user_name/branch1

Publishing stable versions

After through testing, the maintainers of UFO subpackages can publish them in UFO main repository. It is accessible with the following bazaar URL:

  bzr+ssh://user@ufo.kit.edu/framework 

You can create new branches with the following command. These branches will be writable by creator only, but accessible for everybody else. Changes to these branches will immediately appear in the Trac ​source browser.

  bzr init bzr+ssh://user@ufo.kit.edu/framework/branch1

Possible workflow

There are already very good branching ​models out there. Although it's up to everyone how he will work on his personal branches, I will show how I use Bazaar to ease my life.

First of all, I import some of the written code using the steps written above.

cd project-dir
bzr init .
bzr add *
bzr commit
bzr init bzr+ssh://user@ufo.kit.edu/user/project
bzr push bzr+ssh://user@ufo.kit.edu/user/project

Then I clean the project directory and clone the committed code as a named branch and bind to the server:

rm -rf *
bzr clone bzr+ssh://user@ufo.kit.edu/user/project upstream
cd upstream
bzr bind bzr+ssh://user@ufo.kit.edu/user/project

I never work directly in the upstream branch because every commit would be visible immediatly. Therefore, I branch from the upstream branch a local branch where development happens:

cd ..
bzr clone upstream/ local

Whenever I need to work on the same project but tackling different problems, I branch from the local branch to a feature specific branch. To push my changes, I just pull (no merging needed) the changes from the local branch into the upstream branch

cd upstream
bzr pull ../local