|
2 | 2 |
|
3 | 3 | If you're an author of a crate within the `rust-seq` stack _or_ you would like |
4 | 4 | to be, you can use the following checklist to ensure that your crates meet the |
5 | | -above values. Note that these are just suggestions to adhere to the values |
6 | | -above—completing every item is not a requirement to ratify a particular crate. |
| 5 | +above values. For each value, recommendations are listed roughly in order of |
| 6 | +most preferrable to least. Note that these are just suggestions to adhere to the |
| 7 | +values above—completing every item is not a requirement to ratify a particular |
| 8 | +crate. |
7 | 9 |
|
8 | | -## Performance |
| 10 | +To learn more about any particular value, please see [this |
| 11 | +link](../get-started/values). |
| 12 | + |
| 13 | +### Correctness |
| 14 | + |
| 15 | +- [x] Write comprehensive tests to check that all invariants are upheld in the |
| 16 | + crate's logic (these also serve as documentation for your code!). |
| 17 | +- [x] If you are returning user-facing errors, consider using the |
| 18 | + [`anyhow`](https://docs.rs/anyhow/latest/anyhow) crate. Most importantly, |
| 19 | + this means (a) returning `anyhow::Result` for your `fn main()`, and (b) using the |
| 20 | + [`context()`](https://docs.rs/anyhow/latest/anyhow/trait.Context.html#tymethod.context) |
| 21 | + method to add additional context wherever errors might occur. |
| 22 | +- [x] Ensure that all errors implement |
| 23 | + [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) |
| 24 | + and that the information returned by |
| 25 | + [`std::fmt::Display`](https://doc.rust-lang.org/std/fmt/trait.Display.html) |
| 26 | + is helpful. This ensures your custom error types will work well with the |
| 27 | + broader Rust ecosystem. |
| 28 | +- [x] Use the `debug_assert!` macro throughout your code to plant sanity checks |
| 29 | + within the code. Note that this imposes no performance hits for |
| 30 | + production-compiled code (`cargo build --release`), as these statements |
| 31 | + are not included in these builds. |
| 32 | +- [x] If your crate handles user input, integrate a fuzzing suite within your |
| 33 | + tests (e.g., with [`cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz)). |
| 34 | + |
| 35 | +### Performant |
9 | 36 |
|
10 | 37 | - [x] Provide benchmarks that utilize a benchmarking framework (e.g., |
11 | 38 | [Criterion](https://github.com/bheisler/criterion.rs) or |
12 | 39 | [Divian](https://github.com/nvzqz/divan)) that continuous measure |
13 | 40 | performance in the CI and track regressions. |
| 41 | +- [x] For each data type you expect to be heavily used by users, measure the |
| 42 | + amount of memory the type takes up and either via (a) anonymous constants or |
| 43 | + (b) unit tests, ensure that the memory required for that data type remains |
| 44 | + constant. |
| 45 | + |
| 46 | +### Contributable |
| 47 | + |
| 48 | +- [x] Ensure your crate is **comprehensively tested** to ensure that code can be |
| 49 | + modified and refactored by non-experts with confidence. |
| 50 | +- [x] Ensure your crate is **comprehensively linted** to ensure that code is of the |
| 51 | + highest quality possible. |
| 52 | +- [x] Ensure your crate is **comprehensively documented** to ensure that using |
| 53 | + the code is clear and straightforward. This means (a) ensuring |
| 54 | + documentation for all public-facing code, (b) ensuring documentation for |
| 55 | + all private code [to ease development in those areas], and (c) including |
| 56 | + examples for any user-facing code to make sure usage is straightforward. |
| 57 | + Note that this can be accomplished largely by enabling the |
| 58 | + [`missing_docs`](https://doc.rust-lang.org/stable/nightly-rustc/rustc_lint/builtin/static.MISSING_DOCS.html), |
| 59 | + [`clippy::missing_docs_in_private_items`](https://rust-lang.github.io/rust-clippy/master/index.html#/missing_docs_in_private_items), |
| 60 | + and |
| 61 | + [`rustdoc::missing_doc_code_examples`](https://doc.rust-lang.org/stable/nightly-rustc/rustdoc/lint/static.MISSING_DOC_CODE_EXAMPLES.html) |
| 62 | + lints. |
| 63 | + |
| 64 | +### Stable |
| 65 | + |
| 66 | +- [x] Ensure your crate follows [semantic versioning](https://semver.org/) and |
| 67 | + that you don't introduce breaking changes to your API without incrementing the |
| 68 | + major version number. |
| 69 | + |
| 70 | +### Broadly Usable |
| 71 | + |
| 72 | +- [x] Ensure that your code is available under [one of the licenses outlined in |
| 73 | + the values section](/docs/get-started/values#broadly-usable). |
0 commit comments