Skip to content

document the component model #298

Description

@joshua-temple

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsImprovements or additions to documentationmonorepo

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions