diff --git a/content/wiki/formatting_scheme.md b/content/wiki/formatting_scheme.md index 07bceed..b4e7754 100644 --- a/content/wiki/formatting_scheme.md +++ b/content/wiki/formatting_scheme.md @@ -51,3 +51,198 @@ We don't recommend it as a permanent config value even for nightly projects, bec In Markdown files, every paragraph should have one line per sentence. This makes git diff easier to read. [[1]](https://nick.groenen.me/notes/one-sentence-per-line/) [[2]](https://sive.rs/1s) + +## Cargo Metadata + +We order metadata in our `Cargo.toml` for packages consistently, in the order: + +* Ordering of sections: `package`, `features`, `dependencies`, `lints`, `profile`, `example`. +* Ordering of `package` fields: `name`, `version`, `description`, `keywords`, `categories`, `edition`, `rust-version`, `license`, `repository`, `homepage`, `exclude`. + +This reduces the number of choices we need to make over time. +This isn't worth failing a review over, but can be cleaned up in a later audit. +Source: [xilem#972](https://github.com/linebender/xilem/pull/972). +`package` includes the docs.rs metadata: + +```toml +[package.metadata.docs.rs] +all-features = true +``` + +We used to implement manually, but no longer need to, so you can remove that. +We must also follow the [linting setup](@/wiki/canonical_lints.md). + +The baseline `.gitignore` should contain only `/target`. We choose not to ignore IDE specific files, but should ignore `.DS_Store`. + +### Taplo + +We currently use Taplo for TOML formatting - config file looks something like: + +```toml +# See https://taplo.tamasfe.dev/configuration/file.html +# and https://taplo.tamasfe.dev/configuration/formatter-options.html + +[formatting] +# Aligning comments with the largest line creates +# diff noise when neighboring lines are changed. +align_comments = false + +# Matches how rustfmt formats Rust code +column_width = 100 +indent_string = " " +``` + +## Setting up no_std properly + +As many of our crates as possible are made `no_std`. +Crates which are `no_std` should have the `"no-std"` crates.io category. +Even for crates which don't use `std`, they still get a default `std` feature, which gates a line such as: + +```rust +// Ensure that we don't compile if you're using the std feature on a platform without `std` +#[cfg(feature = "std")] +extern crate std as _; +``` + +By default, we do not promise to make our crates no-alloc. Crates which would otherwise be `no-alloc` should have a line such as: + +```rust +// Avoid adding alloc in the future being a breaking change. +extern crate alloc as _; +``` + +This means that if we get a user who wishes to use the crate in a `no-alloc` environment then we won't accidentally break them later. +If we do get a request, we should set up dedicated CI for this use case, but we're not aware of this having happened yet, so haven't done so. +There will be a note about this in the `# Features` section of the crate level docs. +See [#blogging > no_std survey @ 💬](https://xi.zulipchat.com/#narrow/channel/181284-blogging/topic/no_std.20survey/near/618972372). + +## Documentation + +All top-level headings in Rust documentation should use single `#` header, only after a `#` can we use a `##` subheading. +Our crate level readme has a `Features` section, which should look something like the following: + +```rust +//! # Features +//! +//! The following crate [feature flags](https://doc.rust-lang.org/cargo/reference/features.html#dependency-features) are available: +//! +//! - `std` (enabled by default): This is currently unused and is provided for forward compatibility. +//! +//! Note that [Crate Name] does require that an allocator is available (i.e. it uses [`alloc`][]). +``` + +For the crates which do the `libm`/`std` dance, those features should be documented as: + +```rust +//! - `std` (enabled by default): Get floating point functions from the standard library +//! (likely using your target's libc). +//! - `libm`: Use floating point implementations from [libm][]. +//! This is useful for `no_std` environments. +//! However, note that the `libm` crate is not as efficient as the standard library. +//! +//! At least one of `std` and `libm` is required; `std` overrides `libm`. +//! Note that [Crate Name] does require that an allocator is available (i.e. it uses [`alloc`][]). +#![cfg_attr(feature = "libm", doc = "[libm]: libm")] +#![cfg_attr(not(feature = "libm"), doc = "[libm]: https://crates.io/crates/libm")] + +#[cfg(not(any(feature = "std", feature = "libm")))] +compile_error!("[Crate Name] requires either the `std` or `libm` feature to be enabled"); +``` + +The docs for each feature should also be copied to their `Cargo.toml` feature description. +"Bare" intra doc links (such as `[Item]`) should be avoided in the top level docs - you must use something like `[Item][]`. +This allows adding an equivalent link to docs.rs in the README to be linted for. + +### Cargo rdme + +We use [cargo-rdme](https://crates.io/crates/cargo-rdme/1.5.1) v1.5.1 for our readmes. +(The 2.0 series is much harder to use due to its handling of intra-doc links) +Each crate README should have the following block: + +```md + + + +[`Affine`]: https://docs.rs/kurbo/latest/kurbo/struct.Affine.html +[`alloc`]: https://doc.rust-lang.org/stable/alloc/ + +``` + +Note that we previously used `--heading-base-level 0`, because we didn't follow the single `#` 'rule'. +Intra-doc links to this or other crates must be to `latest` (or `stable` for crates in the Rust distribution). + +We also choose to document the command at the top of `lib.rs` (after the copyright header but before the doc): + +```rust +// After you edit the crate's doc comment, run this command, then check README.md for any missing links +// cargo rdme --workspace-project=gazeto +``` + +### Readme Setup + +The readme order for individual packages is as follows. We don't yet have the format fully worked out for workspace (i.e. repository) level readmes. + +```md +
+ +# Name (Title Case) + +**Tagline** + +[![Latest published version.](https://img.shields.io/crates/v/vello.svg)](https://crates.io/crates/vello) +[![Documentation build status.](https://img.shields.io/docsrs/vello.svg)](https://docs.rs/vello) +[![Apache 2.0 or MIT license.](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](#license) +\ +[![Linebender Zulip chat.](https://img.shields.io/badge/Linebender-%23gpu-blue?logo=Zulip)](https://xi.zulipchat.com/#narrow/stream/197075-gpu) +[![GitHub Actions CI status.](https://img.shields.io/github/actions/workflow/status/linebender/vello/ci.yml?logo=github&label=CI)](https://github.com/linebender/vello/actions) +[![Dependency staleness status.](https://deps.rs/crate/vello/latest/status.svg)](https://deps.rs/crate/vello) + +
+ + + +... + + + +## Minimum supported Rust Version (MSRV) + +This version of [Crate Name] has been verified to compile with **Rust 1.96** and later. + +Future versions of [Crate Name] might increase the Rust version requirement. +It will not be treated as a breaking change and as such can even happen with small patch releases. + +## Community + + +Discussion of [Crate Name] development happens in the [Linebender Zulip](https://xi.zulipchat.com/), specifically the [#general channel](https://xi.zulipchat.com/#narrow/channel/147921-general). +All public content can be read without logging in. + +## License + +Licensed under either of + +- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or ) +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or ) + +at your option. + +## Contribution + +Contributions are welcome by pull request. The [Rust code of conduct] applies. +Please feel free to add your name to the [AUTHORS] file in any substantive pull request. + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions. + +[Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct +[AUTHORS]: ../AUTHORS +``` + +We haven't yet decided on the badges for top-level readmes. +See [#linebender > Bikeshedding badges @ 💬](https://xi.zulipchat.com/#narrow/channel/419691-linebender/topic/Bikeshedding.20badges/near/600855247). + +Each crate must have their license files copied into the crate, as well as at the top level.