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.

The normalized release catalog is exported as foundry.release-catalog.v2. It carries the complete component list for each release, a SHA-256 digest of each raw manifest, and a canonical SHA-256 digest of the catalog with the catalog_sha256 field omitted. Consumers must verify the catalog digest before using it to authorize an unattended upgrade lane.

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
• hugo_version

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.

hugo_version is optional and routes both setup and check commands through an exact Hugo binary. The verifier first checks <cwd>/.toolchain/hugo/bin/hugo, then a versioned environment variable such as FOUNDRY_HUGO_0_160_1_BIN, and finally the active PATH. It fails closed when none of those binaries reports the declared version. This allows one bundle to verify consumers with different released Hugo toolchains without changing their source or weakening their repository checks.

Example

See manifests/stable/v1.0.1.yaml for the current stable/LTS bundle example.