This site serves as node for gathering useful workflows.

If you use a workflow which isn't yet listed here, please add it. If you use a workflow very similar to one of the workflows here, but with distinct changes, please add a note to the modifications section of the existing workflow.

But if you search for quick hints to some issues, please have a look at the Tips and tricks page and at the list of extensions. Also there is a page with hints for working practices.

Contents

  1. Intro
    1. Structure of a workflow
    2. Sorting of the entries
  2. Overview and plan
  3. Workflows
    1. One-off patch submission
    2. CVS-like Workflow
    3. Feature separation through named branches
    4. Review bookmarks
    5. QA made easy
    6. Approval Management: Auditing and QA
    7. Approval Reports
    8. Configuration management during deployment
  4. Other Sources for Workflows

Intro

With Mercurial you can use a multitude of different workflows. This page shows some of them, including their use cases.

It is intended to make it easier for you to create your own workflow.

We begin with standard workflows and then go on to more complex examples.

The initial workflows come from the workflow collection in the wiki for http://mercurial-scm.org - would you like to help us convert one of the remaining ones to this page? (please delete this line, as soon as all workflows are transferred).

The workflows on this page are rather terse to give you a good overview. You can find a longer introduction which shows basic Mercurial usage compatible with these workflows in learning Mercurial in workflows.

Structure of a workflow

Sorting of the entries

Overview and plan

General:

Collaborating on features:

Dependency tracking:

Special usages:

Working with other vcs:

Neat tricks for smoothing workflows:

Workflows

One-off patch submission

For whom?

If you just want to submit a short patch to a project, this workflow is right for you.

Requirements

You need just Mercurial (command line) and an email address to which you can send the patch.

Local Flow

First get the repository 

$ hg clone http://selenic.com/repo/hello

Now edit the files and commit your changes 

$ cd hello
$ (edit files)
$ hg add (new files)
$ hg commit -m 'short description of the changes'

Export your patch 

$ hg export tip > patch.diff

Note: "tip" is the most current revision in your repository. hg export exports all selected revisions as one change.

Sharing changes

To share your changes, just send the file patch.diff to the developers email address, ideally with a description what your patch does and why it's important.

The developer will then import and test it: 

$ cd hello
$ hg import patch.diff

Now he has the revision in his local repository. He can test and push it.

Note: You can also use hg import on a maildir file. It will automatically select and import the patch.

Modifications

You can also upload the patch, for example to a bugtracker. It's just a simple file after all.

CVS-like Workflow

For whom?

For people who want to work as in CVS, but with added Mercurial benefits.

Requirements

Only Mercurial.

Workflow

See CvsLikePractice

Feature separation through named branches

For Whom?

If you want to develop features collaboratively and you want to be able to see later for which feature a given change was added, then this workflow might be right for you.

Note: If you have a huge number of small features (2000 and upwards), the number of persistent named branches can create certain performance problems. For features which need no collaboration or need only a few commits, this workflow also has much unnecessary overhead. It is best used for features which will be developed side by side with default for some time (and many commits), so tracking the default branch against the feature is relevant. To mark single-commit features as belonging to a feature, just use the commit message.

Note: The difference between Mercurial named branches and git branches is that git branches don’t stay in history. They don’t allow you to find out later in which branch a certain commit was added. If you want git-style branching, just use bookmarks.

What you need

Just vanilla Mercurial.

Workflow

To start a new feature,

1. first start a new branch with the name of the feature starting from default. 

hg branch feature-x
# do some changes
hg commit -m "Started implementing feature-x"

2. Then commit away and push whenever you finish something which might be of interest to others, regardless how marginal. If you want to hack on a feature started by someone else, or you want to switch between features, just update to the feature. 

hg update --check feature-x
# do some changes
hg commit -m "Improved X"

Note: The short form of hg update --check feature-x is hg up -c feature-x.

3. Merge default into your feature as often as possible. 

hg update feature-x
hg merge default
hg commit -m "merged default into feature-x"

4. When your feature is stable, merge it into default. 

hg update default
hg merge feature-x
hg commit -m "merged feature-x"

5. When the feature is done and needs no more work, close the branch. 

hg update default # start from default, automatic when using a fresh clone
hg branch feature-x
# do some changes
hg commit -m "started feature X"
hg push

# commit and push as you want
hg ci -m "some work for feature-x"

# once work on feature-x is complete, close the branch
hg commit --close-branch -m "finished feature X"

# now merge the completed work on the feature branch into default
hg update default
hg merge feature-x
hg ci -m "merged feature X into default"

6. To improve a feature after it was officially closed, first merge default into the feature branch (to get it up to date), then work just as if you had started it. 

hg up feature-x
hg merge default
hg ci -m "merged default into feature X"
# commit, push, repeat, finish

Generally merge default into your feature as often as possible.

Review bookmarks

For whom?

You have a reviewer and multiple developers. You want to enable the developers to work as disturbance free as possible, and you want to be able to send them reviews.

What do you need?

The bookmarks extension.

Flow

dev is the name of a developer.

feature is the name of a feature.

Repositories

Reviewer

A dev has changes:

A feature is done:

Developer

Option: named integration branch

You could use a named integration branch. Then the integrator can just update to integration and push integration instead of having to look up the revision.

QA made easy

For Whom?

If you have a separate QA team which tests the code before signing it off for release, and you want minimal source code overhead, this workflow might be right for you.

Requirements

Only Mercurial. If you need an additional verifiable datatrail, you can use the GpgExtension for signing off changes.

Workflow

To structure the work, you use separate clones:

To make sure that the code has really been checked by all, you can require that all heads must be GnuPG signed in order to enter a higher-up repository. Also see the Approval Reports Workflow.

To make this workflow more secure, the QA team could push all their changes to the dev repo first and require doublechecking from the devs.

Approval Management: Auditing and QA

For whom?

If you need explicitely approved code history with a full track record using a team of developers and a separate QA team, this workflow might be right for you.

Requirements

You need just Mercurial (command line), a shared repository for exchanging data (a simple SSH-server suffices, as does a single private bitbucket repository) and the GpgExtension.

Flow

This workflow uses the default branch for development, as well as a QA named branch and a release branch.

The advantage is that merging default into QA requires an explicit merge which can subsequently be GPG signed by the developer responsible for it.

When QA finishes applying their changes, they first of all merge back into default (so that developers work on the QA version) and then merge into release, GPG signing the merge commit.

Developer

hg pull # get the latest changes
hg update
hg commit -m "<what I did>"
hg update -C QA
hg merge default
hg commit -m "merged default branch for QA"
hg sign
hg push

QA

hg pull
hg update QA
hg commit -m "QA fixes"
hg update -C default
hg merge QA
hg ci -m "merged QA fixes back into the development branch"
hg update -C release
hg merge QA
hg commit -m "merged finished QA into release"
hg sign

Modifications

If you need more layers than just developers and QA, just add additional named branches, for example staging-release before release.

To make sure that the code has really been checked by all, you can require that all heads must be GnuPG signed in order to enter a higher-up repository.

Approval Reports

For Whom?

If you need reports showing who approved merging a certain feature, this workflow-fragment could be right for you.

What you need

Mercurial and the GpgExtension. Optionally http://code.google.com/p/hghooklib/wiki/CheckGpgSig from the hghooklib.

Workflow

For generating reports which show who approved a given change you can for example use this: 

for h in $(hg heads --template "{node}\n"); do hg sigcheck $h ; done

For an existing signature this gives something like 

5976560e6777 is signed by:
Arne Babenhauserheide (Physikliebhaber, Hobbysänger und Ideenspringquell)
<arne_bab@web.de>

For missing signatures you get 

No valid signature for a6bc9b77e768

A signature approves all ancestors of the signed revision.

You can check all signatures via 

hg sigs

Configuration management during deployment

For Whom?

The increase of globalization has led to more organizations support everywhere and deploy anywhere in the world. From an experience of having been involved in providing deployment services, I've found that companies can waste lots of time and cost while trying to maintain the software installed at the customer site. If you have done that before, you must remember the minute you were sitting in front of your desk trying to remember which configuration files have been changed or what files been updated the last time you have been there. An efficient management tool and a simple workflow can help organizations complete deployment activities faster and no matter what the size of the organization is.

Workflow

Note that Mercurial saves a local copy of tracked changes in hidden folders at the project folder. If there are any folders, large files or log files that you don’t like to track changes in, use the .hgignore file.

Mark release changes by using the Tag (“hg tag –r 1 version1.4”).

That’s it! From now on, you can track what have been changed and what files have been replaced. Next time you would like to make any changes, just read the repository logs and see what have been changed. Read more: http://eranle.blogspot.co.il/2012/08/configuration-management-with-mercurial.html

Other Sources for Workflows

Workflows (last edited 2020-01-16 06:21:28 by aayjaychan)