Differences between revisions 2 and 3
⇤ ← Revision 2 as of 2015-08-19 00:11:54 →
Size: 1286
Editor: Pierre-YvesDavid
Comment: error message
← Revision 3 as of 2015-08-20 05:27:52 → ⇥
Size: 3416
Editor: Pierre-YvesDavid
Comment:
Deletions are marked like this. Additions are marked like this.
Line 12: Line 12:
== 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
Line 17: Line 33:

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`
Line 24: Line 46:
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 BOO ||
|| -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

Line 30: Line 76:
== naming config options == == naming config options ==\

Note:

This page is primarily intended for developers of Mercurial.

Coding Style

How to make build a consistent user experience.

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

Contents

  1. adding UI element
  2. commands
    1. adding new commands
    2. naming commands
  3. argument
    1. naming arguments
    2. common arguments
  4. config
  5. adding new sections
  6. adding new options
  7. output
    1. general output
    2. error message
    3. color
  8. help text

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

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 BOO

-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

4. config

5. adding new sections

6. adding new options

== naming config options ==\

7. output

7.1. general output

7.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) point to help topic if advise//explanation cannot be provided in the hint space,

  • error message should not be punctuated as a sentence. no leading capital, no final dot, (some existing message have a "!").

7.3. color

8. help text

UIGuideline (last edited 2017-08-11 08:52:28 by DavidDemelier)