diff options
| author | Evan Read <eread@gitlab.com> | 2023-09-08 17:48:14 +0300 |
|---|---|---|
| committer | Sami Hiltunen <shiltunen@gitlab.com> | 2023-09-08 17:48:14 +0300 |
| commit | 94056c199c091fb6842a7ffc67df2347e2ec9041 (patch) | |
| tree | 8a59e05ff7c975839442be36bfa51f4c52e10d81 /doc | |
| parent | 69b963287fdb69c55ca41864ac5e4ec8b2dc0d63 (diff) | |
Update Gitaly CLI command help text with usage text
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/help_text_style_guide.md | 23 |
1 files changed, 19 insertions, 4 deletions
diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md index 8c01b85b4..529df6985 100644 --- a/doc/help_text_style_guide.md +++ b/doc/help_text_style_guide.md @@ -13,6 +13,20 @@ 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. +- Always provide a value for the `UsageText` field key. Use this field key to provide: + + - A template for invocation with placeholder values. + - Optional flags in square brackets. + - One or more examples with plausible values. + + For example: + + ```go + UsageText: `gitaly subcommand <placeholder_value> --mandatory-flag <placeholder_value> [--optional-flag] + + Example: gitaly subcommand plausible-value.toml --mandatory-flag plausible-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. @@ -33,10 +47,11 @@ To help users discover `gitaly` and `praefect` features through the CLI: 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` | Yes | No | `Usage: "short description of example command"` | +| Field key | All lower case | Use period | Example key and value | +|:--------------|:---------------|:-----------|:----------------------| +| `Name` | Yes | No | `Name: "example"` | +| `Usage` | Yes | No | `Usage: "short description of example command"` | +| `UsageText` | No | No | `example subcommand <example_placeholder>\n\nExample: example subcommand plausible-value.toml` | | `Description` | No | Yes | `Description: "This is a long description of all the things example command can do."` | ### Specific rules for `Usage` |