Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitaly.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--.editorconfig16
-rw-r--r--cmd/gitaly/main_test.go4
-rw-r--r--doc/configuration/README.md18
-rw-r--r--doc/help_text_style_guide.md56
-rw-r--r--internal/cli/gitaly/app.go2
-rw-r--r--internal/cli/gitaly/check.go2
-rw-r--r--internal/cli/gitaly/configuration-validate.go26
-rw-r--r--internal/cli/gitaly/hooks.go18
-rw-r--r--internal/cli/gitaly/serve.go2
9 files changed, 101 insertions, 43 deletions
diff --git a/.editorconfig b/.editorconfig
index c8f2af68c..424fdec3a 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -7,6 +7,7 @@ charset = utf-8
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
+max_line_length = 120
[Makefile]
indent_style = tab
@@ -16,20 +17,7 @@ indent_size = unset
indent_style = tab
indent_size = 8
tab_width = 8
-max_line_length = 100
-[**.md]
-max_line_length = 80
-
-[**.proto]
-indent_style = space
-indent_size = 2
-max_line_length = 100
-
-[**.rb]
-indent_size = 2
-indent_style = space
-
-[**.yml]
+[**.{md,proto,yml}]
indent_style = space
indent_size = 2
diff --git a/cmd/gitaly/main_test.go b/cmd/gitaly/main_test.go
index 58113c9be..a6c2a1937 100644
--- a/cmd/gitaly/main_test.go
+++ b/cmd/gitaly/main_test.go
@@ -30,7 +30,7 @@ func TestGitalyCLI(t *testing.T) {
{
desc: "without arguments",
exitCode: 2,
- stdout: "NAME:\n gitaly - a Git RPC service\n\nUSAGE:\n gitaly command [command options] [arguments...]\n\nDESCRIPTION:\n Gitaly is a Git RPC service for handling Git calls.\n\nCOMMANDS:\n serve launch the server daemon\n check verify internal API is accessible\n configuration run configuration-related commands\n hooks manage Git hooks\n\nOPTIONS:\n --help, -h show help\n --version, -v print the version\n",
+ stdout: "NAME:\n gitaly - A Git RPC service\n\nUSAGE:\n gitaly command [command options] [arguments...]\n\nDESCRIPTION:\n Gitaly is a Git RPC service for handling Git calls.\n\nCOMMANDS:\n serve Launch the server daemon\n check Verify internal API is accessible\n configuration Run configuration-related commands\n hooks Manage Git hooks\n\nOPTIONS:\n --help, -h show help\n --version, -v print the version\n",
},
{
desc: "with non-existent config",
@@ -42,7 +42,7 @@ func TestGitalyCLI(t *testing.T) {
desc: "check without config",
args: []string{"check"},
exitCode: 2,
- stdout: "NAME:\n gitaly check - verify internal API is accessible\n\nUSAGE:\n gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n Check that the internal Gitaly API is accessible.\n\nOPTIONS:\n --help, -h show help\n",
+ stdout: "NAME:\n gitaly check - Verify internal API is accessible\n\nUSAGE:\n gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n Check that the internal Gitaly API is accessible.\n\nOPTIONS:\n --help, -h show help\n",
stderr: "invalid argument(s)",
},
{
diff --git a/doc/configuration/README.md b/doc/configuration/README.md
index 877a4b9bd..1e6d89b47 100644
--- a/doc/configuration/README.md
+++ b/doc/configuration/README.md
@@ -160,18 +160,16 @@ pattern. All error messages are logged unconditionally.
By default, health check gRPC messages are not logged. To enable them,
set `GITALY_LOG_REQUEST_METHOD_ALLOW_PATTERN` to `.`.
-### Validation
+### Validate Gitaly configuration
-The `gitaly configuration validate` sub-command validates the provided configuration. Use `validate` before starting the service.
+To validate Gitaly configuration, use `gitaly configuration validate`. For example:
-`validate` prints all configuration problems to `STDOUT` in JSON format.
-The output's structure includes:
-
-- A key, which is the path to the configuration field where the problem is detected.
-- A message, with an explanation of the problem.
+```shell
+gitaly configuration validate < gitaly.config.toml
+```
-#### Usage
+For more information, run:
```shell
-gitaly configuration validate
-``` \ No newline at end of file
+gitaly configuration validate --help
+```
diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md
new file mode 100644
index 000000000..4f4f764a8
--- /dev/null
+++ b/doc/help_text_style_guide.md
@@ -0,0 +1,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.
diff --git a/internal/cli/gitaly/app.go b/internal/cli/gitaly/app.go
index 50bb3b7f3..b5cdad174 100644
--- a/internal/cli/gitaly/app.go
+++ b/internal/cli/gitaly/app.go
@@ -19,7 +19,7 @@ func init() {
func NewApp() *cli.App {
return &cli.App{
Name: "gitaly",
- Usage: "a Git RPC service",
+ Usage: "A Git RPC service",
Description: "Gitaly is a Git RPC service for handling Git calls.",
Version: version.GetVersionString("Gitaly"),
// serveAction is also here in the root to keep the CLI backwards compatible
diff --git a/internal/cli/gitaly/check.go b/internal/cli/gitaly/check.go
index 8e66a1f1c..bba97f908 100644
--- a/internal/cli/gitaly/check.go
+++ b/internal/cli/gitaly/check.go
@@ -16,7 +16,7 @@ import (
func newCheckCommand() *cli.Command {
return &cli.Command{
Name: "check",
- Usage: "verify internal API is accessible",
+ Usage: "Verify internal API is accessible",
Description: "Check that the internal Gitaly API is accessible.",
ArgsUsage: "<configfile>",
Action: checkAction,
diff --git a/internal/cli/gitaly/configuration-validate.go b/internal/cli/gitaly/configuration-validate.go
index 64e0327e8..a3cd0e25f 100644
--- a/internal/cli/gitaly/configuration-validate.go
+++ b/internal/cli/gitaly/configuration-validate.go
@@ -11,16 +11,28 @@ const validationErrorCode = 2
func newConfigurationCommand() *cli.Command {
return &cli.Command{
- Name: "configuration",
- Usage: "run configuration-related commands",
- Description: "Run commands related to Gitaly configuration.",
+ Name: "configuration",
+ Usage: "Run configuration-related commands",
+ Description: "Run commands related to Gitaly configuration.\n\n" +
+
+ "Provides the following subcommand:\n\n" +
+
+ "- validate",
HideHelpCommand: true,
Subcommands: []*cli.Command{
{
- Name: "validate",
- Usage: "validate configuration",
- Description: "check that configuration provided on stdin is valid.",
- Action: validateConfigurationAction,
+ Name: "validate",
+ Usage: "Validate Gitaly configuration",
+ Description: "Check that input provided on stdin is valid Gitaly configuration.\n" +
+ "Use `validate` before starting Gitaly.\n\n" +
+
+ "Prints all configuration problems to stdout in JSON format.\n" +
+ "The output's structure includes:\n\n" +
+
+ "- A key, which is the path to the configuration field where the\n" +
+ " problem is detected.\n" +
+ "- A message, with an explanation of the problem.",
+ Action: validateConfigurationAction,
},
},
}
diff --git a/internal/cli/gitaly/hooks.go b/internal/cli/gitaly/hooks.go
index d4affbb1b..31dd5b843 100644
--- a/internal/cli/gitaly/hooks.go
+++ b/internal/cli/gitaly/hooks.go
@@ -27,29 +27,33 @@ const (
func newHooksCommand() *cli.Command {
return &cli.Command{
- Name: "hooks",
- Usage: "manage Git hooks",
- Description: "Manage hooks for a Git repository.",
+ Name: "hooks",
+ Usage: "Manage Git hooks",
+ Description: "Manage hooks for a Git repository.\n\n" +
+
+ "Provides the following subcommand:\n\n" +
+
+ "- set",
HideHelpCommand: true,
Subcommands: []*cli.Command{
{
Name: "set",
- Usage: "set custom hooks for a Git repository",
+ Usage: "Set custom hooks for a Git repository",
Description: "Reads a tarball containing custom Git hooks from stdin and writes the hooks to the specified repository.",
Action: setHooksAction,
Flags: []cli.Flag{
&cli.StringFlag{
Name: flagStorage,
- Usage: "storage containing the repository",
+ Usage: "Storage containing the repository",
},
&cli.StringFlag{
Name: flagRepository,
- Usage: "repository to set hooks for",
+ Usage: "Repository to set hooks for",
Required: true,
},
&cli.StringFlag{
Name: flagConfig,
- Usage: "path to Gitaly config",
+ Usage: "Path to Gitaly configuration",
Aliases: []string{"c"},
Required: true,
},
diff --git a/internal/cli/gitaly/serve.go b/internal/cli/gitaly/serve.go
index 78aa7d56c..a4ae23e81 100644
--- a/internal/cli/gitaly/serve.go
+++ b/internal/cli/gitaly/serve.go
@@ -53,7 +53,7 @@ import (
func newServeCommand() *cli.Command {
return &cli.Command{
Name: "serve",
- Usage: "launch the server daemon",
+ Usage: "Launch the server daemon",
Description: "Launch the Gitaly server daemon.",
ArgsUsage: "<configfile>",
Action: serveAction,
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-27 15:22:19 +0300