Dependency notes for Rust
A line in Cargo.toml records a crate, a version requirement and a feature list. Why the crate is there, why a feature is off, or which targets an upgrade has to be tested on does not fit on that line — and in a workspace, the same crate turns up in many members.
Depos keeps a note for each dependency in .depos/cargo/DEPENDENCY-NOTES.md, beside Cargo.toml, and shows it on the dependency's line. A workspace member without a notes file of its own uses the nearest one above it, so one file at the workspace root can cover every member.
Cargo.toml in VS Code.What Depos reads
- Manifest:
Cargo.toml - Notes file:
.depos/cargo/DEPENDENCY-NOTES.md - Section heading: the dependency key, usually the crate name:
## serde
Depos reads [dependencies], [dev-dependencies], [build-dependencies] and their [target.…] forms. A member's serde.workspace = true counts; [workspace.dependencies] itself does not.
Depos never runs Cargo and does not read Cargo.lock.
Example
[dependencies]
http = "0.2"
http1 = { package = "http", version = "1" }
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.42", features = ["rt-multi-thread", "macros"] }
.depos/cargo/DEPENDENCY-NOTES.md, two of its sections:
## http1
The http 1.x types, renamed so they can sit next to http 0.2 during the hyper upgrade.
### Agent notes
- purpose: request and response types for the new hyper 1 server
- remove-when: nothing uses http 0.2 any more; then rename this back to http
## tokio
Runtime for the API server and the job workers. Keep the feature list short.
### Agent notes
- purpose: async runtime for the API server and the background job workers
- constraint: no `full` feature — enable only what the code uses
- verify: `cargo test --workspace`
- verified: 1.42.0
A renamed dependency is keyed by the name the manifest gives it: ## http1 above, not ## http.
Comments in Cargo.toml
[dependencies]
# tokio: enable only the features the server uses
tokio = { version = "1.42", features = ["rt-multi-thread", "macros"] }
serde = { version = "1.0", features = ["derive"] } # derive only
Cargo.toml is TOML: # starts a comment that runs to the end of the line, unless it is inside a string.
cargo add keeps the comments when it adds a dependency or changes one; before Cargo 1.79, it dropped them from a dependency written as a plain version string when it changed that dependency. cargo remove takes the dependency's comments with it: the one at the end of its line, and every comment line between it and the entry or table header above. If the dependency was the first in its table, that includes a comment under [dependencies] meant for the whole table.
Pinning a version
A bare version in Cargo.toml is a caret requirement: serde = "1.0.200" accepts any later 1.x release. Below 1.0 the range ends at the next minor version, so "0.2.3" means >=0.2.3, <0.3.0. "~1.0.200" accepts patch releases only, and "=1.0.200" that one version; cargo add serde@=1.0.200 writes the exact form.
Cargo.lock records the version each build uses. cargo update serde --precise 1.0.202 sets the locked version of one crate without touching Cargo.toml; other crates in the lock file can move with it. Neither file says why a crate is held where it is: write that in its note as constraint:, which agents read before they change the requirement or run cargo update.
For AI coding agents
An agent reads a crate's section before it adds, upgrades or removes the crate, and records what it did under ### Agent notes. remove-when: tells it when a dependency has served its purpose. See the rules agents follow.