Expand description
The producer’s own release declaration: what one repository publishes.
This is the other release document, and it is deliberately not the one
releases reads. A host declares what it waits on, in
$ONEVCS_HOME/releases.yml, matched across every repository it knows; a
repository declares what it publishes, in a release-targets.toml at its
own root, committed beside the workflow that publishes it. The two answer
different questions from different sides, they are written and reviewed by
different people, and neither is derivable from the other — so they stay two
formats rather than being reconciled into one.
TOML rather than a second YAML document because these files are mostly prose:
the reasoning a producer wrote about why something is a target, or is not one,
is the most valuable thing in them, and it lives as comments. Those comments
are not this crate’s to keep. Reading a declaration answers what it declares;
rendering one back with crate::render_release_declaration writes the declaration and nothing else, so a
caller that round-trips a producer’s file over the top of itself deletes the
prose. Round-tripping is for producing a document, not for editing one.
What a declaration says is fixed by the canonical schema in docs/contract.md,
which six repositories write against; this module is that schema as a type, and
crate::read_release_declaration and
crate::validate_release_declaration are the boundary it is enforced at. Refusing well is most
of the value here: a declaration is written once per repository and then read by
machinery, so every refusal names what is wrong and where in the document it
is.
Structs§
- Declaration
- What one repository publishes, as its own
release-targets.tomldeclares it. - Declared
Target - One consumable artifact: something a dependent names in order to depend on it.
- Instruction
Template - The minijinja template a consumer of one target is instructed by.
- Prose
- One line of operator-written text, checked where it is read.
- Registry
Id - A registry-qualified identifier,
<registry>:<name>, checked where it is read. - Repository
Path - A path to something the repository being released carries, checked where it is read.
- Retired
Artifact - Something this repository once published and does not publish again.
Constants§
- FILE
- The one name a repository’s release declaration is found under, at its root.
- OLDEST_
SCHEMA_ VERSION - The oldest schema version this build reads.
- SCHEMA_
VERSION - The schema version this build writes.