Back to developer page.

Mercurial

Our Mercurial workflow

We use Mercurial, following the task-based workflow explained here. All significant development should be in response to an issue in the tracker, let's say issue1000. Then the usual development process involves two roles, "developer" and "reviewer" (usually Malte), and works as follows:

1. Developer creates a new branch issue1000 in their own repository, usually branching off the newest revision in default. Note the exact spelling of the branch. Being consistent here allows us to automate some of these steps in the future. The Mercurial commands for this step and the following are shown under Mercurial commands for Developers below.

2. Developer resolves the issue in the branch. (Developer does not close the branch or push the changes to the master repository.)

3. Developer pushes his changes to a repository (usually on Bitbucket) and gives the reviewer access.

4. Developer usually makes a pull request on Bitbucket from the issue1000 branch to the default branch in their repository (see ForDevelopers/CodeReview).

5. Developer sets the status of the issue in the tracker to "reviewing".
6. Reviewer pulls the issue1000 branch into their own repository.
7. Reviewer reviews the code and usually makes comments in the pull request on Bitbucket. If reviewer is not satisfied, go back to step 2.
8. Reviewer closes the issue1000 branch.
9. Reviewer merges the issue1000 branch into the default branch.
10. Reviewer pushes the issue1000 branch and its merge into the master repository.
11. Reviewer sets the status of the issue to "resolved".

Mercurial commands for developers

Developers should bring their working copy up to date via hg pull -u. To view open branches use hg branches. To also see closed branches, use hg branches -c. Before you start working on an issue, hg branch should display "default", and hg status should not display any modified files.

If no branch for your issue (here: issue1000) exists yet, type hg branch issue1000 to create a new branch, and commit straight away with hg commit -m "Start branch issue1000.". Else change to the existing branch using hg update issue1000. Fix the bug, then commit with hg commit -m "Fix issue222 by..." or similar message.

If using a separate repository (e.g. at Bitbucket.org) to share your changes, push to that repository with hg push <URL>. If the branch for the issue did not yet exist, you will need to use hg push --new-branch (in older versions of Mercurial: hg push -f, but use that with care).

Mercurial conventions

Commit messages: The first line of the commit message should consist of a self-contained summary and be no longer than 67 characters. All other lines should be below 80 characters. In particular, please avoid very long commit messages without line wrapping. In addition to other problems, overly long lines cause unreadable overlapping/self-intersecting text in the web interface of the repository. Please write the summary in the imperative mode (e.g., "Fix issue600" instead of "Fixed issue600", see https://chris.beams.io/posts/git-commit/).

Tips and tricks

The following Mercurial extensions are highly recommended. You can enable them by adding the mentioned configuration lines to either your ~/.hgrc file (to enable the extension for all your Mercurial repositories; recommended) or to the .hg/hgrc file of a particular repository (to enable the extension just for this repository). All of these extensions are shipped with Mercurial by default, so you don't need to install anything.

Colored output from Mercurial

The color extension colorizes the output of hg status, hg diff and similar commands. Activate it with

[extensions]
hgext.color =

If you don't like the default colors, they can easily be customized. See the documentation for the http://mercurial.selenic.com/wiki/ColorExtension.

Graphical diffs from Mercurial

The extdiff extension allows us to integrate Mercurial with graphical diff tools such as meld. To set it up, run

sudo apt-get install meld

if necessary and add

[extensions]
hgext.extdiff =

[extdiff]
cmd.meld =

to your Mercurial config. You can then use

hg meld

instead of hg diff to obtain graphical diffs. (When using hg meld to merge code, make sure to check the filenames within meld to ensure that your modifications end up in your working directory rather than in temporary directories created by Mercurial.)