Advice

Some suggestions on giving advice to Mercurial users.

1. Diagnose first, suggest fixes later

Please don't make suggestions for work-arounds before figuring out what the precise problem is. This is important for several reasons. First, if a user uses a work-around, we may be unable to diagnose an important bug. Second, if the problem is user error, they'll continue to make the same mistake and continue to blame the tool. And finally, guessing at a work-around is likely to make a problem worse.

Useful tools:

2. Detect conceptual problems

Many problems are due to users applying their conceptual map from other systems (CVS, Git) to Mercurial. This usually results in very strange questions that make little sense in the Mercurial environment. It's usually best to follow up such questions with "what are you trying to do?" to find out what the underlying conceptual problem is.

Useful tools:

Mapping concepts of other SCMs to Mercurial:

3. Recommend safe built-in functionality first

<!> Recommend 'clone -r' before 'strip'!

It's tempting to immediately recommend extensions like 'MQ' and 'transplant' to new users to solve common tasks. But remember that extensions are extensions for a reason - they're potentially dangerous and are not considered suitable for new users still grappling with Mercurial's basics! Also, most extension functionality can be obtained with core features. In particular, 'transplant' can be accomplished with 'export' + 'import' and 'strip' can be done (safely!) with 'clone -r'.

<!> Don't recommend 'rollback'!

As the only destructive command in Mercurial's core, advising a user to "just run rollback" is a good way to get a user to permanently destroy their data. Instead recommend they see 'hg help rollback' so they're aware of its effects and limitations.

4. Encourage new users to abandon legacy features

People converting from CVS and SVN are often attached to CVS's EOL and keyword features. Many modern SCMs have intentionally deprecated or dropped these features and some designers of SVN have gone on record as regretting copying them from CVS.

Mercurial only supports these legacy features through extensions while the core was intentionally designed without consideration for them. Users who migrate away from these features will have better support and a better overall Mercurial experience.

5. Help improve Mercurial documentation

If someone has an issue that might have been remedied by clearer documentation, consider contributing a patch to improve it. See the developer information page and tips for contributing changes to get started.


CategoryBugs CategoryProject

Advice (last edited 2010-10-21 12:14:58 by HenrikStuart)