Distribution manifest format

Distribution manifests define a compatible Foundry release bundle.

Goals

• make compatible repo tags explicit
• define the verification matrix in one place
• give sites a stable upgrade target

Schema

Historical manifests use schema_version: 1. New releases may use schema_version: 2, which adds owner-facing release identity, support promises, and explicit upgrade paths. Historical manifests remain immutable.

Top-level sections:

• bundle
  • release metadata for the bundle itself
• components
  • shared repos and reference repos that belong to the bundle
• verification
  • local repos and commands that must pass before the bundle is considered verified
• notes
  • human-readable release notes

Schema v2 release contract

Schema v2 makes the bundle—not an individual module tag—the owner-facing Foundry release. Its bundle adds:

• version: the bundle SemVer shown to owners, such as v1.2.0
• support_tier: standard or lts
• support_ends_at: the final supported date in YYYY-MM-DD form

lts is a support promise within the stable channel. It is not a separate replacement for stable. LTS requires a bundle at v1.0.0 or newer and at least 365 days of declared support.

Schema v2 also requires upgrade_paths for stable releases. Upgrade impact is relational because the work required depends on both the installed and target bundles. Each path declares:

• from: one or more exact bundle versions
• impact: verify-only, optional-adoption, migration-required, or breaking
• site_changes_required: an explicit boolean
• owner_summary: plain-language owner guidance
• migration_document: required for migration-required and breaking paths

Use examples/release-contract-v2.yaml as the forward contract. Validate all manifests with python3 scripts/validate_release_contract.py.

Component fields

Each entry in components supports:

• id
• role
• repo
• local
• version

role is descriptive and does not change verification behavior.

Verification repository fields

Each entry in verification.repositories supports:

• name
• path
• expected_tag
• require_clean
• require_head_tag

These let release verification distinguish between:

• a repo merely containing the required tag
• a repo currently checked out exactly at the required tag

The path value should normally match a components[].local entry so automation can materialize the bundle into a clean workspace before verifying it.

Verification check fields

Each entry in verification.checks supports:

• name
• cwd
• install_command
• command

Checks run relative to the workspace root supplied to the verification script. install_command is optional and is intended for dependency installation in a clean cloned workspace before the main verification command runs.

Example

See manifests/stable/v0.2.4.yaml for the current stable bundle example.