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