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 :)
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