blob: 4f4f764a8177ac59bb594b8fd06e26f5b7f62722 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
# Help text style guide
The command-line interface (CLI) tools `gitaly` and `praefect` are the primary interfaces to Gitaly and Gitaly Cluster.
For this reason, it's important that help text is standardized and complete.
The [`urfave/cli` library](https://cli.urfave.org) is used for CLI tooling in this project. It provides a number of
options for developers to provide help text to users.
## Rules for options
To help users discover `gitaly` and `praefect` features through the CLI:
- Always provide a value for the `Description` field key. This field key provides a lot of space to describe the command
or subcommand. At a minimum, provide a longer full sentence restatement of (but don't duplicate) the `Usage` field key
value.
- Because of a [known issue](https://gitlab.com/gitlab-org/gitaly/-/issues/5350), always set the `HideHelpCommand`
field key to `true`. Setting this hides the `COMMANDS:` section of the help text,
which hides a generated list of available subcommands, if available.
Instead, list subcommands in the value of the `Description` field key. For example:
```go
Description: "This is a long description of all the things example command can do.\n\n" +
"Provides the following subcommands:\n\n" +
"- subcommand1\n\n" +
"- subcommand2\n\n",
```
## Rules for command strings
When adding or updating `gitaly` and `praefect` CLI tools, use the following guidance for values for the different field
keys for commands and subcommands:
| Field key | All lower case | Use period | Example key and value |
|:--------------|:---------------|:-----------|:--------------------------------------------------------------------------------------|
| `Name` | Yes | No | `Name: "example"` |
| `Usage` | No | No | `Usage: "Short description of example command"` |
| `Description` | No | Yes | `Description: "This is a long description of all the things example command can do."` |
### Specific rules for `Description`
When providing values for the `Description` key:
- If referring to the subcommand itself, put the subcommand in backticks. For example:
```plaintext
`subcommand` can be run at any time.
```
## Related topics
- [Voice and tone](https://design.gitlab.com/content/voice-and-tone) from GitLab Design System.
- [Language](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language) from GitLab
Documentation Style Guide.
|