Working with Bzr branches and Launchpad
This tutorial expects you to have set up Bzr and Launchpad correctly.
Cloning a branch
To clone a branch from Launchpad, you will need to issue the bzr branch command with the branch location as the second parameter. You can find this branch location from the branch overview. For example, to clone the manual tests branch, run:
bzr branch lp:ubuntu-manual-tests
This will clone the ubuntu-manual-tests branch to the current directory as a subdirectory with the branch name. If you want a different directory name, you can append the directory name you wish as the third parameter for the bzr command.
You can get the branch command/name for any branch from its overview page in Launchpad. For example, the manual tests overview page is at https://code.launchpad.net/ubuntu-manual-tests.
Add files to your branch
Now that your changes are complete, it's time to commit them to your local repository and then sync your local repository to launchpad so others can view and utilize your work.
Bzr commands require you to run them inside the directory (or a sub-directory) of the repository on your local machine. If needed, cd to the directory of the files you made / changed before running these commands.
First, let's commit to your local repository. Bzr allows you to view the status of a repository using bzr status. This will show you the changes you made to your local repository. For example;
$ bzr status modified: testcases/packages/Mousepad unknown: testcases/packages/nautilus
In this example you can see I've modified the Mousepad testcase, and made a new file for a new testcase for nautilus. The new file shows up as "unknown" to bzr.
If you have made a new file, use the bzr add command to add it to the local copy. If you only modified an existing file, you can skip this step and jump down to Commit your work
$ bzr add testcases/packages/nautilus adding testcases/packages/nautilus $ bzr status added: testcases/packages/nautilus modified: testcases/packages/Mousepad
Committing your work
You must enter a message of some sort in order to commit your changes. The message should be a short description of what you changed. For example, the message for my changes above could say "Added a new test for mousepad to verify keyboard layout. Created a new nautilus testcase".
bzr commit -m "Added a new test for mousepad to verify keyboard layout. Created a new nautilus testcase"
Pushing a branch
Once you are done with your changes on the branch, you will need to push the branch to Launchpad in order to do a merge proposal.
Until you have the permissions to push to the main branch, you will need to push the branch as a personal branch. Additionally, in order to be able to do a merge proposal, the branch needs to start with the project name. For example, to push a branch for a merge proposal against the ubuntu-manual-tests main branch, run:
bzr push lp:~yourusername/ubuntu-manual-tests/mychanges
As a quick breakdown, the branch name consists of three different parts:
lp:~yourusername/, which means you will be pushing into a personal repository for yourusername
ubuntu-manual-tests/, implying that this branch is an alternative/branched branch of the project ubuntu-manual-tests
mychanges, which is the actual branch name for this branch
Linking the branch to a bug
If your work is related to an existing bug. Copy it's bug number. Click your branch shown on this page and then click "Link a bug report". Paste the bug number, click search, then click OK.
Registering a merge proposal
After you have pushed your changes successfully to a personal branch, you will need to register a merge proposal for your branch in order to let the main branch maintainers know what you have done and to ask for a review from them.
To do this, go to the overview page of your page in Launchpad. If your push location was lp:~yourusername/ubuntu-manual-tests/mychanges, then your branch overview page will be https://code.launchpad.net/~yourusername/ubuntu-manual-tests/mychanges.
You can always find the list of all your personal branches for all projects at https://code.launchpad.net/~/.
On that page, click on Propose for merging under Branch merges. Launchpad will now show you a merge proposal form.
The target branch is always the main branch by default, and it is also is in most cases what you want to use.
The description is a brief description of your changes, to complement the diff of your merge proposal that the reviewer will be looking at.
Finally, reviewer is the person that you ask to review your branch. You do not need to use this unless somebody has asked you to mark them as the reviewer for the branch; in that case, fill in their Launchpad username to this field.
Once you have filled the above information, click Propose merge. This will automatically send a notification to the default reviewers (or the reviewer you specifically filled in).
If your branch looks good to them, the reviewer(s) will approve and merge the branch to the main branch. If there are problems with your branch, the reviewer(s) will comment on the merge proposal and tell you what you need to do before they will approve the branch. You will get an automatic notification in both cases.