Release Operations

Operational procedures for releasing and rolling back core theme versions. This page covers the full release lifecycle: version strategy, pre-release gates, version determination, tagging, post-release verification, and downstream deployment — plus a rollback playbook for when a release causes failures.

Version Lifecycle

The core theme follows Semantic Versioning 2.0.0 with a staged progression designed to support early feedback and stable production use:

• 0.x.x (pre-release) — development versions; breaking changes are acceptable. Ideal for early testing and feedback. Current phase.
• 1.0.0-rc.x (release candidate) — API is locked, final polish. Signal that 1.0.0 is imminent; last chance for feedback before the stable contract.
• 1.0.0+ (general availability) — stable and production-ready. Backwards compatibility guaranteed; major version bumps only for breaking changes.

For details on this progression and version determination rules, see the Versioning Standard in .docs/standards/VERSIONING.md.

Current version: 0.1.0 (see package.json)

Who This Is For

• Core theme maintainers cutting a release
• Site teams consuming a new release via sync:core
• Anyone investigating or executing a rollback after a bad release

Release Checklist

Follow every step in order. Do not tag until all pre-release gates pass.

Pre-Release Gates

All conditions must be true before proceeding to version determination:

• npm run validate passes with zero errors and no open waivers. See the Validation Pipeline (DOC-00007) for step definitions and the Validation Troubleshooting guide (DOC-00036) if any step fails.
• Manual Lighthouse audit on four representative routes (/, /services/, /articles/[article]/, /contact/) meets these mobile targets: Performance ≥90, Accessibility ≥95, Best Practices ≥90, SEO ≥95.
• Manual accessibility audit is clean — no open failures for any interactive pattern (header, search, forms, theme switcher, accordion, tabs, scroll-to-top, consent banner, drawer, skip link).
• Requirements catalog (src/core/config/requirements.catalog.ts) status fields are accurate for all shipped features.
• CHANGELOG.md is current — every shipped change since the last release has a dated entry.
• .docs/decisions.md includes all implementation decisions made since the last release.

Version Determination

Classify the release as major, minor, or patch using Semantic Versioning 2.0.0 (external link) and the Versioning Standard in .docs/standards/VERSIONING.md:

1. Review all commits since the last release tag:

   git log --oneline <last-tag>..HEAD

2. Check for breaking changes:

   git log --grep="BREAKING CHANGE" <last-tag>..HEAD

3. Determine the version bump:

   Current phase (0.x):

   • New features (feat commits), no breaking changes → bump minor: 0.1.0 → 0.2.0
   • Breaking changes (feat! commits) → bump minor: 0.1.0 → 0.2.0 (breaking changes do not bump major in 0.x)
   • Bug fixes only (fix commits) → bump patch: 0.1.0 → 0.1.1

   After transition to 1.0.0+:

   • New features, no breaking changes → bump minor
   • Breaking changes → bump major
   • Bug fixes only → bump patch

Breaking-Change Protocol (Major Releases Only)

Skip this section for minor and patch releases.

• Every breaking change has a BREAKING CHANGE: footer in its commit message.
• CHANGELOG.md contains migration notes for each breaking change describing: what changed, what breaks, and how downstream sites should adapt (REQ-00195).
• If src/content.config.ts schemas changed (pages, articles, fragments): document the schema changes and migration steps in CHANGELOG.md. This file is SITE-OWNED and not synced — downstream sites must apply schema changes manually.

Version Tagging

Run the release automation script:

npm run release

The script automatically:

1. Displays all commits since the last tag for review.
2. Proposes the correct version bump based on commit types and the current versioning phase (0.x, prerelease, or GA).
3. Generates a grouped CHANGELOG draft.
4. Asks for approval before modifying any files (Gate 1).
5. Bumps package.json, updates CHANGELOG.md and the version string in README.md, then pauses for optional manual editing (Gate 2).
6. Commits package.json, package-lock.json, CHANGELOG.md, and README.md, and creates an annotated tag vX.Y.Z.

To preview without making changes:

npm run release -- --dry-run

To set an explicit version instead of using the auto-computed bump:

npm run release -- --version 0.9.0

When --version is provided the script skips auto-detection and uses the given semver string directly. Commits are still gathered for the CHANGELOG draft. Combine with --dry-run to preview:

npm run release -- --version 0.9.0 --dry-run

After the script completes, push the commit and tag manually:

git push origin main --tags

Post-Release Verification

• Run the downstream sync test against the tagged release:

  node scripts/test-sync.mjs

• Verify the docs site builds cleanly:

  npm run build

• Verify .downstream-exclude is current — any new development artifacts added since the last release should be listed in the manifest.

Downstream Deployment Overview

High-level steps a site team follows after a new core release is tagged. For the authoritative downstream setup, deployment, and redeployment runbook, see the Deployment Guide (DOC-00021).

1. Sync core files to the latest stable release:

   npm run sync:core

   The script auto-detects the latest stable version tag and syncs only if newer than the last sync. To target a specific version, use npm run sync:core -- --ref vX.Y.Z. Files matching .downstream-exclude patterns are automatically filtered from the sync output.

2. Review the diff — check what changed in synced files.

3. Run npm run validate — fix any issues before committing.

4. Test locally — start the dev server and verify key pages.

5. Commit the sync update and redeploy using the procedure in DOC-00021.

Rollback Playbook

Procedure for reverting a core theme release when it causes downstream failures. Follow the steps in order.

Trigger Criteria

Initiate a rollback when any of the following occur after a downstream site syncs to a new release:

• Validation failure — npm run validate fails on the downstream site after running sync:core, and the failure is caused by the synced core changes (not pre-existing site issues).
• Critical regression — a shipped feature that previously worked is broken in the new release (pages don’t render, navigation is broken, forms don’t submit, search doesn’t work).
• Ownership boundary violation — sync:core modified files it should not have (site-owned files overwritten, site content deleted, astro.config.mjs changed). See the File Ownership Model (DOC-00006) for ownership boundaries.

Do not roll back for:

• Cosmetic issues that don’t block functionality.
• Pre-existing site issues unrelated to the sync.
• Expected breaking changes that were documented in the changelog with migration guidance.

Rollback Procedure

Upstream (Core Theme Maintainer)

1. Identify the last known-good tag:

   git tag --sort=-creatordate | head -5

2. If the issue is in the release tag itself (not downstream-specific), revert the problematic commits on main:

   git revert <commit-sha>

3. Do not delete the bad tag — it serves as a historical record. Tag a new patch release after the revert:

   git tag -a vX.Y.Z -m "Release vX.Y.Z — reverts <issue>"
   git push origin main --tags

Downstream (Site Team)

1. Re-sync to the last known-good tag:

   npm run sync:core -- --ref <last-good-tag>

2. Run validate to confirm the rollback restored a clean state:

   npm run validate

3. Commit the rollback:

   git add -A
   git commit -m "fix: rollback sync:core to <last-good-tag>"

4. Deploy the rolled-back version.

Post-Rollback Process

After the immediate rollback is complete:

• Document what failed. Write a brief summary in .docs/decisions.md: what the release changed, what broke, and why the rollback was necessary.
• Create a follow-up task. Add an entry to TODO.md or the project tracker describing the fix needed before the changes can be re-attempted.
• Re-scope before retrying. Do not re-apply the same changes without modification. Identify the root cause, scope a targeted fix, and run it through the normal release process (validate, test, tag) before shipping again.