Skip to content

Latest commit

 

History

History
96 lines (69 loc) · 2.76 KB

CONTRIBUTING.md

File metadata and controls

96 lines (69 loc) · 2.76 KB
Raw

Contributing to the API guidelines

The Rust API guidelines project welcomes contribution from everyone in the form of suggestions, bug reports, pull requests, and feedback. This document gives some guidance if you are thinking of helping us.

Please reach out here in a GitHub issue or in our Gitter channel if we can do anything to help you contribute.

Submitting ideas for new guidelines

We are always looking out for lessons to learn from high-quality Rust libraries. If you spot an aspect of some crate's API that you think other crates could benefit from, please open a discussion to let us know.

If you'd like to propose a specific amendment to an existing guideline you can also open an issue.

Writing content for the guidelines

The guidelines are written in a collection of Markdown files under the src directory. When making changes, you can preview the rendered content using mdBook.

cargo install mdbook

# In the api-guidelines directory
mdbook serve

The mdbook serve command makes the rendered API guidelines available as a web page at http://localhost:3000/.

Guidelines for the guidelines

We follow some basic grammatical rules to ensure that the checklist of guidelines remains consistent and intelligible.

A guideline is an indicative statement about a hypothetical crate.

  Not an imperative like
- "Implement Hex, Octal, Binary for binary number types"
  Instead:
+ "Binary number types provide Hex, Octal, Binary formatting"

  Not an obligation like
- "Macros should compose well with attributes"
  Instead:
+ "Macros compose well with attributes"

Guidelines have an explicit subject and verb.

  Not implicit subject like
- "Includes all common Cargo.toml metadata"
  Instead:
+ "Cargo.toml includes all common metadata"

  Not implicit verb like
- "Thoroughly documented with examples"
  Instead:
+ "Crate level docs are thorough and include examples"

  Not metaphysical like
- "There are no out-parameters"
  Instead:
+ "Functions do not take out-parameters"

Guidelines use active voice.

  Not passive voice like
- "Function arguments are validated"
  Instead:
+ "Functions validate their arguments"

Conduct

As with all Rust-related spaces, we observe the Rust Code of Conduct. For escalation or moderation issues please contact the Rust moderation team, [email protected].