Distribution release policy

Foundry releases should let the shared framework move forward without forcing unexpected changes onto shipped sites.

Core rules

• all shared repos use semantic version tags
• downstream sites consume tagged releases only
• compatibility is tracked as a bundle, not just as individual repo tags
• no uncontrolled site should follow main
• sites may stay pinned to older compatible bundles until they intentionally opt into a newer release
• every module version referenced by a site lock must exist as a remote tag in the module repo

Change classes

Safe additive

• new block
• new optional field
• new token
• new variant
• new feature flag

These changes should ship as minor or patch releases, depending on scope.

Soft upgrade

• improved behavior behind opt-in configuration
• new shared capability that existing consumers can ignore

These changes may ship in a minor release if existing defaults stay intact.

Migration-required

• preferred path changes while old behavior still works
• existing consumers need explicit adoption steps

These changes require migration notes and bundle verification before release.

Breaking

• removing a public field or class contract
• changing default semantics for an established contract
• removing tokens that consumers may already target

These changes require a planned major release and explicit migration guidance.

Release bundle rule

Every shared release should map to a distribution manifest that records:

• compatible repo tags
• starter and docs reference versions
• verification commands
• downstream consumer checks

Release identity and support

Use the Distribution bundle version as the owner-facing Foundry version. Component tags remain technical provenance and must not be interpreted as the overall support state of a site.

Support has two independent dimensions:

• channel: preview or stable
• tier: standard or lts

LTS is a stable bundle with a longer, explicit maintenance promise. Do not call a release LTS unless all of these are true:

• the bundle is v1.0.0 or newer
• support_ends_at provides at least 365 days of support
• a maintained backport branch and verification lane exist
• the team will backport security, data-loss, build-blocking, and severe compatibility fixes

Standard stable releases remain supported through their declared support_ends_at date. End-of-life releases remain reconstructable and documented, but receive no fixes.

Owner-facing upgrade impact

Version numbers do not determine site work by themselves. Every schema-v2 stable bundle must classify each supported source-to-target path:

• verify-only: no site edits; rebuild and verify
• optional-adoption: existing behavior remains valid; site changes are optional
• migration-required: explicit site edits and a migration document are required
• breaking: a coordinated major migration is required

Core reports these facts without changing the site. Control may persist review, scheduling, approval, and rollout state. Owner-facing surfaces should derive current, update available, action required, or unsupported from the site lock plus this contract; they must not guess from module SemVer.

Release map rule

When a release lane or major migration has important planning choices that must survive beyond chat, store them in a release map under docs/release-maps/.

Use a release map to record:

• locked decisions for the current version
• scope included now versus deferred later
• downstream adoption requirements
• next-version questions that should be revisited deliberately

Do not use changelogs for this purpose. Changelogs describe what shipped. Release maps describe what was decided.

Release process

1. land the change in the correct repo layer
2. update starter/examples if the change is user-facing
3. update docs, migration guidance, and any applicable release map
4. verify the bundle matrix
5. tag changed repos
6. publish or update the matching distribution manifest

Site safety requirements

• keep sites pinned in go.mod
• for locked-materialized sites, point go.mod replace rules at ./.foundry/modules/...
• prefer release bundles over ad hoc version selection
• use vendored or pinned releases for sites you do not directly control
• avoid changing default behavior without an explicit upgrade path
• keep local newest-upstream testing explicit and separate from the release baseline
• do not treat sibling workspace repos as the committed runtime baseline for a locked site

Release map update triggers

Update a release map when:

• a planning decision is locked
• scope is added or removed
• a repo is added to the release bundle
• a deferral is promoted into scope
• a release candidate is declared
• a version retrospective captures what moves to the next version

Confidence gate

Release confidence and upgrade claims should be evaluated against FOUNDRY-CONFIDENCE-GATE.md.