Skip to content

Commit

Permalink
docs(contrib): Describe how to add a new package
Browse files Browse the repository at this point in the history
@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!
  • Loading branch information
epage committed Oct 25, 2023
1 parent b227fe1 commit 9a36c04
Show file tree
Hide file tree
Showing 2 changed files with 53 additions and 0 deletions.
1 change: 1 addition & 0 deletions src/doc/contrib/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
52 changes: 52 additions & 0 deletions src/doc/contrib/src/implementation/packages.md
Original file line number Diff line number Diff line change
@@ -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 <name>`
- `<name>`:
- 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.

0 comments on commit 9a36c04

Please sign in to comment.