From 60a539ccfe06c1bacf13f2fb65daab9268a1ce49 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Thu, 18 Jul 2024 21:07:07 -0500 Subject: [PATCH 1/8] Add a style guide --- STYLE.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 000000000000..f0fa8ae429e0 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,87 @@ +# 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)`. + +## 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". +1. Do not uppercase, e.g., "UV". + +## Documentation + +1. Use periods at the end of all sentences, including lists unless they enumerate single items. +1. Avoid language that patronizers the reader, e.g., "simply do this". + +### Sections + +The documentation is divided into: + +1. Guides +2. Concepts +3. Reference documentation + +#### Guides + +1. Should assume no previous knowledge. +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. May be written from second-person point of view, though we prefer third-person at this time. + +#### 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"). + +#### 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"). + +### 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. When instructing the user to execute a command, it should be bolded. +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. + +### Logging + +1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag. +1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag. +1. All logging should be to stderr. +1. Text can be written to stdout if they are "data" that could be piped to another program. From cb5bb37b999fb9676c9228d7c82f0ad0a36a3071 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Fri, 19 Jul 2024 09:53:01 -0400 Subject: [PATCH 2/8] Some additions --- STYLE.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/STYLE.md b/STYLE.md index f0fa8ae429e0..cfd6953d7f8f 100644 --- a/STYLE.md +++ b/STYLE.md @@ -9,8 +9,9 @@ _The following is a work-in-progress style guide for our user-facing messaging i 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. 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 @@ -23,7 +24,7 @@ Just uv, please. ## Documentation 1. Use periods at the end of all sentences, including lists unless they enumerate single items. -1. Avoid language that patronizers the reader, e.g., "simply do this". +1. Avoid language that patronizes the reader, e.g., "simply do this". ### Sections @@ -43,7 +44,7 @@ The documentation is divided into: 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. May generally ignore platform-specific behavior. 1. May be written from second-person point of view, though we prefer third-person at this time. #### Concepts @@ -75,7 +76,8 @@ The documentation is divided into: ### Colors and style -1. When instructing the user to execute a command, it should be bolded. +1. All CLI output should 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. In general, we use: green for success, red for error, yellow for warning, and cyan for hints; cyan for file paths, cyan for salient user-facing values (e.g., a package name in a message), and green for commands. 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. From 3c81d6039a63adcf4c2640cb585a1a6ed534fa03 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Fri, 19 Jul 2024 09:53:51 -0400 Subject: [PATCH 3/8] List --- STYLE.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index cfd6953d7f8f..993e33906201 100644 --- a/STYLE.md +++ b/STYLE.md @@ -77,9 +77,16 @@ The documentation is divided into: ### Colors and style 1. All CLI output should 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. In general, we use: green for success, red for error, yellow for warning, and cyan for hints; cyan for file paths, cyan for salient user-facing values (e.g., a package name in a message), and green for commands. 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, we 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 From 3107ecc40cfe096b37d274edde41bdbe75146953 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 19 Jul 2024 09:04:18 -0500 Subject: [PATCH 4/8] Add a style guide --- STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 993e33906201..dffd4ef5cc08 100644 --- a/STYLE.md +++ b/STYLE.md @@ -9,7 +9,7 @@ _The following is a work-in-progress style guide for our user-facing messaging i 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. 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. From 041ce15d5f25567abf555830372c9a1ee3034622 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 19 Jul 2024 11:33:34 -0500 Subject: [PATCH 5/8] Voice edits --- STYLE.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/STYLE.md b/STYLE.md index dffd4ef5cc08..c65b63eade35 100644 --- a/STYLE.md +++ b/STYLE.md @@ -25,6 +25,7 @@ Just uv, please. 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. ### Sections @@ -36,7 +37,7 @@ The documentation is divided into: #### Guides -1. Should assume no previous knowledge. +1. Should assume no previous knowledge about uv. 1. Should refer to relevant concept documentation. 1. Should have a clear flow. 1. Should be followed by a clear call to action. @@ -45,7 +46,8 @@ The documentation is divided into: 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. May be written from second-person point of view, though we prefer third-person at this time. +1. Should be written from second-person point of view. +1. Should use the imperative voice. #### Concepts @@ -55,12 +57,14 @@ The documentation is divided into: 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 From 7aebd2e2dfb0d996b05e3f0fc3a227cee68bcbb8 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 19 Jul 2024 11:41:58 -0500 Subject: [PATCH 6/8] Some review feedback --- STYLE.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/STYLE.md b/STYLE.md index c65b63eade35..7095582e7bce 100644 --- a/STYLE.md +++ b/STYLE.md @@ -26,6 +26,7 @@ Just uv, please. 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 @@ -38,6 +39,7 @@ The documentation is divided into: #### 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. @@ -80,10 +82,10 @@ The documentation is divided into: ### Colors and style -1. All CLI output should 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. 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, we use: +1. In general, use: - Green for success. - Red for error. - Yellow for warning. @@ -95,6 +97,22 @@ The documentation is divided into: ### Logging 1. `warn`, `info`, `debug`, and `trace` logs are all shown with the `--verbose` flag. -1. `warn_user` and `warn_user_once` are shown without the `--verbose `flag. + - Note that the displayed level is controlled with `RUST_LOG`. 1. All logging should be to stderr. -1. Text can be written to stdout if they are "data" that could be piped to another program. + +### 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: `. From 3feabce031d8afe2dc1a72f297e03c820ee90448 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 19 Jul 2024 11:45:58 -0500 Subject: [PATCH 7/8] Update STYLE.md --- STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 7095582e7bce..7cb34b7119da 100644 --- a/STYLE.md +++ b/STYLE.md @@ -18,7 +18,7 @@ _The following is a work-in-progress style guide for our user-facing messaging i 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". +1. Do not capitalize, e.g., "Uv", even at the beginning of a sentence. 1. Do not uppercase, e.g., "UV". ## Documentation From 895de11c11ee41b7094557499fd3cae80fecbeb7 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Mon, 22 Jul 2024 12:31:53 -0500 Subject: [PATCH 8/8] Update STYLE.md --- STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 7cb34b7119da..bd01eee7eb06 100644 --- a/STYLE.md +++ b/STYLE.md @@ -19,7 +19,7 @@ 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". +1. Do not uppercase, e.g., "UV", unless referring to an environment variable, e.g., `UV_PYTHON`. ## Documentation