|
Size: 3415
Comment:
|
Size: 3797
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 74: | Line 74: |
| 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) |
|
| Line 77: | Line 81: |
For boolean option, avoid negative name as they lead fo double negative. * bad: `disablefoobar = False` * good: `enablefoobar = True` |
Note:
This page is primarily intended for developers of Mercurial.
Coding Style
How to make build a consistent user experience.
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
This is a early draft to be filled and reviewed more widely.
Contents
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":
- new config option in the "experimental" section (virtually free, no backward compat needed.
- new config option
- new config section
- new flag to an existing command
- new command
Keep also in mind that we have multiple tier of support
- third party extensions (good for experimenting)
- extensions bundled with core (that have backward compatibility constraint, but can be deprecated as a whole)
- 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
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)
6. adding new options
7. naming config options
For boolean option, avoid negative name as they lead fo double negative.
bad: disablefoobar = False
good: enablefoobar = True
8. output
8.1. general output
8.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 "!").
8.3. color