Skip to content

Latest commit

 

History

History
134 lines (101 loc) · 5.21 KB

STYLE.md

File metadata and controls

134 lines (101 loc) · 5.21 KB
Raw

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.
  2. Em-dashes are okay, but not recommended when using monospace fonts. Use "—", not "--" or "-".
  3. Always wrap em-dashes in spaces, e.g., "hello — world" not "hello—world".
  4. Hyphenate compound words, e.g., use "platform-specific" not "platform specific".
  5. Use backticks to escape: commands, code expressions, package names, and file paths.
  6. Use less than and greater than symbols to wrap bare URLs, e.g., <https://astral.sh> (unless it is an example; then, use backticks).
  7. Avoid bare URLs outside of reference documentation, prefer labels, e.g., [name](url).
  8. 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.
  9. Markdown files should be wrapped at 100 characters.
  10. Use a space, not an equals sign, for command line arguments with a value, e.g. --resolution lowest, not --resolution=lowest.

Styling uv

Just uv, please.

  1. Do not escape with backticks, e.g., uv, unless referring specifically to the uv executable.
  2. Do not capitalize, e.g., "Uv", even at the beginning of a sentence.
  3. Do not uppercase, e.g., "UV", unless referring to an environment variable, e.g., UV_PYTHON.

Terminology

  1. Use "lockfile" not "lock file".
  2. Use "pre-release", not "prerelease" (except in code, in which case: use Prerelease, not PreRelease; and prerelease, not pre_release).

Documentation

  1. Use periods at the end of all sentences, including lists unless they enumerate single items.
  2. Avoid language that patronizes the reader, e.g., "simply do this".
  3. Only refer to "the user" in internal or contributor documentation.
  4. 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.
  2. May assume basic knowledge of the domain.
  3. Should refer to relevant concept documentation.
  4. Should have a clear flow.
  5. Should be followed by a clear call to action.
  6. Should cover the basic behavior needed to get started.
  7. Should not cover behavior in detail.
  8. Should not enumerate all possibilities.
  9. Should avoid linking to reference documentation unless not covered in a concept document.
  10. May generally ignore platform-specific behavior.
  11. Should be written from second-person point of view.
  12. Should use the imperative voice.

Concepts

  1. Should cover behavior in detail.
  2. Should not enumerate all possibilities.
  3. Should cover most common configuration.
  4. Should refer to the relevant reference documentation.
  5. Should discuss platform-specific behavior.
  6. Should be written from the third-person point of view, not second-person (i.e., avoid "you").
  7. Should not use the imperative voice.

Reference documentation

  1. Should enumerate all options.
  2. Should generally be generated from documentation in the code.
  3. Should be written from the third-person point of view, not second-person (i.e., avoid "you").
  4. Should not use the imperative voice.

Code blocks

  1. All code blocks should have a language marker.
  2. When using console syntax, use $ to indicate commands — everything else is output.
  3. Never use the bash syntax when displaying command output.
  4. Prefer console with $ prefixed commands over bash.
  5. Command output should rarely be included — it's hard to keep up-to-date.
  6. Use title for example files, e.g., pyproject.toml, Dockerfile, or example.py.

CLI

  1. Do not use periods at the end of sentences :), unless the message spans more than a single sentence.
  2. 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.)
  2. NO_COLOR must be respected when using any colors or styling.
  3. UV_NO_PROGRESS must be respected when using progress-styling like bars or spinners.
  4. 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.
  2. 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.
  2. Deprecation warnings must be actionable.

Hints

  1. Errors may be followed by hints suggesting a solution.
  2. Hints should be separated from errors by a blank newline.
  3. Hints should be stylized as hint: <content>.