Migration Registry

Purpose

This registry is the release-facing index for migrations that need explicit ownership, deadlines, rollback notes, and verification evidence before a release is cut. It covers documentation, operational, configuration, and database-affecting migration contracts, but each entry must state its real surface and must not imply that a documentation-only change is a runtime database migration.

Use this registry with the existing runbooks:

docs/database.md for PostgreSQL, Prisma, backup, restore, migration-status, and redacted database diagnostics.
docs/upgrades.md for the deeper upgrade workflow and manual runtime boundaries.
docs/deployment.md for image, tag, Coolify, health, rollback, and manual deployment evidence.
docs/security.md for secret redaction, incident evidence, provider boundaries, and data-handling prohibitions.
docs/versioning.md for SemVer, changelog, breaking-change, deprecation, rollback, and verification expectations.

Entry schema

Each registry row must include:

ID: stable migration identifier, usually milestone/slice/task or release-entry scoped.
Surface: affected documentation, database, deployment, configuration, API, worker, provider, or security surface.
Risk: docs-only, low, medium, high, or critical based on rollback complexity, data impact, security sensitivity, and operator coordination.
Owner: accountable maintainer, release role, or owning team. Do not leave owner blank.
Status: one value from the status vocabulary below.
Deadline: release, date, or explicit release window by which the migration must be resolved.
Rollback: safest rollback or revert path, including whether backup restore or prior artifact redeploy is required.
Verification evidence: non-secret command output summary, checklist result, artifact/tag identifier, or manual-runtime note.
Redaction notes: specific data that must stay out of the registry and linked release evidence.

Optional extended fields for detailed entries include dependencies, reviewer, affected tenants or customers described only as generic labels, and links to release notes or runbooks.

Status vocabulary

Status	Meaning
`proposed`	Identified but not yet accepted for the release.
`planned`	Accepted for the release with an owner and deadline.
`in-progress`	Implementation or documentation work is active.
`blocked`	Cannot proceed without an explicit dependency or decision.
`verified`	Implementation is complete and the stated non-secret verification evidence exists.
`rolled-back`	Reverted or restored through the documented rollback path.
`superseded`	Replaced by a newer registry entry or release decision.

Rows must not use vague placeholders such as unresolved markers. If a deadline or owner is unknown, keep the row in proposed status and add a concrete decision needed in the redaction or notes field without using placeholder marker text.

Risk classification

docs-only: documentation roots, release templates, checklists, or registry entries that do not change runtime behavior or persisted data.
low: reversible configuration or packaging changes with no stored-data impact and clear static verification.
medium: deployment, runtime, or provider-boundary changes that require coordinated rollout or manual runtime inspection.
high: database, queue, authentication, authorization, or security changes where rollback may require prior artifacts, queue controls, or backup/restore confirmation.
critical: destructive or externally visible changes where rollback is not automatic, requires production incident coordination, or can expose sensitive data if mishandled.

Database-affecting entries must link back to docs/database.md, use parameterized or ORM-safe migration paths where applicable, and record only redacted migration-status or deployment evidence.

Registry table

ID	Migration entry	Surface	Risk	Affected surfaces	Owner	Status	Deadline	Rollback	Verification evidence	Redaction notes
Release Docs-S03-T01	Canonical upgrade-guide root at `docs/upgrade.md`.	Documentation	docs-only	Upgrade entrypoint, release-upgrade checklist, links to deeper runbooks.	Release docs maintainer	verified	Release Docs/S03 baseline close	Revert the `docs/upgrade.md` addition if it misstates the upgrade contract, then restore the prior release-doc inventory expectation.	`test -s docs/upgrade.md` and `pnpm run verify:docs-links` passed in T01.	No credentials, connection strings, tenant identifiers, customer data, provider payloads, screenshots, or browser/E2E evidence.
Release Docs-S03-T02	Release documentation root and initial release entry at `docs/releases/`.	Documentation	docs-only	Release checklist, changelog alignment, artifact/tag evidence, pre-release and post-release boundaries.	Release docs maintainer	verified	Release Docs/S03 baseline close	Revert the `docs/releases/README.md` and initial release entry additions, then keep release notes in `CHANGELOG.md` until the root is corrected.	`pnpm run verify:docs-links` passed in T02.	Keep registry hosts, namespaces, Coolify URLs, UUIDs, tokens, provider-console details, and browser/E2E recordings out of release evidence.
Release Docs-S03-T03	Migration registry root at `docs/migration-registry.md`.	Documentation	docs-only	Migration ownership, status, deadlines, rollback, verification, redaction, and release-facing migration index.	Release docs maintainer	in-progress	Release Docs/S03 baseline close	Revert this file if the schema mixes docs-only migrations with real database migrations or weakens redaction rules.	`test -s docs/migration-registry.md` and `pnpm run verify:docs-links` are required for this task.	Registry rows must exclude secrets, raw connection strings, tenant identifiers, customer data, provider payloads, and browser/E2E evidence.
Release Docs-future-release-doc-roots	Future release-upgrade documentation roots discovered by baseline inventory.	Documentation	docs-only	Future release entries, migration-contract docs, changelog-adjacent runbooks, and baseline documentation inventory.	Release docs maintainer	planned	Next release-documentation slice that introduces the root	Do not create runtime migrations for missing documentation roots; revert or rename the documentation root and update this registry if the future path changes.	Future rows must use focused docs-link verification and the applicable baseline inventory verifier before being marked `verified`.	Future entries may reference command names, artifact labels, and generic statuses only; no live provider payloads or sensitive runtime evidence.

Verification and evidence rules

Acceptable registry evidence includes focused non-E2E commands, static verifier PASS/FAIL summaries, reviewed release checklist status, immutable image tag labels, migration-status phase and exit code, backup or restore-point confirmation labels, and manual-runtime notes that contain only redacted facts.

Unacceptable evidence includes raw database URLs, Redis URLs, registry credentials, Coolify webhook URLs, bearer tokens, API keys, cookies, tenant identifiers, customer domains, customer data, provider payloads, raw job payloads, database dumps, screenshots with secrets, browser recordings, Playwright traces, Cypress artifacts, and full environment dumps.

Browser, Playwright, Cypress, live Docker, live registry, Coolify, provider-console, and production traffic checks remain manual runtime boundaries unless a human explicitly approves the exact focused run. When such checks are required for a release, record only the manual check label, operator, status, target name, immutable tag or request ID, and redacted failure code.

Negative checks

Before marking this registry healthy for a release baseline, verification must reject these conditions:

docs/migration-registry.md is missing or empty.
Any local markdown link in this file is unresolved.
The registry table omits owner, status, or deadline fields.
A docs-only migration is represented as a real database migration.
A registry row stores sensitive evidence instead of redacted summaries.
Unresolved marker text is present in the file.

8.5 KiB Raw Blame History