# Common Reference

## Using Bazaar (Bzr)

Bazaar (commonly referred to as Bzr) is the version control system primarily used in Xubuntu development.

### Setting up Bzr

To set up Bzr, do the following:

- To make sure Bzr is installed on your system, run `sudo apt-get install bzr`

- To set up your personal information for Bzr to use, run `bzr whoami "John Doe <john.doe@gmail.com>"`

### Getting and updating Bzr branches

After you have set up Bzr, you can get a local copy of a branch by running `bzr branch LOCATION`. This will create a directory for the branch.

To make sure your local copy is up to date, run `bzr pull` inside the branch directory.

### Pushing to Bzr branches

When you have worked on your changes and want to push them to a remote branch, do the following in the local branch:

- To rename or move files, run `bzr mv OLD NEW`. This helps to keep the resulting diff meaningful, and also works after the fact.

- If you have added files, run `bzr add .` in the branch root. This starts tracking any files in the branch that are currently unknown.

- If you have removed files, run `bzr remove`. In most cases, this should automatically stop tracking files that are no longer in the branch.

- To check the status of the branch, run `bzr status`.

- Commit your changes by running `bzr commit`. This will open a text editor to enter the commit message.

- After you have done one or more commits, run `bzr push LOCATION` to push your changes to a remote branch.

The commit message should summarize all the changes you have done after the last commit. You can specify it directly by using `-m MESSAGE`, and link a bug report to the commit by using `--fixes lp:BUGNO`.

When you are working on a branch and are making several changes that aren't related to each other, it is recommended that you do several commits. This helps to keep the commit log clean and makes it easier to find any issues that certain changes may have introduced.

When you push to a remote branch the first time, you will need to specify the branch location. In most cases, it will follow the format `&branch;lp:~username/projectname/branchname`. This pushes your code to a personal remote branch. On subsequent pushes, you can omit the branch location, as Bzr will have saved your previous push location in the local branch configuration.

### Submitting merge proposals

Once you have pushed your changes to a personal branch, you might want to propose them to be merged into the main branch.

To do a merge proposal (often referred to as MP) via web browser, start by opening the Launchpad page of your branch. You can find it by going to your Launchpad branches page and clicking on the branch in question. Now, click on Propose for merging. This will open a page that asks for some details on the merge proposal you are about to do.

The Target Branch is usually set correctly by default, change this only if you know it is wrong. If you have been told to add a specific Reviewer, add that reviewer to the appropriate field. Enter a Description of your proposed change as well. If in doubt about any of the options, ask the requested reviewer, or if one isn't specified, in the IRC channel.

Finally, click on Propose Merge. This submits your merge proposal and the target branch's owner as well as the specified reviewers will be sent a mail. If they need further information or want you to work further on the branch, they will comment on the merge proposal. You will be sent a mail any time an action is taken on the merge proposal, including when it's approved and merged into the main branch.

To do a merge proposal from the command line, using both the remembered submit branch (defaults to the parent branch) and the default reviewer team for that branch, run `bzr lp-propose-merge`. This will open a text editor to enter the description of your proposed change. You can override the default reviewer by using `--review NAME` one or more times, and link a bug report to the merge proposal by using `--fixes lp:BUGNO`.

## Using Git

Git is the version control system used in Xfce development.

One major difference between Git and Bazaar to note is that, in Bazaar you usually deal only with branches, while in Git you have to differentiate between branches and repositories, which can hold multiple branches. This is also reflected by the various commands you use. Another is that Git doesn't automatically stage your changes for commit, you have to tell it to do so.

### Setting up Git

To set up Git, do the following:

- To make sure Git is installed on your system, run:

  `sudo apt-get install git`

- To set up your personal information for Git to use, run:

  `git config --global user.name "John Doe"`

  `git config --global user.email "john.doe@gmail.com"`

### Getting and updating Git repositories

After you have set up Git, you can get a local copy of a repository by running `git clone LOCATION`. This will create a directory for the repository.

To make sure your local copy of a branch is up to date, run `git pull` inside the branch directory.

### Pushing to Git repositories

When you have worked on your changes and want to push them to a remote repository, do the following in the local branch:

- To rename or move files, run `git mv OLD NEW`. This helps to keep the resulting diff meaningful, while Git should figure this out automatically.

- To remove files, run `git rm FILE`. This also stops tracking the specified files, while it's redundant if all changes are staged later anyway.

- If you have added files, run `git add .` in the branch root. This starts tracking any files in the branch that aren't currently, and also stages any changes.

- To check the status of the branch, run `git status`.

- Commit your changes by running `git commit -a`. This stages any changes, and will open a text editor to enter the commit message.

- After you have done one or more commits, run `git push LOCATION BRANCH` to push your changes to a remote repository.

The commit message should summarize all the changes you have done after the last commit, you can specify it directly by using `-m MESSAGE`.

## Build dependencies

Before you can build a package from source, you will usually need to install its build dependencies.

To do this, simply run `sudo apt-get build-dep PACKAGE`.

## Launchpad

Launchpad is the primary platform used for Xubuntu development. Historically, the version control system used on Launchpad is Bazaar, but it recently added support for Git, too.

### Setting up a Launchpad account

For information on setting up a Launchpad account, see Creating a new account.

## Useful QA Links

- Xubuntu QA

- Xubuntu Testers

- ISO Tracker

- Package Tracker

- Ubuntu QA Team Wiki

- Ubuntu Manual Tests