From 337a1c20834bf1eb2385401fcc10d5211dd2e53e Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 23 Jul 2024 13:57:32 -0400 Subject: [PATCH] Add a style guide (#5209) Co-authored-by: Charlie Marsh --- STYLE.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 000000000..bd01eee7e --- /dev/null +++ b/STYLE.md @@ -0,0 +1,118 @@ +# Style guide + +_The following is a work-in-progress style guide for our user-facing messaging in the CLI output and documentation_. + +## General + +1. Use of "e.g." and "i.e." should always be wrapped in commas, e.g., as shown here. +1. Em-dashes are okay, but not recommended when using monospace fonts. Use "—", not "--" or "-". +1. Always wrap em-dashes in spaces, e.g., "hello — world" not "hello—world". +1. Hyphenate compound words, e.g., use "platform-specific" not "platform specific". +1. Use backticks to escape: commands, code expressions, package names, and file paths. +1. Use less than and greater than symbols to wrap bare URLs, e.g., `` (unless it is an example; then, use backticks). +1. Avoid bare URLs outside of reference documentation, prefer labels, e.g., `[name](url)`. +1. If a message ends with a single relevant value, precede it with a colon, e.g., `This is the value: value`. If the value is a literal, wrap it in backticks. + +## Styling uv + +Just uv, please. + +1. Do not escape with backticks, e.g., `uv`, unless referring specifically to the `uv` executable. +1. Do not capitalize, e.g., "Uv", even at the beginning of a sentence. +1. Do not uppercase, e.g., "UV", unless referring to an environment variable, e.g., `UV_PYTHON`. + +## Documentation + +1. Use periods at the end of all sentences, including lists unless they enumerate single items. +1. Avoid language that patronizes the reader, e.g., "simply do this". +1. Only refer to "the user" in internal or contributor documentation. +1. Avoid "we" in favor of "uv" or imperative language. + +### Sections + +The documentation is divided into: + +1. Guides +2. Concepts +3. Reference documentation + +#### Guides + +1. Should assume no previous knowledge about uv. +1. May assume basic knowledge of the domain. +1. Should refer to relevant concept documentation. +1. Should have a clear flow. +1. Should be followed by a clear call to action. +1. Should cover the basic behavior needed to get started. +1. Should not cover behavior in detail. +1. Should not enumerate all possibilities. +1. Should avoid linking to reference documentation unless not covered in a concept document. +1. May generally ignore platform-specific behavior. +1. Should be written from second-person point of view. +1. Should use the imperative voice. + +#### Concepts + +1. Should cover behavior in detail. +1. Should not enumerate all possibilities. +1. Should cover most common configuration. +1. Should refer to the relevant reference documentation. +1. Should discuss platform-specific behavior. +1. Should be written from the third-person point of view, not second-person (i.e., avoid "you"). +1. Should not use the imperative voice. + +#### Reference documentation + +1. Should enumerate all options. +1. Should generally be generated from documentation in the code. +1. Should be written from the third-person point of view, not second-person (i.e., avoid "you"). +1. Should not use the imperative voice. + +### Code blocks + +1. All code blocks should have a language marker. +1. When using `console` syntax, use `$` to indicate commands — everything else is output. +1. Do not use the `bash` syntax when displaying command output. +1. Command output should rarely be included — it's hard to keep up to date. + +## CLI + +1. Do not use periods at the end of sentences :), unless the message spans more than a single sentence. +1. May use the second-person point of view, e.g., "Did you mean...?". + +### Colors and style + +1. All CLI output must be interpretable and understandable _without_ the use of color and other styling. (For example: even if a command is rendered in green, wrap it in backticks.) +1. `NO_COLOR` must be respected when using any colors or styling. +1. `UV_NO_PROGRESS` must be respected when using progress-styling like bars or spinners. +1. In general, use: + - Green for success. + - Red for error. + - Yellow for warning. + - Cyan for hints. + - Cyan for file paths. + - Cyan for important user-facing literals (e.g., a package name in a message). + - Green for commands. + +### Logging + +1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag. + - Note that the displayed level is controlled with `RUST_LOG`. +1. All logging should be to stderr. + +### Output + +1. Text can be written to stdout if it is "data" that could be piped to another program. + +### Warnings + +1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag. + - These methods should be preferred over tracing warnings when the warning is actionable. + - Deprecation warnings should use these methods. +1. Deprecation warnings must be actionable. + +### Hints + +1. Errors may be followed by hints suggesting a solution. +1. Hints should be separated from errors by a blank newline. +1. Hints should be stylized as `hint: `.