Latest Posts

Changes in BzrPrimer

Editor Comment

Rewrote the instructions for pushing to Launchpad.


Revision Differences of Revision 6

# Bazaar primer for SVN developers ¶

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

## Getting started with bazaar ¶

* Get bazaar: <http://bazaar.canonical.com> or the packaging system of your trust. ¶
* Read <http://wiki.bazaar.canonical.com/BzrForSVNUsers>. ¶

## Getting started with launchpad ¶

* 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> ¶

## 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 in ¶
>
> ~$ bzr whoami "Your Name <your.email@example.net>" # if you are using bzr for the first time on this machine ¶

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

> If you will be developing media, also set up a repository for the media branch by entering ¶
>>
> ~$ bzr init widelands-media-repo ¶

> These repositories will now support uploading and downloading only the changes made to the branches you establish in them. ¶

### Getting the Source ¶

* To download
a "checkout" which is the contents of the __main development trunk__ for the first time, ¶
>> ~$ cd widelands-repo ¶
~$ bzr branch lp:widelands/trunk ¶

* When that completes, create a working tree by entering ¶
>> ~$ bzr get trunk my_widelands_working_tree ¶
> to copy the trunk to a working directory. __DO NOT MAKE CHANGES DIRECTLY TO THE TRUNK__. (BAD things happen.) ;( ¶

* To download
a "checkout" of the __media trunk__ for the first time, ¶
>> ~$ cd widelands-media-repo ¶
~$ bzr branch lp:widelands-media/trunk ¶
(This is a BIG download.) ¶

* When that completes, enter ¶
>> ~$ bzr get trunk my_widelands-media_working_tree ¶
> to copy the trunk to a working directory. __DO NOT MAKE CHANGES DIRECTLY TO THE TRUNK__. (BAD things happen.) ;( ¶

### Making Changes ¶
__DO NOT MAKE CHANGES DIRECTLY TO THE TRUNK__. (BAD things happen.) ;( ¶
(Have we made our point?) ;) ¶

* To make changes, ¶
>> ~$ cd widelands-repo/my_widelands_working_tree (or cd widelands-media-repo/my_widelands-media_working_tree) ¶
hack ¶
hack ¶
hack ¶
~$ bzr add * # to alert bzr to any __new__ files you've created ¶
~$ bzr commit -m "Commit of a very cool new feature I contributed" ¶

* To keep your working tree(s) up to date with changes others have made on the trunk you must pull the changes from launchpad and then merge them with your working tree. This is done as follows for the main development trunk. The media trunk is done the same way.: ¶
>> ~$ 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 first secure them before merging the new changes from the trunk. ¶

### Pushing your changes to Launchpad ¶

--- ¶
## The Remainder of This Page from This Point is Currently Under Re-write ¶


The next step varies. If you are a member of [widelands-dev](https://launchpad.net/~widelands-dev) you can directly get your changes back to launchpad: ¶
~~~~~~ ¶
$ bzr push lp:~widelands-dev/widelands/trunk # see the --remember option ¶
~~~~~~ ¶

If you are not a member of [widelands-dev](https://launchpad.net/~widelands-dev), you can still push your changes up to launchpad: ¶
~~~~~~ ¶
$ bzr push lp:~myusername/widelands/cool-new-feature-branch ¶
~~~~~~ ¶

## The way I work ¶
I will explain briefly how I will work with bazaar. I have some experience with git that is pretty like bazaar. ¶

### To download main stream ¶
The code will be downloaded to ~/widelands ¶

* $ cd ~ ¶
* $ bzr branch lp:widelands ¶
* $ cd widelands ¶


### To get changes on main branch ¶
When someone push or merges changes to main branch, you need to update your sources. ¶

* $ cd ~/widelands/ ¶
* $ bzr pull ¶


### Branches ¶
The strong points of distributed version controls are the freedom to create branches for every single feature to add or bug to be fixed. While developing, his code will not break mainstream source. And anyone can download a specific branch and test it to confirm if works as spected. Finally when branch has added the feature or fixed the bug, it will be merged with mainstream and 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 local main branch to pull from upstream and rebase your branches before pushing back. ¶

#### To add a new feature ¶

* $ cd ~/widelands/ ¶
* $ bzr branch widelands feature-xxx ¶


We have created a new branch called feature-xxx that is a copy of current downloaded mainstream branch. We need to move onto them and make changes there. ¶

* $ cd ~/widelands/feature-xxx ¶
* hack with sources! ¶
* $ bzr commit -m "Feature added: xxx" ¶


We now push changes to our own personal repo. ¶

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


Now we can send a mail to inform other devs and players that branch my-feature-xxx need

## Getting your changes into the game ¶

### Branches ¶
The strong points of distributed version controls are 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?) ;) ¶


#### To add a new feature ¶
Create a working branch or use an existing "working_tree" ¶

* $ cd ~/widelands-repo/ ¶
* $ bzr branch trunk feature-xxx (or my_widelands_working_tree) ¶


We have created a new branch called feature-xxx that is a copy of the current downloaded (local) main trunk (or branch). We need to move into that folder and make changes there. ¶

* $ cd ~/widelands-repo/feature-xxx (or $ cd ~/widelands-repo/my_widelands_working_tree) ¶
* hack with sources or add new media! ¶
* $ bzr add * (to alert bzr to any newly added files. If none, this command is optional.) ¶
* $ bzr commit -m "Feature added: xxx" ¶


We now push changes to our own __personal repo__. ¶

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


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

If you need to fix something or people report some problem with branch: ¶

* $ cd ~/widelands
-repo/feature-xxx ¶
* make more hacks! ¶
* $ bzr commit -m "Bug fixed on feature xxx" ¶
* $ bzr push lp:~my.user.name/widelands/my-feature-xxx ¶


#### To fix a bug ¶
You can work on
mainstream or create a new branch only for fixing it, to avoid breaking mainstream. I prefer create a new branch and merge it with mainstream when confirmed that bug is fixed. The way to work is exactly like to add new feature. ¶

* $ cd ~/widelands/ ¶
* $ bzr branch widelands bug-xxx <- This creates my branch to hack ¶
* $ cd bug-xxx ¶
* hack to solve bug ¶
* $ bzr commit -m "Bug xxx fixed" ¶
* $ bzr push lp:~my.user.name/widelands/fix-bug-xxx ¶


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

* $ cd ~/widelands/bug-xxx ¶
* $ bzr rebase ~/widelands ¶
the main trunk or create a new branch only for fixing it, to avoid breaking the main trunk. I prefer to create a new branch and merge it with the main trunk when confirmed that bug is fixed. The way to work is exactly like adding a new feature. ¶

* $ cd ~/widelands-repo/ ¶
* $ bzr branch trunk bug-xxx <- This creates my branch to hack ¶
* $ cd bug-xxx ¶
* hack to solve bug ¶
* $ bzr commit -m "Bug xxx fixed" ¶
* $ bzr push lp:~my.user.name/widelands/fix-bug-xxx ¶

#### 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 for the main development trunk. 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 first 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 first have those changes pushed to a personal branch and then when you 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 needed. ¶

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


Doing that way another developer can push a change before you push yours, in this case a conflict could arise when try to push, 'branches has diver
sed' or something like. When this happens you simply uncommit your merges to main: ¶

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


Revert to undo merge: ¶

* $ bzr revert ¶


Update your mainstream (see above) and redo the *rebase*, *merge*, *commit* and *push* again.
ged' or something like. When this 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 manually can be a bit 'time consuming' if a lot of developers push at 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> ¶

th
aen you are down to that revision number ¶

to get back to HEAD, run: ¶

* $ bzr revert ¶
* $ bzr pull ¶



--- ¶
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. ¶