API Guidelines
๐Ÿคนโ€โ™‚๏ธ ย  Lead: dtolnay
๐Ÿ˜บ ย  Chat: WG-libs-guidelines
๐Ÿ’พ ย  Source: https://github.com/rust-lang-nursery/api-guidelines
๐Ÿ“– ย  Published: https://rust-lang-nursery.github.io/api-guidelines

Getting started

The best way to start is to read this document, then join the chat and say hello! Weโ€™ll help you from there.

Background

The API Guidelines are a checklist of recommendations on how to design and present the API of a Rust library. They are based on the authorsโ€™ experiences building the Rust standard library and important crates.

As part of the Libz Blitz weโ€™ve been learning from the API decisions made by high-quality foundational Rust libraries and distilling that knowledge into broadly applicable recommendations to drive consistency, completeness, and quality across the library ecosystem.

Goals

By the end of the impl period, we should proudly recommend the API Guidelines as a resource for experienced developers as well as budding library authors to level up the crates that they contribute to.

  • Content โ€” Throughout the Libz Blitz we have kept track of dozens of API lessons learned, but still need to synthesize most of these into broadly applicable guidelines.

  • Focus โ€” Not all of the current guidelines carry their weight. We need to condense down to the ones we feel most strongly about to keep everything maximally relevant.

  • Presentation โ€” The guidelines are presented in a compact checklist form that a library author familiar with the material can quickly evaluate against one of their crates. Each guideline then has a long-form explanation discussing the motivations, exceptions, and examples. The content needs to be easy to consume for new readers as well as experienced users running through the checklist for the nth time.

  • Revision โ€” All content will need an editing pass to make sure that justifications are logically presented, examples are on point, and the material is cohesive and professional.

Work remaining

The work items for this working group are tracked via issues in the rust-lang-nursery/api-guidelines repository. You can also find them on the find-work website.ย