How to work with bazaar through the GUI on Windows

Bazaar: Source Code Management System for OpenPetra

We use Bazaar as Source Code Management (SCM) for OpenPetra. Bazaar is a SCM that is classed as a 'Distributed SCM', which differs considerably from centralised SCM's like CVS. General information about Bazaar can be found here: [1].

• All our source code is hosted 'in the cloud' on Launchpad. (Launchpad is a software development platform provided by the company Canonical [who develop Ubuntu and Bazaar]).
• We are setting up Bazaar to use a 'Shared Repository' on our development PC's.
  • A developer's local repository can contain as many 'branches' as he/she wants and they will get merged into the main development line ('trunk') when work on them has finished.

Alternative: use Bazaar from the command line

If the GUI is not your prefered way of doing things, please see How to work with bazaar on the command line

Download Bazaar for Windows

You find the downloads for Bazaar for Windows here: http://wiki.bazaar.canonical.com/WindowsDownloads

We use the Standalone 2.4.2 Stable Release for OpenPetra development. Do not download a newer release as a Bug on Launchpad's servers prevents us from using newer releases!

The download includes the core Bazaar distribution and several GUI's for Bazaar. We recommend to not install TortoiseBzr initially if this is your first experience with Bazaar - it adds more ways to work with Bazaar, which is good, but it might confuse people who are new to Bazaar.

We have noticed that the German translation is not complete at all, and on German Windows systems the GUI is quite mixed up with several languages. Solution: delete all but the en locale directory from C:\Program Files\Bazaar\locale. If the local-folder is not available on your computer you can also set the LANG environment variable to the required language code.

See also Visual Tour of Bazaar Explorer on Windows.

If you still get plink console windows with bazaar, have a look those instructions!

Setup your environment

Start Bazaar Explorer from the Start menu.

Go to Settings|Configuration|User Configuration to set your user name and email address:

Set up the bug tracker integration as follows:

Here is the URL for easy copy&paste: https://tracker.openpetra.org/view.php?id={id}

The commit dialogue of Bazaar Explorer allows one to specify a bug that was closed with the commit. One needs to prefix the bug number with 'op:' (e.g. 'op:170' if Bug #170 is closed in the openPETRA bug tracker).

If you prefer to use WinMerge for showing the diff of files, you can configure it in the same window as well:

To setup KDiff3 (http://kdiff3.sourceforge.net/) as your Merge tool, configure it in the same window:

For Copy&Paste: "C:\Program Files (x86)\KDiff3\kdiff3.exe" --output "%r" "%b" "%t" "%o" (For newer versions of Bazaar (from 1.2.2 on) add a new merge tool with the following command: "C:\Program Files (x86)\KDiff3\kdiff3.exe" {base} {this} {other} -o {result})

Line Ending issues

To avoid problems with the line endings, and the code generators, in Bazaar Explorer go to Settings/Rules and insert the content listed at below:

[name *.cs]
eol = native
[name *.csproj]
eol = native
[name *.sln]
eol = native
[name *.yaml]
eol = native
[name *.xml]
eol = native
[name *.config]
eol = native
[name *.build]
eol = native
[name *.js]
eol = native
[name *.html]
eol = native
[name *.htm]
eol = native
[name *.sql]
eol = native

See also http://doc.bazaar.canonical.com/development/en/user-reference/eol-help.html

Working with trunk and Branches in Bazaar

trunk

'trunk' is the main branch of the repository.

• Only certain members of the core development team can commit to trunk and merge changes from a branch into trunk.
• For other developers it makes sense to checkout trunk for readonly access to be able to compile the latest version from the repository.

Branches

We have an agreed procedure in place to create a Branch for each bug or feature from Mantis that takes more than 3 hours to develop, including the time needed for coding and testing. Only small bugs and not so complicated fixes can be committed directly into trunk.

Once the work on a Branch has finished a member of the core development team that can merge changes from a Branch to trunk needs to be contacted to get that Branch merged into trunk. (Work is not considered finished until a merge from trunk and an Uncrustify operation has been carried out as the final steps in your work - your branch will not be accepted for merging into trunk if this hasn't happened!)

Local Repository Format

Bazaar offers several formats in which the local Bazaar repository can be built. With a 'Shared Repository' (setup described in section Create a local repository) one can check out several branches (and trunk which is just a special branch) into separate Working Trees.

Create your own branch

Every developer needs to create a free account at http://launchpad.net, for hosting their own Branches there.

For creating a new branch, you need to follow the following steps...

Setup your Launchpad account

You only need to do this once!

• First get an account on Launchpad, which is a service provided by the company Canonical, who develop Ubuntu and Bazaar: https://login.launchpad.net/+new_account
• Create a public and private key on launchpad. This is explained here.
  • It is important to execute pageant and to load the private key into pageant as otherwise the establishing of a SSH connection to the Launchpad server will fail!
• Use plink to verify that the SSH connection to Launchpad is working
  • Open a command-line window and change to the Putty directory (probably C:\Program Files\PuTTY or C:\Program Files (x86)\PuTTY).
    • To test directly with your private key, type in the following command: plink.exe -v -ssh -noagent -i <private key path and file name> <Launchpad userid>@bazaar.launchpad.com. Example: C:\Program Files\PuTTY>plink.exe -v -ssh -noagent -i C:\PrivateFile\bazaar.ppk myuserid@bazaar.launchpad.net
    • To test using pageant, type the following: plink.exe -v -ssh -agent <Launchpad userid>@bazaar.launchpad.com
    • In both cases a good response should look similar to the following. Just hit enter in response since we don't need to actually connect.

Looking up host "bazaar.launchpad.net"
Connecting to 91.189.95.84 port 22
Server version: SSH-2.0-Twisted
Using SSH protocol version 2
We claim version: SSH-2.0-PuTTY_Release_0.62
Using Diffie-Hellman with standard group "group1"
Doing Diffie-Hellman key exchange with hash SHA-1
The server's host key is not cached in the registry. You
have no guarantee that the server is the computer you
think it is.
The server's rsa2 key fingerprint is:
ssh-rsa 1024 9d:38:3a:63:b1:d5:6f:c4:44:67:53:49:2e:ee:fc:89
If you trust this host, enter "y" to add the key to
PuTTY's cache and carry on connecting.
If you want to carry on connecting just once, without
adding the key to the cache, enter "n".
If you do not trust this host, press Return to abandon the
connection.
Store key in cache? (y/n)

• Following is an example of an error.

Looking up host "bazaar.launchpad.net"
Connecting to 91.189.95.84 port 22
Failed to connect to 91.189.95.84: Network error: Connection reset by peer
Network error: Connection reset by peer
FATAL ERROR: Network error: Connection reset by peer

Here is one list of possible connection errors: http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter10.html

• You need to tell your local Bazaar installation your Launchpad username.
  • Failing to do so results in an error message: "bzr: ERROR: Connection error: Unable to authenticate to SSH host as xxx. supported auth types: ['publickey']" where xxx is in the format username@bazaar.launchpad.net!
  • This can be done in the Bazaar Explorer GUI: Menu Bazaar / All Commands. The 'Run bzr command' Dialog will be opened (see screenshot below).
  • 'Working directory' can be any valid directory, it doesn't matter.
  • Select Category 'launchpad'
  • Select Command 'launchpad-login'.
  • Enter your launchpad id in the 'Options and arguments for command' TextBox.
  • Click 'OK'.
  • This process only needs to be done once.

Create a local repository

You only need to do this once!

Now you should configure a directory where you will store all your branches. Go to "Start a new project", and click on "Initialize". Make sure to select the options "Shared repository" and to tick the option "Create parent directories of location, if required". The option "Branches in the repository will default to not having a working tree" should not be ticked.

In the example screenshot below I have chosen the directory <My Documents>/openpetra/bzr/. However,

• Especially when using Windows 7 it is recommended to create the repository in a local directory (e.g. C:\openpetraorg\) and not one on the network as otherwise compiling with NAnt can give problems. Compiling from a network drive gave the following error on Windows 7:

System.Security.SecurityException: Request for the permission of type 'System.Security.Permissions.FileIOPermission, mscorlib, Version=2.0.0.0, ... failed

• By using a directory near the root of a local drive (e.g. C:\openpetraorg\) you are less likely to run into problems with path+file combinations exceeding 250 characters, which is a hard limit on Windows operating systems. (None of the OpenPetra path+file combinations exceed that if you go with this example.)

You might be asked, if you want to create a new "hat". Just say yes. An explanation can be found here: http://wiki.bazaar.canonical.com/BzrExplorer#hats

Create a new branch on Launchpad

Make sure you have started pageant with your private key, otherwise your connection to the bazaar server will fail. To do that, you just need to double-click on the .ppk file, which is the private key file which you saved when you created the SSH key for developer access.

Open Bazaar Explorer, and select Bazaar / Start / Branch from the menu.

The source will be: lp:openpetraorg

The destination should be an URL in this form: lp:~LAUNCHPADUSERID/openpetraorg/BRANCH_NAME

Naming convention for OpenPetra branches:

• They start with 'dev_'
• followed by the <Mantis Issue Number> that is being addressed in this branch - as a seven-digit number (fill up with leading 0's)
• followed by '_'
• followed by <keywords to describe the issue>.

Examples: dev_0000167_import_cc_hierarchy or dev_0001065_Validate_Subscription.

Note: You could also create branches that are unrelated to the OpenPetraOrg project: eg. lp:~tpokorra/+junk/BRANCHNAME.

Checkout the code into a working tree

After creating the branch on Launchpad you need to download this branch into a separate directory in your own local repository. This can be done by selecting in the menu Bazaar | Start | Checkout.

Use the URL of your branch:

lp:~LAUNCHPADUSERID/openpetraorg/BRANCH_NAME

The destination for the checked out trunk as shown in the screenshot above is:

<My Documents>/openpetra/bzr/work

However, you need to make sure that the destination folder is inside your local repository directory which you have created earlier (in step Create a new branch on Launchpad)!

Alternatively, for just browsing the source code online one can go to https://code.launchpad.net/~LAUNCHPADUSERID or https://code.launchpad.net/openpetraorg (=trunk).

After the checkout has finished, click on Refresh in the Bazaar Explorer, and then double-click trunk to get to the view of the current working tree:

Now you can edit the code and add functionality. Please make sure to add as well your OpenPetra.build.config file to the branch (if you have one) and create the Database with nant. (without those steps the server won't start) (see also Setup_of_Development_environment#initial_steps)

--Pokorra 07:31, 16 March 2012 (UTC) Do NOT add your OpenPetra.build.config file to your public branch at Launchpad, since it may contain your database password etc. Also it will cause problems with merging your branch into trunk. If you have a private branch, ie. it is on your own bazaar server, and it only contains adjusting changes for a production system, then you can call your config file OpenPetra.build.config.my and add it to that private branch.

Commit added and modified files

The Bazaar Explorer should look similar to this for your working tree:

This screen gives you access to operations like:

• Add: add new files
• Rename: rename files in the working tree control
• Commit: commit local changes to the repository.
  • Please enter the Mantis numbers of the bugs you have fixed (in edit field Fixed bugs), in the format op:<mantis number>, eg. op:123 op:124
  • it is recommended always to commit to the central repository, and to avoid local commits

Alternatively, you can work with Tortoise Bazaar as well:

Rebase a branch / Merge from trunk

You should rebase your branch regularly, so that the changes happening in trunk are flowing back into your branch.

You need to click on Merge, and if there have been changes merged into your branch, you will need to Commit as well.

It is highly recommended to first commit all your own local changes, before doing a merge.

Merge to trunk

If you want your changes to be merged into the OpenPetra trunk, use the link Propose for merging on your Launchpad code page. It is recommended to have small branches for each feature that you want to go upstream. You will not be able to reuse a branch, after it has been merged into openpetra trunk, since we want to avoid criss cross merges etc.

Certain members of the core team with write permissions on trunk will switch to trunk, and then do a Merge from the branch. They will resolve conflicts if there are any, and do a Commit.

Resolve conflicts

This example will show you how to resolve a conflict.

The situation: the file Gift.Importing.cs has been edited both in trunk and in the dev branch. We switch to the dev branch, and select Merge from bzr+ssh://bazaar@bzr.openpetra.org:2208/openpetra/trunk/

This is how it looks in Bazaar Explorer:

Now go in the menu to Bazaar > Work > Resolve Conflicts. You will get this screen:

If you have configured KDiff3 right, you should be able to double-click the conflict files and see them in KDiff3. This only works for files that have text conflicts. For files with content conflicts, you need to manually compare the .BASE and .THIS or .OTHER file with the current file.

In KDiff3, you have 3 columns:

• The left column (A) is the BASE version. This is the version before all changes happened, the common source of the branches.
• The center column (B) is the THIS version. This is the version that you have last had in your branch.
• The right column (C) is the OTHER version. This is the version coming from trunk, in our example.
• The file at the bottom is the resulting file. You can go through the conflicts, and select if you want to select the version from A, B, or C, or you can modify it yourself.

Make sure that the line end style is set to DOS (and not to UNIX).

You might also want to right click the conflicting file in the Explorer, and select the Log, this will you to see what happened to the file, and how the changes got into that file, by looking at the diff of each commit.

After you have fixed the bottom file, saved it and closed KDiff3, select "Mark as resolved" in the conflicts list window, when right-clicking the conflict file.

Frequently asked questions

Please go to Notes_about_Bazaar#Frequently_asked_questions to see our FAQ for bazaar.