bzr howto for the MatPLC project

Setting up

First of all, you have to tell bzr your name and e-mail address. This will be used on log messages and code histories to identify your contributions.

bzr whoami 'Your Name <email@example.com>'

You only need to do this once - bzr will remember it.

Getting the code

bzr branch http://mat.sourceforge.net/release/coruscant mat-coruscant
bzr branch mat-coruscant mat-devel
cd mat-devel
bzr pull --remember URL

where URL is another developer's branch. This will: (1) get coruscant, (2) make a devel branch for you and (4) update the devel branch to the given URL.

Please use this procedure rather than directly branching off a developer's branch. For one thing, it'll be a lot faster, because SourceForge has a bigger pipe.

Where to bzr pull from

• one of the main development branches

  You might branch off a developer that's closer to you institutionally, by language, interest or time-zone.

  • Jiri's dev branch: http://www.baum.com.au/~jiri/mat/mat-main
  • Juan's dev branch: http://www.acelab.com/mat/mat-ace
  
  
• the branch of a particular feature

  If a developer is working on a major feature, they may invite others to take a look (or even collaborate); see discussion of the feature on the mailing list or ask the developer in question.
  

• the coruscant release branch

  If you want to base your development on coruscant (eg for an application, rather than MatPLC development per se), simply skip the last step (bzr pull) in the above description and just start using your mat-devel branch.

• internal company branches

  A company or other group may also have internal branches, only publishing features back to the MatPLC project at the end (or not). bzr allows for such internal development, including merging new versions of the MatPLC into the internal development and, if desired, the orderly merging back into the main line MatPLC development (even if some time has passed).
  

Keeping up to date

bzr merge [OTHER]

A "pull" is simpler, but only works if you haven't made any changes (or if they've been already merged on the other end). This means that either it will work completely or not at all - you can never get a conflict from a simple "pull".

If you have made changes, you have to use "merge", fix up conflicts (if any) and then commit.

OTHER is the URL of another branch; if omitted, it defaults to the URL used with --remember or the original bzr branch. It can also be the filename of a "bundle" file (see "publishing your changes", below, for how to create such files).

Starting work on a new feature

bzr branch SRC DEST

Here, SRC and DEST will both be local directory names; often SRC will be your main branch and DEST will be the name of the feature you're working on. This gives you a new branch where you can work on the new feature. If others want to help you with that change, you can let them branch off the new branch.

Working on a branch

Just like cvs:

bzr status
bzr diff
bzr commit
bzr add
bzr remove
bzr mv

Merging a feature back into main

1. Make sure the branch is up to date with the main line, using "bzr pull" and/or "bzr merge" on the branch.
2. Go into your main branch and do a "bzr pull ../FEATURE"

Publishing your changes

There are two methods, one for occasional use and one for regular use.

• For occasional use:
  bzr commit
  bzr bundle URL > FEATURE.bundle

  This creates a file called FEATURE.bundle, which you can e-mail to someone; URL should be either that person's repository or one of the public ones. (If you receive a bundle like this, you can do a "bzr pull" or "bzr merge" on it, as though it were a repository.)
  

• For regular use, set it up so that one of your branches (at least its .bzr subdirectory) is visible on the web and send the URL to the mailing list (or to one of the developers, if you prefer). Remember to "commit" whenever appropriate.

  For internal development, you might publish your changes on an intranet instead, accessible only to your colleagues, for instance on a shared disk. You would only publish a branch on the web if/when you want to contribute a particular feature back to the MatPLC project.
  

Other questions

Documentation for bzr

bzr Tutorial

Further bzr documentation