Latest Posts

Changes in BzrPrimer

Editor Comment

added email warning and done some clean-up


Revision Differences of Revision 20

# Bazaar primer for SVN developers ¶

This
will explain ins a shortened workflow, how to mexplakeining the steps from having developed on sf.net and knowing SVN to developing on [launchpad.net](http://launchpad.net) using bazaar (bzr). ¶

[TOC] ¶

## Getting started with bazaar ¶

* Get bazaar: <http://bazaar.canonical.com> or the packaging system of your trust. ¶
* Read [BzrForSVNUsers](http://wiki.bazaar.canonical.com/BzrForSVNUsers) or [BzrForGITUsers](http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-git-users.html) ¶

## Getting started with
lLaunchpad ¶

* Get an account: <http://launchpad.net> ¶
* Register an SSH
key with your account: <https://launchpad.net/people/+me/+editsshkeys>, interesting read is also <https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair> ¶
* Use 'bzr launchpad-login' to connect your
lLaunchpad account with bzr ¶

## Getting started with widelands development ¶

This is for unixes. The Windows terminal should work quite similarly, but optionally you can use some kind of GUI
, like <http://wiki.bazaar.canonical.com/TortoiseBzr>. ¶

### Initial Steps


* First install bazaar on your computer. That is the utility used to move files back and forth from Launchpad. ¶

* Start a terminal session on your computer and from the home directory
type set your identification (in case you are using bzr for the first time on this machine). Normally, you should use this (don't use it, read below):

> `~$ bzr whoami "Your Name \<your.email@example.net\>"`


But
the above will unashamedly expose your email address, so don't provide it, and ignore the warnings: ¶

> `~$ bzr whoami "username"` ¶

If you have not done it, you may also need to register your public key through Launchpad's web interface.


* Then set up a bzr shared-repository folder on your computer by entering
:
> `~$ bzr init-repo widelands-repo` ¶

* Now you have ~/widelands-repo
empty directory created. It is empty. If you will be developing media, also set up a repository for the media branch by entering :
> `~$ bzr init-repo widelands-media-repo` ¶

* These repositories will contain trunk and your own branches used to upload and download your changes.


_Side note: '**~$**' here means home directory, on
lLinux it tends to be like 'home/johny/'. If unsure where you are, use 'pwd' or just 'cd' to get to back to home directory. _ ¶

### Getting the Source


* To download a "checkout" which is the contents of the __main development trunk__ for the first time, go to widelands-repo directory: ¶

> `$ cd ~/widelands-repo` ¶

* and run: ¶

> `$ bzr branch lp:widelands/trunk` ¶

* When that completes, you will have ~/widelands-repo/trunk/ populated with widelands source code. ¶

* Remember: __DO NOT MAKE CHANGES DIRECTLY TO THE TRUNK__. (BAD things happen.) ;( ¶

*
TLikewise, to download a "checkout" of the __media trunk__ for the first time, go to ~/ widelands-media-repo and run :

> `~$ bzr branch lp:widelands-media/trunk` ¶

* This is a BIG download (more than 4 GB) ¶



## Getting your changes into the game


### Branches

The strong point
s of distributed version controls arsystems is the freedom to create branches for every single feature to add or bug to be fixed. While developing, this code will not break mainstream source, and anyone can download a specific branch and test it to confirm if it works as expected. Finally, when the branch has successfully added the feature or fixed the bug, it will be merged with the main trunk and the branch can be deleted safely.
Another strong point of working only on branches is the lower risk of conflicts when merging. My recommendation is only work on branches, and

use a local main branch to pull from upstream and rebase your branches before pushing them back.
__DO NOT MAKE CHANGES DIRECTLY TO THE TRUNK__. (BAD things happen.) ;(

(Have we made our point?) ;) ¶



#### Creating own branch (to add a new feature / fix a bug / change anything) ¶
* First change to widelands-repo directory: ¶

> `$ cd ~/widelands-repo/` ¶

* and create new branch from the trunk (named feature-xxx) ¶

> `$ bzr branch trunk feature-xxx ` ¶

* Directory ~/widelands-repo/feature-xxx/ should now be populated with widelands source code
.

* Any
of your changes should be done in feature-xxx directory only!.

* If you need to
to add a new file, you must inform bzr of its existence, so use: ¶

> `$ bzr add *`


*
oOnce you are done, you must commit changes (createing new revision) with: ¶

> `$ bzr commit -m "Feature added: xxx"` ¶

* (
IBefore any commit, it's a good habit to `bzr status before committing`, to make sure of what will really change, de.g. toes n'ot forget tof `bzr add` any new files.) ¶

* We now push changes to our own __personal repo__ on launchpad
.:

> `$ bzr push lp:~my.user.name/widelands/my-feature-xxx` ¶

* Or we may push to the official development repo: ¶

> `$ bzr push lp:~widelands-dev/widelands/my-feature-xxx` ¶



* Now we can send a
n email to inform other devs and players that branch my-feature-xxx needs testing.



#### To keep your working tree(s) up to date

with changes others have made on the trunk (or an original personal branch from someone else)
, you must pull the changes from launchpad and then merge them with your working tree. This is done as follows fFor the main development trunk., this is done as Tfollows (the media trunk and personal branches are handled in a similar fashion):

* `$ cd widelands-repo/trunk` ¶
* `$ bzr pull` ¶
* `$ cd ../my_widelands_working_tree` ¶
* `$ bzr merge ../trunk` ¶
* `$ bzr commit -m "Merged
with changes from trunk."` ¶

> __Note__ that any changes you have made to your working tree but have not committed will be lost.
So if you wish to keep the work you have done so far in your working tree, do a `bzr commit` (see above) to firstly secure them before merging the new changes from the trunk.

### Merging with the main trunk

We have already seen example commands to push our changes to personal branches on launchpad.
The typical path for introducing fixes or new features is to firstly have those changes pushed to a personal branch and then, when youwe feel that branch is ready, submit a proposal for merging on Launchpad. The branch will be flagged as requesting review and merging upon acceptance. ¶

__Experienced members of the development team__ have the ability to merge development branches directly into the main trunk.

___DO NOT ATTEMPT THIS UNLESS YOU KNOW WHAT YOU ARE DOING!!!___ ¶

#### To upload changes directly to the main trunk manually (NOT RECOMMENDED!) ¶
When bugs get fully fixed or features added really work without problems, then you can propose a merge with main through launchpad web. Or rebase your bug-xxx branch with the main trunk, merge bug-xxx with main and do a push on main. Note: If you do it this way you need the rebase plugin for bazaar. ¶

* `$ cd ~/widelands-repo/bug-xxx` ¶
* `$ bzr rebase ~/widelands ` ¶

Now we merge our local branch with our local mainstream. ¶

* `$ cd ~/widelands-` ¶
* `$ bzr merge bug-xxx` ¶
* Solve conflicts with merges ¶

Some test are needed, at least try to build! ¶
When you were sure that all is ok, you can upload to mainstream. ¶
Note: After a merge
allways, a commit is always needed. ¶

* `$ bzr commit -m "Merged with bug-xxx"` ¶
* `$ bzr push` ¶



Doing that way, another developer can push a change before you push yours,. iIn thisat case a conflict could arise when trying to push, ('branches hasve diverged' or something like that). When thisat happens, you simply uncommit your merges to main: ¶

* `$ cd ~/widelands` ¶
* `$ bzr uncommit` ¶



Revert to undo merge: ¶

* `$ bzr revert` ¶



Update your local main trunk (see above) and redo the *rebase*, *merge*, *commit* and *push* again. ¶

##### Alternative method

Assuming bug-xxx was originally a branch of the main trunk, __an alternative__ to the rebase is to:


* `$ cd ~/widelands-repo/trunk` ¶
* `$ bzr pull (to get any recent changes to the main trunk)` ¶
* `$ cd ../bug-xxx` ¶
* `$ bzr merge ../trunk` ¶
* `$ bzr commit -m "Merged with changes from main trunk"` ¶
* `$ cd ../trunk` ¶
* `$ bzr merge ../bug-xxx` ¶
* `$ bzr commit -m "Bug xxx fixed"` ¶
* `$ bzr push lp:widelands/trunk` ¶



Doing it manually can be a bit 'time consuming' if a lot of developers push at the same time, so **I think that is better to make a petition to merge and solve all on launchpad web**. ¶

### Getting a specific revision ¶

In your bzr checkout (i.e. your local copy of a trunk or branch) run: ¶

* `$ bzr revert -r <revisionnumber>` ¶

then you are down to that revision number ¶

to get back to HEAD, run: ¶

* `$ bzr revert` ¶
* `$ bzr pull` ¶

### Git-style workspace (lightweight checkouts) ¶

Another way to organize the workspace (and at the same time save some space on your hard disk) is to use the so-called "lightweight checkouts". ¶

Normally, the shared repository (widelands-repo) contains the history of the "common part" of all branches. ¶
A single branch (trunk, feature-xxx, bug-xxx) contains the history of that branch and the current version of _all_ files that are in the branch. ¶

So, if you have 3 branches, you will have 3 times all the unmodified files. ¶

A "lightweight checkout" is simply a "link" to a specific revision of a branch
, and gives you the possibility to keep a single working directory and to attach this working directory to any branch. Since you have only one working directory, you have all files only one time. ¶
In this way it's very similar to git style - a single "moving" workspace (that follow
s a single branch at a time). ¶

In order to use this system, you can generate the branch with the --no-tree option. ¶
This means that the history (and support files) for that branch will be generated, but no actual file belonging to the branch itself
wisll be inserted in the branch folder. ¶

* `$ cd ~/widelands-repo/` ¶
* `$ bzr branch --no-tree trunk feature-xxx` ¶

Then you have to create the "working directory" folder and link it to your branch
:

* `$ bzr checkout --lightweight feature-xxx my_widelands_working_tree` ¶
* `$ cd my_widelands_working_tree` ¶

From now on, every time you commit in the "my_widelands_working_tree" folder, you are committing to feature-xxx
.

Imagine
that you want to create another branch and start working on it. Here is one way to do it (but see below for a possible shortcut):

* `$ cd ~/widelands-repo/` ¶
* `$ bzr branch --no-tree trunk feature-yyy` ¶

Now we have to "move" our "working directory"
, so as it points to the branch we want to work in.:

* `$ cd my_widelands_working_tree` ¶
* `$ bzr switch ../feature-yyy` ¶

nNow any changed made on my_widelands_working_tree is applied to feature-yyy.

NOTE: if you plan to use this approach, you have to type "--no-tree" any time you create a branch. ¶
To avoid this, the initial init-repo command can be modified into
:

*` $ cd ~` ¶
* `$ bzr init-repo --no-trees widelands-repo` ¶

so that any branch created will be created without trees. Then you can use the `switch` command to create new branches more easily. ¶
Suppose
that you want to create a branch twhichat starts with the current status of your working directory. You can simply say:

* `$ bzr switch -b ../feature-yyy` ¶

to simultaneous create and switch to the new branch. ¶



## Graphical user interfaces for BZR ¶

Among the [BZR Plugins](http://wiki.bazaar.canonical.com/BzrPlugins), there are some nice graphical user interfaces for bzr that can ease the work with bzr (e.g. through showing a commit window where you can select
, what you would like to submit, write the commit message, and add the number for a fixed bug to the commit).

Available for Linux, Windows and the MAC OS, _qbzr_ is a simple and intuitive user interface
,. jJust install qbzr for your repository, and afterwards write the same commands oin the terminal, as before, just with a "q" at the beginning (e.g. "bzr qdiff", "bzr qcommit", ...) ¶



--- ¶
Now, speak up on the [mailinglist widelands-public](https://lists.sourceforge.net/lists/listinfo/widelands-public) and we might merge your branch into trunk if it is good.