UI Guidelines

How to make build a consistent user experience.

This is a early draft to be filled and reviewed more widely.

1. adding UI element

The general philosophy is that adding is easier than removing. So we tend to start small and add things when it is clear it make senses to make it more widely available. Here are the possible methods to introduce new user interface point. Sorted by increasing "cost":

1. new config option in the "experimental" section (virtually free, no backward compat needed.)
2. new config option
3. new config section
4. new flag to an existing command
5. new command

Keep also in mind that we have multiple tier of support

1. third party extensions (good for experimenting)
2. extensions bundled with core (that have backward compatibility constraint, but can be deprecated as a whole)
3. core mercurial

2. commands

2.1. adding new commands

2.2. naming commands

We have two styles of naming currently in fashion

- noun: command can be named after the concept they refer to. eg: hg bookmarks, hg phases hg heads

- verbs: command can also be named after the action they perform, eg: hg rebase, hg graft, hg merge, hg resolve

3. argument

3.1. naming arguments

3.2. common arguments

Here is a list of argument use in multiple commands, avoid to pick colliding short version as it will likely confuse people

Some pattern are specific to command that create/alter changesets

Some commands like hg status unfortunately breaks this pattern, this get very confusing for users

4. config

4.1. adding new sections

Try to avoid adding a new section for a single entry. Do add a new section when you are introducing a new concept and already know that multiple option will fit in.

(note: we should get a way to list all config option and section)

4.2. adding new options

4.3. naming config options

Use hyphens between words for every new option.

• bad: allow_pull = john

• good: allow-pull = john

For boolean option, avoid negative name as they lead to double negative.

• bad: disable-foobar = False

• good: enable-foobar = True

5. output

5.1. general output

• We never handle pluralization in Mercurial output. If an item could be plural, use the plural for to refer to it in all case.

5.2. error message

• Error message should fit on 'a single' 80 characters line,
• a hint should be provided to point the user toward a solution (78 chars max),

abort: uncommitted changes
("use 'hg status' to list changes")

• error message should include the offending item when possible,

abort: push creates new remote head 02793c56c8d3!
(merge or see "hg help push" for details about pushing new heads)

• error should not blindly point to dangerous operation (eg: --force)

• when advise//explanation cannot be provided in the hint space, point to the appropriate help topic ,
• error message should not be punctuated as a sentence. no leading capital, no final dot, (some existing message have a "!").

5.3. color

• Always ensure UIs are usable without color. Some users don't like color, and a good fraction of the population has non-normal color perception.

5.4. progress

• progress should describe work being done: e.g. "getting files", "rebuilding"

• users should be able to see what progress is measuring, specify unit in progress: e.g. "files", "changesets", "bytes"

• don't forget to make unit plural:

  • good: "1/3 files", "1000 changesets/sec"
  • bad: "1/3 file", "1000 changeset/sec"

6. help text