Problem / why
The current docs describe per-component versioning as a reserved, behavior-free shape. Once the
component model ships, the docs must describe the real components: model under
schema_version 1: per-component version, tag, and promotion behavior, and the framing that a
manifest with no components: block is one implicit default component whose output is
byte-identical to the pre-component baseline.
Scope (firm intent)
- Update the reference and explanation docs to cover the
components: block, per-component
version lines and tag prefixes, per-component triggering, per-component promotion, hotfix,
rollback, and release, and environment subsets. The docs-IA mapping work item decides the
exact page placement first; the working targets are reference/manifest.md (the components:
schema), reference/versioning.md (per-component version lines and tag prefixes),
reference/generated-workflows.md (per-component files), a component-focused how-to guide
under guides/, and the start/how-it-works.md and internals/architecture.md explanation
of the component-major model as the native schema.
- Frame single-component as the implicit default: no
components: block means one default
component, and its output is byte-identical.
- Remove the reserved-shape language now that the shape carries behavior.
- State plainly that cross-component dependencies are out of scope and the
external / notify
mechanism is the coordination path.
Files / areas touched
docs/src/content/docs/ (reference, guides, start, and internals pages per the docs-IA
mapping). Note the per-component versioning content now lives at
docs/src/content/docs/reference/versioning.md.
Tests and coverage required
- Docs build and link check pass.
Acceptance criteria
- Docs describe the shipped component model with no remaining reserved-shape language.
- Docs frame single-component (no
components: block) as the implicit default with
byte-identical output.
Dependencies
Blocked by the docs-IA mapping work item and by the independent hotfix, rollback, and release
milestone (so docs reflect the complete lifecycle).
Problem / why
The current docs describe per-component versioning as a reserved, behavior-free shape. Once the
component model ships, the docs must describe the real
components:model underschema_version 1: per-component version, tag, and promotion behavior, and the framing that amanifest with no
components:block is one implicit default component whose output isbyte-identical to the pre-component baseline.
Scope (firm intent)
components:block, per-componentversion lines and tag prefixes, per-component triggering, per-component promotion, hotfix,
rollback, and release, and environment subsets. The docs-IA mapping work item decides the
exact page placement first; the working targets are
reference/manifest.md(thecomponents:schema),
reference/versioning.md(per-component version lines and tag prefixes),reference/generated-workflows.md(per-component files), a component-focused how-to guideunder
guides/, and thestart/how-it-works.mdandinternals/architecture.mdexplanationof the component-major model as the native schema.
components:block means one defaultcomponent, and its output is byte-identical.
external/notifymechanism is the coordination path.
Files / areas touched
docs/src/content/docs/(reference, guides, start, and internals pages per the docs-IAmapping). Note the per-component versioning content now lives at
docs/src/content/docs/reference/versioning.md.Tests and coverage required
Acceptance criteria
components:block) as the implicit default withbyte-identical output.
Dependencies
Blocked by the docs-IA mapping work item and by the independent hotfix, rollback, and release
milestone (so docs reflect the complete lifecycle).