Using bazaar

Word of introduction

In WT team we believe bzr stands for "bizarre". Using Bazaar is not easy, nor intuitive. It may lead to many frustrations, losing nerves and such. Please inform us about your problems to help you (and some other folks too). When configuring your environment, bare in mind it will take some effort to make all the needed things working. Using Bazaar Explorer - a GUI over bzr system, may lead to additional issues, like inability to configure the latest stable version (uninstall it and install previous version in this case, or simply do not configure BE at all, it will work badly anyway).

Prerequisites for contributors

To commit any kind of changes to the content of the /trunk to us on Launcpad via Bazaar you must:

1. already have checked out the /trunk once
2. be part of the Launcpad group called WTdevs
3. have been in contact with us via e-mail, presenting yourself
4. and also have a SSH key registered at Launchpad.

Joining the team

• Make sure you are a registered and activated user on Launchpad.net
• Join / apply for membership in the Launchpad group called [WTdevs https://launchpad.net/~wtdevs]
• Please contact snowdrop via e-mail (snowdrop at wtactics dot org) with a presentation of yourself and what you are going to contribute with.
  • Allow a couple of days for us to get back to you: Depending on your ideas and ambitions, you will either be granted or denied write access to the trunk. You will be notified per mail either way.

Registering a SSH key at Launchpad

• Follow the instructions given at: https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair
• You will not be able to upload your changes to the /trunk unless you have registered a key.

Keep in mind that on some popular, non-free systems, the creators did'nt pay attention to your security too much, this way, when working with bazaar you will have to run PAGENT.exe and provide it with your private key (it is a part of Putty toolset). All the rest will just happen automagically.

Id yourself for Launchpad

bzr launchpad-login yourusername

The above ID:s yourself for Launchpad. In order for that to work you must have already followed the SSH key creation and registration process.

Checkout the project

To get the project for the first time you need to do a so called "check out". When checking out a project you will download it and it's associated files.

bzr checkout --lightweight http://bazaar.launchpad.net/~wtdevs/wtactics/trunk/ /your/destination/path

• Would get the latest revision of the project and download it to /your/destination/path.
• The --lightweight flag saves you from also including all the previous versions of each file and a total history record. Typically you would not want that as the above check out should suffice for most people.

If you only want to keep yourself updated by viewing our content the above should suffice. The next step is only required if you want to contribute by uploading files to the branch as well:

bzr switch lp:~wtdevs/wtactics/trunk/      

• Very important: unless the above command is executed you will not be able to commit your changes to the branch if you did a checkout --leíghtweight.
• The bzr switch is not needed if you, instead of a checkout, did a branch instead.
• After running the command you don't need to do push to submit your changes to the cental repo: Any commit you do is directly also done to the main branch online at launchpad.

A maybe more proper way to checkout the project instead of using the above two commands could be:

bzr checkout --lightweight bzr+ssh://bazaar.launchpad.net/~wtdevs/wtactics/trunk/

That would presumably not require you to use the switch command after the checkout. (This needs verification. If true, and uploading works directly without you needing to use the switch command, the previous two commands should be deleted and the above one kept as the proper method. If so, please edit me.)

• Sidenote here: You can also make a branch of the project. There are three major differences when making branch (v. making checkout): you will have to download whole history and keep it locally (its a huge pile of data, keep that in mind), you will be able to commit changes locally and later push it to our code tree when a major task is finished, pushing revisions will work much faster. Take what suits you most - if you have slow connection, but plenty of space, making a branch may be better, while on really fast connection and narrow disk space lightweight checkout will be a better option.

Adding files

Adding to the Bazaar versioning system

bzr add

• The add command is used to add new files/dirs to the project and/or rename, move or delete files/dirs already within it.
• It is, per default totally recursive: Being in the root of your local checked out copy of the /trunk will add any and all new files/dirs and changes to the project. Notice that it will all happen on your local version of the branch and that add does not actually commit the content anywhere. Add only tells the version control system (Bazaar) to keep track of the files.
• Easiest way to add all your new stuff is to simply be in the trunk root and give the command (bzr add) - it would take care of everything in lightning speed.
• Official documentation

Uploading to the central /trunk

Please note there are some guidelines covering committing comment syntax. We don't use a bug system to keep tightly to the guidelines, all we really need is to explain what your commit is supposed to change in a clear manner.

We have TEST file in the main directory, for testing purposes.

If you have a branch

• to update a local branch with a remote content, you need to merge first (this will take all the data from the net) and later update or pull your working tree (or both).

You have added new content or modified some old and want to share your contribution. To do so, give the following command if you got your copy of the trunk via the branch command:

bzr push --remember lp:~wtdevs/wtactics/trunk

• The above will upload any changes you made to the /trunk and that you, before doing this, have already committed locally.
• For your convenience: From that point on, it is sufficient to type just bzr push when you want to update the central branch at Launchpad. That is why we use the --remember flag. Bazaar will fill in the lp:~wtdevs/wtactics/trunk info itself once you have done the above.
• This will only work for developers that actually have requested and gotten access to write to the /trunk and are part of the wtdevs launchpad group.
• Notice the ~wtdevs-part of the command: In Bazaar documentation it often tells you to input your personal Launchpad username there instead. Do not do that, as that will just create another branch. All WT developers should, unless otherwise agreed upon, use the ~wtdevs group name. That way we all push the changes to the one and the same trunk.

If you have a checkout

Before you try to commit changes, when working with checkout, be sure to run the very obscure command:

bzr switch lp:~wtdevs/wtactics/trunk/

We still dunno why it was needed and not covered in any tutorial. It needs to be casted once only.

The push command is not needed at all if you got your copy of the trunk by using the checkout command. Then all all your changes are committed directly to the central server at Launchpad. Use the following to send in your work:

bzr commit