HiveGrid-Wireframes/hivegrid-cloud/docs/release-checklist.md

Release Checklist

Purpose

Use this checklist when preparing, cutting, tagging, publishing, or handing off a boilerplate release. It turns the release documentation root in docs/releases/README.md, the public CHANGELOG.md, and the SemVer policy into an operator-facing record that can be reviewed without exposing runtime secrets.

This checklist is documentation and release-evidence guidance only. It does not approve browser automation, Playwright, Cypress, live Docker builds, registry pushes, Coolify execution, provider-console inspection, or production traffic checks as automatic verification.

Source evidence

Before the release cut, review and link the relevant sources:

• CHANGELOG.md for the user-facing release entry and Keep a Changelog categories.
• docs/releases/README.md for release-entry naming, required sections, artifact evidence, and manual runtime boundaries.
• docs/staging-live-uat.md for staging, live runtime smoke, browser UAT, fixed code-gap evidence, compatibility boundaries, and final evidence packet rules.
• docs/versioning.md for SemVer, breaking-change, deprecation, rollback, and verification expectations.
• docs/upgrade.md for upgrade classes, rollout sequencing, database-migration review, and rollback planning.
• docs/deployment.md for image target, tag, Coolify, health, readiness, and deployment evidence boundaries.
• docs/migration-registry.md for migration ownership, deadlines, rollback notes, and redacted evidence rules.
• docs/security.md for secret redaction, incident handling, provider boundaries, and prohibited shared evidence.
• docs/observability.md for health, readiness, request IDs, queue/job IDs, and safe production diagnostics.
• docs/porting-verification.md for documentation-porting verification, package-manager wording, and manual E2E policy.

Pre-release readiness

Complete these checks before changing version numbers, tags, or release records:

• The release owner, reviewer, target release entry, and release window are named with generic role labels when the record is shared outside the deployment boundary.
• The release entry under docs/releases/ exists or is planned with the naming rules from docs/releases/README.md.
• Known risks, migration-sensitive changes, deployment-sensitive changes, and security-sensitive changes are listed in docs/migration-registry.md or explicitly marked as not applicable.
• The automatic verification commands in this checklist are limited to supported non-E2E commands from package.json.
• Manual runtime checks are written as record fields with owner, date, target label, redacted status, and safe correlation IDs rather than as commands for automation.

SemVer and changelog alignment

Use docs/versioning.md as the release decision source:

• The release class is recorded as major, minor, or patch, with the reason tied to compatibility impact.
• Breaking changes include migration steps, rollback limits, and affected documented workflows before release.
• Deprecated behavior appears under Deprecated in CHANGELOG.md with replacement guidance and the earliest removal window.
• The release entry keeps the Keep a Changelog categories: Added, Changed, Deprecated, Removed, Fixed, and Security.
• Empty changelog categories state that no changes were introduced for that category.
• Package-manager examples stay aligned with the repository packageManager pin, pnpm@10.33.0.

Pre-release verification

Use only these automatic command examples for this release-documentation surface:

pnpm run verify:release-docs
pnpm run verify:staging-live-uat-readiness
pnpm run verify:release-docs-baseline
pnpm run verify:docs-links

Record the command name, exit code, checked surface, and short PASS or FAIL summary. Do not paste full environment values, registry credentials, provider payloads, screenshots, cookies, tokens, customer data, tenant identifiers, or secret-shaped examples into the release record.

Changelog and version tagging

When the release is ready to cut:

• Confirm the version in the release record matches the SemVer decision and the relevant changelog entry.
• Confirm release notes do not include unresolved marker text or future-tense guarantees for behavior that is not implemented.
• Confirm the tag or version reference is immutable once published.
• Keep artifact references placeholder-shaped when documenting the expected image format, such as {registry}/{namespace}/{web|api|worker}:{tag}.
• If a release entry moves from a dated planning file to a versioned file, update local links in the same change.

Release-cut steps

The release owner should create or update the release record with these fields:

Field	Required content	Redaction boundary
Release summary	One paragraph describing the release scope.	No customer names, tenant names, or provider payloads.
SemVer decision	Major, minor, or patch plus compatibility reason.	No private roadmap labels unless already public.
Changelog alignment	Link to the CHANGELOG.md section and category coverage.	No unresolved marker text.
Verification evidence	Supported non-E2E commands and exit summaries only.	No browser traces, screenshots, cookies, tokens, or environment dumps.
Artifact/tag evidence	Release tag, commit SHA label, image target label, package version, or signed-artifact status.	Use placeholder registry and namespace labels, not real hosts or credentials.
Rollback notes	Redeploy, backup-restore, queue-control, forward-fix, or unsupported rollback decision.	No raw database, Redis, registry, Coolify, or provider values.
Manual runtime evidence	Human-approved record fields for runtime checks when required.	Redacted status and safe correlation IDs only.

Artifacts and rollback

Artifact evidence should identify what was released without exposing where secrets live:

• Release tag or version label is recorded.
• Commit SHA label or build job label is recorded when available.
• Deployable targets are named generically as web, api, and worker when relevant.
• Image examples use {registry}/{namespace}/{web|api|worker}:{tag} only.
• Rollback says whether a prior artifact redeploy is sufficient, a database backup restore is required, queue pause or drain is required, or rollback is unsupported after migration.
• Readiness or health follow-up references safe fields from docs/observability.md, such as status, target label, request ID, job ID, queue name, or redacted dependency code.

Migration and rollback review

For every migration-sensitive change, review docs/upgrade.md and docs/migration-registry.md:

• The migration entry has an owner, status, deadline, rollback path, and verification evidence.
• Documentation-only migrations are not described as database migrations.
• Database-affecting changes confirm backup or restore-point readiness before production deployment.
• Worker or queue changes state whether queues must be paused, drained, replayed, or monitored manually.
• Security or provider changes follow docs/security.md and record only provider category, delivery status, signing status, request ID, job ID, or redacted diagnostic code.

Post-release monitoring and support handoff

After the release is cut, hand off support with a concise redacted record:

• Release version or tag label.
• Deployment target labels and immutable tag labels when available.
• Health or readiness status labels for web, API, worker, database, Redis, Mailjet, browser runtime, or deployment as applicable.
• Safe request IDs, job IDs, queue names, timestamps, and redacted dependency codes from docs/observability.md.
• Known follow-up work, owner, and deadline.
• Rollback contact path and safest stopping point.

Manual runtime evidence

Manual runtime checks are allowed as evidence records only when a human approves and performs the exact runtime activity. Keep them separate from automatic command examples.

Manual-only record fields may include:

• Browser journey label and redacted outcome.
• Playwright or Cypress review label and redacted outcome.
• Live Docker smoke label and redacted outcome.
• Live registry publish label and immutable target tag.
• Coolify deployment label and redacted status.
• Provider-console review label, provider category, request ID, delivery status, signing status, or redacted diagnostic code.
• Production health/readiness status, target label, request ID, job ID, queue name, and timestamp.

Do not present Playwright, Cypress, browser automation, live Docker, live registry, Coolify, provider-console, or production checks as automatic release commands unless a future documented policy explicitly approves that exact class of check.

Redaction requirements

Release records, tickets, docs, verification summaries, and support handoff notes must not include:

• Registry hosts, registry credentials, namespaces tied to private accounts, passwords, tokens, bearer headers, API keys, cookies, or secret-shaped sample values.
• Coolify webhook URLs, UUID-like deploy endpoints, deploy tokens, or provider-console URLs.
• Database URLs, Redis URLs, Supabase keys, Mailjet keys, browser runtime credentials, or full environment dumps.
• Tenant identifiers, customer domains, customer data, email addresses from customers, provider payloads, raw queue payloads, database rows, or screenshots containing sensitive data.
• Stack traces or logs that include any of the above.

Use placeholder key names, generic target labels, immutable tag labels, redacted diagnostic codes, request IDs, job IDs, queue names, and PASS or FAIL summaries instead.

Non-E2E verification

For documentation-only updates to this release checklist, use scoped non-E2E verification:

pnpm run verify:release-docs
pnpm run verify:docs-links

For the broader Release Docs release-documentation baseline, use:

pnpm run verify:release-docs-baseline

These commands verify repository files and links only. Browser flows, Playwright, Cypress, live Docker, live registry, Coolify, provider-console, and production-runtime checks remain manual runtime evidence unless explicitly approved outside this automatic documentation checklist.