#pragma section-numbers 2
<<Include(A:dev)>>

= UI Guidelines =

How to make build a consistent user experience.

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

<<TableOfContents>>

== 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.)
 1. new config option
 1. new config section
 1. new flag to an existing command 
 1. new command

Keep also in mind that we have multiple tier of support

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

== commands ==

=== adding new commands ===

=== 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`

== argument ==

=== naming arguments ===

=== common arguments ===

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

|| short || long || used for ||
|| -r REV || --rev REV || specifying revisions ||
|| -f || --force || forcing as operation ||
|| -S || --subrepos || act recursively on subrepositories ||
|| -B BOOK || --bookmark BOOK || do something with/related to bookmark BOOK ||
|| -T TEMPLATE || --template || display changesets//output using TEMPLATE ||
|| -t TOOL || --tool TOOL || merge tool to be used for merging ||
|| -I PATTERN || --include PATTERN || include names matching the given patterns ||
|| -X PATTERN || --exclude PATTERN || exclude names matching the given patterns ||



Some pattern are specific to command that create/alter changesets

|| short || long || used for ||
|| -m MSG || --message || message to be used for the changeset/action ||
|| -e || --edit || edit the message ||
|| -l FILE || --logfile FILE || get message from FILE ||

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


== config ==

=== 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)

=== adding new options ===

=== 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`

== output ==

=== 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.

=== 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 "!").

=== color ===

 * Always ensure UIs are usable '''without''' color. Some users don't like color, and a good fraction of the population has [[https://en.wikipedia.org/wiki/Color_blindness|non-normal color perception]].

=== 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"

== help text ==