Release documentation

Purpose

This directory is the canonical release documentation root. Each release entry connects the user-facing CHANGELOG.md, the SemVer policy, upgrade guidance in docs/upgrade.md, and the deeper upgrade runbook to the evidence maintainers need before cutting, tagging, publishing, or rolling back a release.

Use this directory for release-checklist records, artifact/tag evidence, production-readiness notes, changelog alignment, and manual runtime boundaries. It does not replace the changelog; the changelog remains the concise public record, while release entries preserve operator evidence and decision context.

Entry naming

Create one Markdown file per release window or version:

YYYY-MM.md for a dated release train or initial planning template, for example 2026-01.md.
vMAJOR.MINOR.PATCH.md when the release is cut around a specific SemVer version and the tag already exists or is being prepared.

Prefer immutable version names once a release is tagged. If a dated planning entry becomes a tagged release, either rename it in the same change that updates references or keep the dated entry as the planning record and link the final versioned entry from it.

Required sections

Every release entry must include:

Release summary and SemVer decision.
Changelog alignment with Keep a Changelog categories: Added, Changed, Deprecated, Removed, Fixed, and Security.
Pre-release checklist for readiness, unresolved risks, migrations, redaction review, and documentation links.
Release-cut checklist for version, artifact/tag, changelog, and release notes evidence.
Post-release checklist for monitoring, support handoff, rollback readiness, and follow-up work.
Verification evidence limited to supported non-E2E automated commands.
Artifact/tag evidence with immutable references when available.
Rollback notes that state whether rollback is redeploy-only, migration-sensitive, backup-dependent, or unsupported.
Manual checks for browser, Playwright, Cypress, provider-console, production deploy, live registry, live Docker, Coolify, or other runtime-only verification.

Changelog and SemVer alignment

Release entries must agree with CHANGELOG.md and docs/versioning.md. Breaking changes require a major version decision, migration steps, rollback notes, and explicit verification evidence. Backward-compatible additions normally use a minor version, while backward-compatible fixes and documentation corrections normally use a patch version.

Do not leave unresolved marker text in release entries. Empty Keep a Changelog categories should say that no changes were introduced for that category.

Supported automated verification examples

Only use commands that are present in package.json or explicit focused Vitest targets that are supported by the repository:

pnpm run typecheck
pnpm run lint
pnpm run verify:release-docs-baseline
pnpm run verify:docs-links
pnpm exec vitest run scripts/verify-release-docs-baseline.test.mjs

Do not claim registry pushes, production deploys, provider-console checks, browser sessions, Playwright, Cypress, or E2E runs as automatic checks in release entries. Record those as manual checks with owner, date, environment, and redacted outcome when they are required.

Artifact and tag evidence

Artifact/tag evidence should name immutable references such as release tag, commit SHA, image digest, package version, build job URL or ID, and signed artifact status when available. Evidence must be redacted: do not include secrets, bearer tokens, cookies, customer data, provider payloads, private registry credentials, production connection strings, or screenshots containing sensitive information.

Manual runtime boundary

Automatic release documentation verification stays inside non-E2E checks: file/content assertions, docs-link checks, typecheck, lint, and focused Vitest. Production deploys, live Docker or registry operations, Coolify checks, browser journeys, Playwright, Cypress, provider consoles, and live customer-impacting verification require a human-approved manual runtime record.