Documentation:Using bzr

Introduction
We follow a similar workflow for documentation as is followed for development. This allows us to work efficiently, keep our documentation at it's best, work independently and keep new work isolated until approved.

If you haven't yet read the page on Bazaar, it is recommended that you do that before reading this page.

Utilities that help
For those who like GUI's, you can download and install Bazaar Explorer for Linux, Windows and Mac OS X.

Version Control Workflow
The core of the development workflow is the version control workflow.

Diagram
Here's a diagram to help you understand how the workflow works:



Getting Started
The first thing you'll want to do is to create a shared repository. This is a directory that holds all our branches, and a shared history (which means everything takes up less disk space).

I'm going to create this shared repository in my  directory:

@:~$ cd Projects @:~/Projects$ bzr init-repo --2a openlp-docs

Now that I've created this shared repository, I'm going to check out the trunk. This is the main branch where all the other branches are merged into.

@:~/Projects$ cd openlp-docs @:~/Projects/openlp$ bzr checkout lp:openlp/documentation trunk

Great! Now I have a directory called  in my   directory, which contains the main branch of all the code.

Please note: You cannot commit or push to trunk. Trunk is read-only for anyone other than the OpenLP Core team.

Branching
When you want to do some work in a particular area, or on a particular area, you'll want to create a new branch for this work. Once this branch is created, you'll work in it until you've completed what you set out to do.

First make sure your checkout of trunk is up to date:

@:~/Projects/openlp-docs/trunk$ bzr update

Now let's create a new branch:

@:~/Projects/openlp$ bzr branch trunk my-documentation

Great! Once this command is finished, I'll have a branch called. Now I can work in this branch until I've got all the my-documentation code looking and working nicely.

Adding files
If you make changes to an existing file, bzr will automatically detect those changes when you next commit. However if you add some new files, it is necessary to tell bzr that you would like this file to be added to the repository when you next commit. The same command applies whether you are adding text files or binary files such as images. Remember only add the source files. Files which can be generated/built from other files already in the repository should not be included.

To add a single file: @:~/Projects/openlp/dualdisplay$ bzr add manual/source/monitors.rst

You can also choose to add an entire folder, however be sure this only contains file you wish to add, and there are no temporary files or generated files in the folder. If in doubt add files individually as above.

@:~/Projects/openlp/dualdisplay$ bzr add manual/source/newfolder

Renaming or removing files
To rename an existing file which is already in bzr:

@:~/Projects/openlp/dualdisplay/manual/source/$ bzr mv monitors.rst dualmonitors.rst

To remove a file from the repository:

@:~/Projects/openlp/dualdisplay/manual/source/$ bzr remove dualmonitors.rst

Note, this will note delete the file from disk, this needs to be done as a separate step.

Committing
When I've made some changes, and they work, and I'm happy with them, I can commit my changes to this branch so that I create a new revision, and I don't lose the changes.

@:~/Projects/openlp/dualdisplay$ bzr commit

Reverting
Perhaps you've made some changes and now decide you don't want them. Using the bzr revert command you can undo everything since the last commit. Note, be very careful you want to do this, as you could lose work. Perform a bzr status first to check the uncommitted changes.

@:~/Projects/openlp/dualdisplay$ bzr revert

Pushing
When my code is at a stage where I want to merge it with the trunk code, I first need to push it up to Launchpad.net.

@:~/Projects/openlp/dualdisplay$ bzr push lp:~raoul-snyman/openlp/dualdisplay

This command will create a publically viewable branch in my account on Launchpad. Then if I want this code merged with OpenLP's trunk, I need to go to Launchpad and propose a merged.

Remember that you can only push to your own account on Launchpad, but you can branch from anyone's account.

Proposing A Merge
Now you need to go to the OpenLP code page on Launchpad and look for your branch that you just pushed your code to. Click on the link there, and on the details page you should see a link a little way down that says "Propose for merging into another branch". Click on this link, and specify  as the branch to merge this code into.

Once this merge proposal has been created, an e-mail is sent to the core team, who will then review your proposed merge. Once you have at least 2 approvals (and if you're part of the core team, you can't approve your own proposal!), one of the core team will merge your code to trunk and mark the proposal as merged.

Updating
Once the merge has happened, most folk will want to update their trunk.

@:~/Projects/openlp/trunk$ bzr update

If you want the latest changes from trunk in a branch that you are working on (please note, this is not necessary, bzr takes care of merging things like this), then you'll want to merge trunk into your branch. You can find out how to merge in the section below.

Merging
On some occasions, trunk will be updated while you are working in a separate branch, and you want to pull those changes from trunk across to your branch. This is how we get it right.

First, make sure you have no changes in your branch that have not been committed. You don't want to mix up your changes and the latest changes in trunk in a single revision. Follow the commit instructions above to do this.

Next, you need to go to your copy of trunk.

@:~$ cd ~/Projects/openlp/trunk @:~/Projects/openlp/trunk$

Then make sure your checkout of trunk is up to date:

@:~/Projects/openlp/trunk$ bzr update

Then you need to navigate to your branch:

@:~/Projects/openlp/trunk$ cd ../dualdisplay @:~/Projects/openlp/dualdisplay$

Then merge from your local copy of trunk into your branch:

@:~/Projects/openlp/dualdisplay$ bzr merge ../trunk

Once you have merged, you will be a alerted to any possible conflicts in the merge. There are two ways to resolve these conflicts:

Edit the conflicted file, and look for the conflicts and fix them up. A really good tool to use on Linux is KDiff3, which can automatically merge most conflicts. Simply select your base, "mine" and "theirs" files, and the output file, and then choose what stays and what goes.
 * 1) Manually:
 * 1) Semi-Automatically:

And once that is merged and all the conflicts are resolved, you'll need to commit.

@:~/Projects/openlp/dualdisplay$ bzr commit

Updating Trunk
Core developers only!

Once a Merge Proposal has received two Approvals from the Core Documentation Team, it is time to merge it into trunk.

First ensure your trunk is up to date, cd to your documentation trunk folder and:

@:~/Projects/openlp/trunk$ bzr update

Note, although you shouldn't change anything in trunk yourself, if you think you may have accidentally changed something, perform a revert. There is no harm in always performing this step.

@:~/Projects/openlp/trunk$ bzr revert

Now, visit the Merge Approval page on Launchpad. Near the top you will see a "To merge this branch:" followed by a bzr command. Type that command. E.g.

@:~/Projects/openlp/trunk$ bzr merge lp:~wesleystout/openlp/documentation

Now commit the changes, ensure you type in a sensible descriptive commit message. You can often use the proposal message. Note you can also leave off the -m option, and it will open an editor where you can type the message instead, which is easier if you have a long message.

@:~/Projects/openlp/trunk$ bzr commit -m"How to add an author to a song"

If you are not the author of the changes, you need to specify the author of the merge.

@:~/Projects/openlp/trunk$ bzr commit --author "Spam Eggs "

As an alternative, the qcommit command offers a GUI interface where the message, author and bug can be easily added:

@:~/Projects/openlp/trunk$ bzr qcommit