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 c7452cf
Show file tree
Hide file tree
Showing 2 changed files with 31 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
30 changes: 30 additions & 0 deletions src/doc/contrib/src/implementation/packages.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# New Packages

## Steps

Choose the relevant parent directory
- `credential/` for credential-process related packages
- `benches/` for benchmarking of cargo itself
- `crates/` for everything esle

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 to get it auto-updated
- Ecosystem packages tend to have a policy of "N-2" with a `# MSRV:3` comment to get it auto-updated
- 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 published, add the package to `publish.py`, 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

0 comments on commit c7452cf

Please sign in to comment.