From 9a36c04cf6efd21c859bd12dec42a80d58380833 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 25 Oct 2023 10:44:16 -0500 Subject: [PATCH] docs(contrib): Describe how to add a new package @Muscraft is considering adding a crate and we felt it was best to not just answer the question of how to do so but to document it! --- src/doc/contrib/src/SUMMARY.md | 1 + .../contrib/src/implementation/packages.md | 52 +++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 src/doc/contrib/src/implementation/packages.md diff --git a/src/doc/contrib/src/SUMMARY.md b/src/doc/contrib/src/SUMMARY.md index 268d8b6401f..e97028eb511 100644 --- a/src/doc/contrib/src/SUMMARY.md +++ b/src/doc/contrib/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Design Principles](./design.md) - [Implementing a Change](./implementation/index.md) - [Architecture](./implementation/architecture.md) + - [New packages](./implementation/packages.md) - [New subcommands](./implementation/subcommands.md) - [Console Output](./implementation/console.md) - [Filesystem](./implementation/filesystem.md) diff --git a/src/doc/contrib/src/implementation/packages.md b/src/doc/contrib/src/implementation/packages.md new file mode 100644 index 00000000000..e7d965ecaca --- /dev/null +++ b/src/doc/contrib/src/implementation/packages.md @@ -0,0 +1,52 @@ +# New Packages + +This chapter sketches out how to add a new package to the cargo workspace. + +## Steps + +Choose the relevant parent directory +- `credential/` for credential-process related packages +- `benches/` for benchmarking of cargo itself +- `crates/` for everything else + +Run `cargo new ` +- ``: + - We tend to use `-` over `_` + - For internal APIs, to avoid collisions with third-party subcommands, we can use the `cargo-util-` prefix + - For xtasks, we use the `xtask-` prefix +- `package.rust-version` + - Internal packages tend to have a policy of "latest" with a [`# MSRV:1` comment](#msrv-policy) + - Ecosystem packages tend to have a policy of "N-2" with a [`# MSRV:3` comment](#msrv-policy) + - If the right choice is inherited from the workspace, feel free to keep it that way +- If running without [cargo new automatically adding to workspace](https://github.com/rust-lang/cargo/pull/12779), add it as a workspace member if not already captured by a glob + +If its an xtask, +- Add it to `.cargo/config.toml`s `[alias]` table +- Mark `package.publish = false` + +If needed to be published with `cargo`, +add the package to `publish.py` in the repo root, +in dependency order. + +Note: by adding the package to the workspace, you automatically get +- CI running `cargo test` +- CI verifying MSRV +- CI checking for `cargo doc` warnings + +## MSRV Policy + +Our MSRV policies are +- Internal packages: support latest version +- Ecosystem packages: support latest 3 versions + +We proactively update the MSRV +- So contributors don't shy away from using newer features, either assuming they + can't ask or feeling like they have to have a justification when asking +- To avoid a de facto MSRV developing from staying on a version for a long + period of time, leaving users unhappy when their expectations aren't met + +To proactively update the MSRV, we use [RenovateBot](https://docs.renovatebot.com/) +with the configuration file in `.github/renovatebot.json5`. +To know what MSRV policy to use, +it looks for comments of the form `# MSRV:N`, +where `N` is the number of supported rust versions.