docs(book-cc): document the process for adding new workspace crates #273
Conversation
There was a problem hiding this comment.
Subjective opinion: not sure if we really need this section, given that we don't add new crates that often
The first couple of points aren't RIOT-rs specific. Only really the points about rexporting the crate from riot-rs and adding it (and potential features flag) to the CI are. Maybe it makes sense to have them, but then I'm in favor of shortening it down.
But not a strong opinion :)
I agree it's not a weekly event, but it does happen quite regularly:
I also agree that not all of it is RIOT-rs-specific, but it helps clarify what tools and configuration we embrace, especially as these are always changing—e.g., inheritance of workspace lints was only added a few months ago and I was personally pleasantly surprised when I saw that using |
ROMemories
force-pushed
the
docs/new-workspace-crate
branch
from
54d5383
to
721435d
Compare
|
This has proven useful these past few weeks, I've updated it and I think we can get it in now. |
ROMemories
changed the title
|
|
||
| 1. Create the new crate's directory in `src/`. | ||
| 1. Run `cargo init --lib` in that directory. | ||
| 1. Add relevant lints (e.g., `#![deny(missing_docs)]` and `#![deny(clippy::pedantic)]`) to the crate; some lints are already inherited from the workspace and do not need to be added to the new crate. |
There was a problem hiding this comment.
I think this needs to be more specific. Better state e.g., "Add #![deny(missing_docs)] and #![deny(clippy::pedantic)] to the crate"
| 1. Create the new crate's directory in `src/`. | ||
| 1. Run `cargo init --lib` in that directory. | ||
| 1. Add relevant lints (e.g., `#![deny(missing_docs)]` and `#![deny(clippy::pedantic)]`) to the crate; some lints are already inherited from the workspace and do not need to be added to the new crate. | ||
| 1. Cargo has added the crate to the workspace members in the workspace's `Cargo.toml`, move the added string to its own line, preserving lexicographic order. |
There was a problem hiding this comment.
| 1. Cargo has added the crate to the workspace members in the workspace's `Cargo.toml`, move the added string to its own line, preserving lexicographic order. | |
| 1. In the workspace's `Cargo.toml` `workspace.members`, ensure the crate's entry keeps the lexicographic order. |
| 1. Cargo has added the crate to the workspace members in the workspace's `Cargo.toml`, move the added string to its own line, preserving lexicographic order. | ||
| 1. Add the crate to the list of crates checked by Clippy in `.github/workflows/main.yml`, preserving lexicographic order. | ||
| 1. Consider adding the crate to the list of crates run by cargo test in `.github/workflows/main.yml`, preserving lexicographic order. | ||
| 1. Re-export the crate from the `riot-rs` crate, inline it in the docs as done for the other crates, and feature-gate it if necessary. |
There was a problem hiding this comment.
move to third place (after "add lints", before the CI fixes start)
| 1. Run `cargo init --lib` in that directory. | ||
| 1. Add relevant lints (e.g., `#![deny(missing_docs)]` and `#![deny(clippy::pedantic)]`) to the crate; some lints are already inherited from the workspace and do not need to be added to the new crate. | ||
| 1. Cargo has added the crate to the workspace members in the workspace's `Cargo.toml`, move the added string to its own line, preserving lexicographic order. | ||
| 1. Add the crate to the list of crates checked by Clippy in `.github/workflows/main.yml`, preserving lexicographic order. |
There was a problem hiding this comment.
This and the next I found not obvious and thus skipped it. Can we have ANCHORS in those yamls? :)
Not sure the Coding Conventions is the best place to document this, maybe we should have a book section for documenting processes.