Compatibility

The goal of Foundry compatibility policy is straightforward:

• keep shipped sites stable
• keep framework development moving
• make upgrades intentional instead of accidental

Core rule

Existing sites do not follow moving branches.

They pin released module tags and adopt newer releases only when the site owner is ready. Foundry can continue adding features, variants, and fixes, but a site should not change behavior until its pinned versions change.

Repo ownership

Use the narrowest correct layer for every change.

• likestyle-foundry-core
  • shared block markup contracts
  • shared runtime behavior
  • shared structural CSS and fallback tokens
  • additive block APIs and feature flags
• likestyle-foundry-theme-shield
  • neutral visual defaults for shared contracts
  • baseline theme tokens and component styling
• site-owned brand theme repo
  • high-consideration service proof site brand treatment only
  • no shared behavior should originate here
• site repos such as high-consideration-service
  • page composition
  • content wiring
  • site-only layout wrappers when shared contracts are insufficient
• likestyle-foundry-starter
  • proof that a shared capability is reusable
  • upgrade reference for new sites
• likestyle-foundry-distribution
  • release bundles, compatibility manifests, and verification tooling
• likestyle-foundry-docs
  • policy, contracts, migration guidance, and upgrade documentation

If another site could reasonably use a behavior or contract, it does not belong in a site repo.

Change classes

Every Foundry change should be classified before implementation.

1. Safe additive

Examples:

• new block
• new optional field
• new token
• new variant
• new feature flag
• new theme styling for a new contract

Requirements:

• no existing contract removed or repurposed
• starter or demo coverage if user-facing
• docs updated

2. Soft upgrade

Examples:

• improved behavior behind a new variant
• improved behavior behind an opt-in flag
• new shared runtime that existing consumers can ignore

Requirements:

• existing sites keep current behavior unless they opt in
• migration guidance explains how to adopt
• verify at least one downstream site still builds cleanly

3. Migration-required

Examples:

• default behavior changes for an existing contract
• old field remains supported, but preferred path changes

Requirements:

• deprecation notice in docs
• explicit migration steps
• release bundle notes
• verification against starter and at least one real site

4. Breaking

Examples:

• removing a public field
• removing a stable class or token
• changing markup or runtime expectations for existing consumers

Requirements:

• planned release only
• migration guide first
• distribution manifest with clear upgrade notes
• no silent shipment as normal feature work

Most Foundry work should stay in the first two classes.

For already-live production sites, also follow the stricter rollout posture in docs/FOUNDRY-PRODUCTION-MIGRATION-CONTRACT.md. Compatibility classification alone is not enough; production-facing changes also need a documented upgrade packet, rollback path, and stable-bundle migration story.

Allowed and forbidden default behavior changes

Allowed in minor/feature work:

• adding new optional tokens
• adding new optional fields
• adding new variants
• adding new runtime data attributes or classes
• introducing a new shared capability with site adoption left optional

Not allowed without migration planning:

• changing the meaning of an existing field
• changing default rendering semantics for a widely used block
• removing tokens or classes that sites may already target
• moving behavior from a theme into a site repo or vice versa without contract documentation

Deprecation policy

Foundry should migrate by addition first, replacement second, removal last.

Required sequence:

1. Add the new path.
2. Keep the old path working.
3. Mark the old path deprecated in docs.
4. Publish migration guidance.
5. Remove only in a planned breaking release.

Required verification matrix

For any shared Foundry change, the minimum verification matrix is:

1. Build the changed shared repo if it has its own build or validation command.
2. Build likestyle-foundry-starter.
3. Build at least one real downstream site that consumes the changed contract.
4. Update the starter or demo when the shared feature is user-facing.
5. Update docs before tagging the release bundle complete.

For visual navigation or scroll behavior, keep a starter or demo example page permanently so future changes can be checked against the same scenario.

Release bundles

Foundry compatibility is not just a repo tag problem. It is a stack problem.

Use likestyle-foundry-distribution manifests to define compatible bundles of:

• core
• theme-shield
• brand themes where applicable
• starter reference version
• docs version
• optional control-plane compatibility contracts

Sites should upgrade to a known compatible bundle, not guess which tags across repos happen to work together.

Different sites may intentionally stay on different published bundles.

That is a feature, not drift, as long as each site is pinned to a real published bundle and its own lockfile is reproducible.

Support tracks

Recommended channel model:

• dev
  • for explicit canary sites and active framework validation only
  • may follow live sibling-repo development mode or a pre-release bundle
  • not the default for ordinary production sites
• stable
  • default for most new sites
  • latest fully validated compatible bundle
• lts
  • optional longer-support track for sites that need slower upgrades
  • bug fixes, security updates, and selective backports only
• preview
  • optional pre-release validation track
  • not a default production target

If this longer-support track is added, use lts terminology rather than lte so the intent is unambiguous.

Canary and production cohorts

Not every site should run the same track.

Recommended cohort model:

• canary sites
  • intentionally validate upcoming Foundry work
  • may run dev or preview
  • should be few in number and deliberately chosen
  • should represent important consumer shapes such as:
    • starter
    • one standard brand/theme site
    • one more customized or migration-heavy site
• normal production sites
  • should run published stable or lts bundles
  • should not follow moving framework work by default

This gives Foundry forward pressure without making every shipped site part of the experiment.

Version identity

Use versioning at three different levels:

1. module version
   • each shared repo keeps its own tag series
   • example: likestyle-foundry-core v0.1.16
2. distribution bundle version
   • the compatible stack version published by likestyle-foundry-distribution
   • example: distribution_version: v0.3.1
3. site lock version selection
   • the site pins the exact bundle/channel and module tags it is using in foundry.lock.yaml and go.mod

Compatibility decisions should be made at the bundle level, not by comparing individual repo tags in isolation.

Build metadata

Build metadata is useful, but it should not be the main compatibility version.

Recommended rule:

• compatibility = bundle version + locked module tags
• traceability = build metadata

Build metadata can include:

• site git commit
• distribution manifest path
• distribution version
• build date/time
• environment name such as preview or production

That metadata is good for diagnostics, preview footers, and support work, but it should not change upgrade meaning by itself.

In other words:

• new build of the same locked bundle = same compatibility level
• new bundle version = new compatibility decision
• new module tag in the lockfile = new compatibility decision

If you want SemVer-style notation, treat build identity as metadata, not as a new support tier. For example:

• bundle release: v0.3.1
• traceable build: v0.3.1+site.high-consideration-service.sha.abc1234

Locked runtime versus live framework development

Normal site work should use a locked-materialized runtime:

• commit foundry.lock.yaml
• pin module tags in go.mod
• materialize those locked repos into ./.foundry/modules/
• resolve Hugo modules through go.mod replace directives that point at ./.foundry/modules/...

This keeps site development and builds reproducible.

The materialized repos under ./.foundry/modules/ are runtime copies, not the source of truth. They should be generated from the lockfile and usually ignored by git rather than committed.

Live sibling-repo development is still useful, but it should be an explicit framework-development mode, not the default mode for ordinary site work.

That means Foundry tooling should recognize two valid bootstrap modes:

1. locked-materialized site mode
2. live sibling-repo framework mode

Upgrade path for sites

Recommended site workflow:

1. Pin released module tags in go.mod.
2. Track the current bundle manifest that the site is using.
3. Upgrade to a newer bundle only when ready.
4. Run the site’s local QA and visual review.
5. Deploy only after verification completes.

This keeps production stable while Foundry continues to evolve.