Versioning policy

Goal

Allow each site to adopt new features on its own schedule without breaking production.

Policy

• shared Foundry repos use semantic version tags
• sites pin module versions in go.mod
• new features should be additive by default
• release compatibility is tracked as a bundle, not just as individual repo tags

Use the detailed compatibility rules in docs/COMPATIBILITY.md when deciding whether a change is safe additive, soft upgrade, migration-required, or breaking.

Repo versioning rules

• likestyle-foundry-core
  • patch: bug fixes, docs, non-breaking structural or token fixes
  • minor: new blocks, new optional fields, new variants, new shared behaviors
  • major: contract removals or incompatible defaults
• theme repos
  • patch: bug fixes, non-breaking styling improvements
  • minor: new tokens, new component variants, additive styling support
  • major: token removals or incompatible styling contract changes
• likestyle-foundry-starter
  • patch: docs/example fixes
  • minor: new starter examples or updated compatible pins
  • major: starter contract changes that require different setup
• likestyle-foundry-docs
  • patch: clarifications and process updates
  • minor: new major operating docs or migration material
  • major: structural documentation reorganization only if necessary
• likestyle-foundry-distribution
  • patch: doc or tooling fixes to an existing release lane
  • minor: new bundle manifests, verification improvements, or new channels
  • major: manifest schema or compatibility policy changes

Release Flow

1. Implement the change in the correct repo layer.
2. Verify the change against the required starter and downstream site matrix.
3. Update docs, starter examples, and any applicable release map if the change alters locked scope or planned migration behavior.
4. Tag the changed repos.
5. Publish or update the matching distribution bundle manifest.
6. Sites adopt the newer bundle only when ready.

Bundle rule

Sites should not guess which repo tags belong together.

Use likestyle-foundry-distribution to define a compatible stack of:

• runtime modules
• theme modules
• docs/reference versions
• verification expectations

Use distribution release maps when the team needs to remember the intent of a release lane, including what was deliberately deferred and what should be revisited in the next version.

This creates a stable upgrade target for sites without freezing framework development.

Site upgrade rule

When a site upgrades:

1. choose a target bundle
2. update pinned module versions
3. run the documented verification steps
4. complete local QA and visual review
5. deploy only after the upgrade passes

Why This Matters

This prevents surprise regressions and allows staged rollout of new block features while keeping the shared framework moving forward.