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

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 process

1. land the change in the correct repo layer
2. update starter/examples if the change is user-facing
3. update docs and migration guidance
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
• 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