docs(contrib): Start guidelines for schema design #15037
Conversation
rustbot
added
A-documenting-cargo-itself
| @@ -0,0 +1,29 @@ | |||
| # Data Schemas | |||
There was a problem hiding this comment.
Should we have an overview of what this "data schemas" refer to?
There was a problem hiding this comment.
I've added some context
epage
force-pushed
the
schema-design
branch
2 times, most recently
from
4f50d9b to
e323d10
Compare
| - For output, prefer [jsonlines](https://jsonlines.org/) as it allows streaming output and flexibility to mix content (e.g. adding diagnostics to output that didn't prevously have it | ||
| - `deny_unknown_fields` should not be used to allow evolution of formats, including feature gating | ||
|
|
||
| ## Schema Evolution Strategies |
There was a problem hiding this comment.
When reading this, each bullet point is a bit disconnected to me.
I can't tell what it means exactly by evolution strategies. Maybe it is a pretty common term but I didn't know?
Also like "When reading data, add new fields", I had a hard time interpreting it as part of evolution strategies. For "Versioned with the edition" I am able to guess it means "When a schema needs to change some existing field, versioning it with edition", though the whole paragraph still looks pretty sparse and needs some guesses for me to read.
There was a problem hiding this comment.
Tried to expand on it a bit more. Hope it helps!
There was a problem hiding this comment.
Thanks. That is good enough for me as a maintainer. Not sure about casual contributors, but we can always iterate later :)
This was inspired by a recent Cargo team discussion on whether we should generally elide default values. This will also help with https://rust-lang.github.io/rust-project-goals/2025h1/cargo-plumbing.html Case studies in schema design: - rust-lang#14506 - rust-lang#10543
| - For output, prefer [jsonlines](https://jsonlines.org/) as it allows streaming output and flexibility to mix content (e.g. adding diagnostics to output that didn't prevously have it | ||
| - `deny_unknown_fields` should not be used to allow evolution of formats, including feature gating | ||
|
|
||
| ## Schema Evolution Strategies |
There was a problem hiding this comment.
Thanks. That is good enough for me as a maintainer. Not sure about casual contributors, but we can always iterate later :)
Update cargo 18 commits in fd784878cfa843e3e29a6654ecf564c62fae6735..088d496082726091024f1689c124a0c3dccbd775 2025-01-03 20:06:26 +0000 to 2025-01-10 20:10:21 +0000 - docs(reference): Fix PkgIdSpec kind docs (rust-lang/cargo#15049) - feat: Added warning when failing to update index cache (rust-lang/cargo#15014) - docs(ref): Fix the inverted logic about MSRV (rust-lang/cargo#15044) - chore(deps): update msrv (1 version) to v1.84 (rust-lang/cargo#15041) - Remove unnecessary into conversions (rust-lang/cargo#15042) - docs(contrib): Start guidelines for schema design (rust-lang/cargo#15037) - fix: emit warnings as warnings when learning rust target info (rust-lang/cargo#15036) - fix(schemas): Fix the `[lints]` JSON Schema (rust-lang/cargo#15035) - fix(schemas): Fix 'metadata' JSON Schema (rust-lang/cargo#15033) - shorten comment on Ord for SourceKind (rust-lang/cargo#15029) - Make `"C"` explicit in `extern "C"`. (rust-lang/cargo#15034) - simplify SourceID Ord/Eq (rust-lang/cargo#14980) - Setup cargo environment for `cargo rustc --print` (rust-lang/cargo#15026) - Avoid naming variables `str` (rust-lang/cargo#15025) - Bump to 0.87.0; update changelog (rust-lang/cargo#15022) - Update libgit2 to 1.9 (rust-lang/cargo#15018) - Remove condition on RUSTUP_WINDOWS_PATH_ADD_BIN (rust-lang/cargo#15017) - Fix https::self_signed_should_fail for macos (rust-lang/cargo#15016)
What does this PR try to resolve?
This was inspired by a recent Cargo team discussion on whether we should generally elide default values.
This will also help with https://rust-lang.github.io/rust-project-goals/2025h1/cargo-plumbing.html
Case studies in schema design:
cargo metadatano longer distinguishes between "magical" features from optional deps and normal features #10543How should we test and review this PR?
Additional information