docs: KEEP-432 document @requires-db-prep directive and merge gate#1293
Open
OleksandrUA wants to merge 1 commit into
Open
docs: KEEP-432 document @requires-db-prep directive and merge gate#1293OleksandrUA wants to merge 1 commit into
OleksandrUA wants to merge 1 commit into
Conversation
Adds the operator runbook and authoring contract for the new @requires-db-prep directive that was introduced as part of the KEEP-432 incident response. - CLAUDE.md gets a "Heavy DDL Migrations" subsection under the existing Database Migrations section: when to use the directive, how to author a migration that uses it, the operator runbook for the manual CREATE INDEX CONCURRENTLY step, the db-prep-check workflow + db-prepped-<branch> label gate, and what happens on deploy (no-op via IF NOT EXISTS). - AGENTS.md gets its Database Migrations section corrected (previously said "Never Write Manual Migrations" and listed db:push as the apply step, both wrong for this repo) and gains a bullet pointing at the directive with a one-line summary. No code changes. Reference docs only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the
@requires-db-prepdirective anddb-prep-checkmerge gate that were introduced during KEEP-432 incident response. No code changes - reference docs only.Tracking: KEEP-432
Why now
The mechanism was added in PR #1219 (and merged via #1281 + #1283), but the contract (when to use the directive, how to author a migration, the operator runbook) lives only in PR comments and commit messages right now. This makes it discoverable to both humans and AI agents who read
CLAUDE.md/AGENTS.mdwhen working in this repo.What changed
CLAUDE.md: adds aHeavy DDL Migrationssubsection under the existing Database Migrations section. Covers: when to use the directive, how to author the SQL, the pre-merge operator runbook, what the gate does, and what happens on deploy.AGENTS.md: existing Database Migrations bullets were outdated (said "Never Write Manual Migrations" and listeddb:pushas the apply step, neither of which match how this repo actually works). Corrected to matchCLAUDE.mdand adds a one-line bullet pointing at the directive with a pointer to the full operator runbook.What did NOT change
CLAUDE.mdrule "No Random Documentation").CLAUDE.md/AGENTS.mdwhere developers actually look.Test plan