docs: document D1 migration numbering convention

[kentcdodds]

Summary

packages/worker/migrations/ has four duplicated 4-digit prefixes from
earlier parallel-branch merges:

• 0009-secret-allowed-hosts.sql / 0009-ui-artifact-parameters.sql
• 0010-secret-allowed-capabilities.sql / 0010-value-buckets.sql
• 0018-jobs.sql / 0018-mcp-memory-source-uris.sql
• 0023-entity-sources.sql / 0023-secret-allowed-packages.sql

We're not changing anything on disk: D1 tracks applied migrations by
exact filename, the apply order is stable (Wrangler sorts the full
filename), and all four pairs are additive (new tables/indexes only) so
ordering is not behaviorally significant.

This PR just documents the situation and the numbering convention going
forward, in a new "Authoring D1 migrations" section in
docs/contributing/setup.md. Specifically:

• Pick the next-highest 4-digit prefix; rebase and renumber on collision.
• Existing migration files that have landed in main are immutable (this
  bullet was previously under "Documentation maintenance" and is moved
  here since it is really a migration-authoring rule).
• The four duplicate prefixes are grandfathered — don't rename them, and
  don't add a third file to any of those prefixes.

What this PR does not do

• Does not rename any .sql file.
• Does not modify any test (the legacy-inline-sources,
  jobs-codemode-only, and unified-email-receipt migration tests
  continue to reference filenames like 0009-ui-artifact-parameters.sql,
  0018-jobs.sql, and 0023-entity-sources.sql directly).
• Does not touch any production / preview / local D1 ledger.

Verification

Docs-only change. Verified oxfmt --check is clean on the modified file.

  

Summary by CodeRabbit

• Documentation
  • Updated D1 migration documentation with guidance on naming conventions using zero-padded 4-digit prefixes, handling upstream migration conflicts, and rules for modifying deployed schemas through new migrations rather than editing existing deployed migration files.

[coderabbitai]

Warning

Rate limit exceeded

@cursor[bot] has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 55 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ac02a140-fc8d-49ea-9b07-c3e135cd0a07

📥 Commits

Reviewing files that changed from the base of the PR and between c459995 and 5dbf669.

📒 Files selected for processing (1)

• docs/contributing/setup.md

📝 Walkthrough

Walkthrough

This pull request consolidates D1 migration authoring guidance by introducing a dedicated "Authoring D1 migrations" documentation section with step-by-step naming conventions, conflict resolution procedures, and constraints on editing deployed migrations, while removing duplicate guidance from the "Documentation maintenance" section.

Changes

D1 Migration Documentation

Layer / File(s)	Summary
New D1 Migration Authoring Guide docs/contributing/setup.md	Adds "Authoring D1 migrations" section with instructions for naming migration files with 4-digit zero-padded prefixes, handling upstream prefix collisions, and rules prohibiting edits to already-deployed main migrations (use new migrations for corrections instead).
Documentation Consolidation docs/contributing/setup.md	Removes "do not edit migration files that have already landed in main" guidance from "Documentation maintenance" section to eliminate duplication.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• kentcdodds/kody#101: Documents the "never edit existing migrations" rule in agent setup context.
• kentcdodds/kody#178: Modifies migration-editing rules in the same setup.md file to clarify immutability of deployed migrations.

Poem

🐰 A section blooms, migrations clear,
No duplicate words need appear.
Four digits guide each file's name,
Deployed migrations stay the same.
🌱✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and concisely describes the main change: documenting the D1 migration numbering convention in the setup guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/rfc-migration-prefix-collisions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-407.kentcdodds.workers.dev

Worker: kody-pr-407
D1: kody-pr-407-db
KV: kody-pr-407-oauth-kv

Mocks:

• ai: https://kody-pr-407-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-407-mock-ai)
• cloudflare: https://kody-pr-407-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-407-mock-cloudflare)

[coderabbitai]

🧹 Nitpick comments (1)

docs/contributing/setup.md (1)

113-114: ⚡ Quick win

Consider clarifying the duplicate-prefix prohibition.

The guidance "Do not commit a duplicate prefix" is clear, but since lines 119-124 document four existing duplicate prefixes, you might want to make the rule more precise to avoid confusion.

📝 Suggested clarification

 - If your branch is behind `main` and a new migration has landed upstream with
   the prefix you picked, rebase and renumber. Do not commit a duplicate prefix.
+  the prefix you picked, rebase and renumber. Do not commit a duplicate prefix
+  (beyond the four grandfathered pairs documented below).

Alternatively, you could rephrase to:

 - If your branch is behind `main` and a new migration has landed upstream with
-  the prefix you picked, rebase and renumber. Do not commit a duplicate prefix.
+  the prefix you picked, rebase and renumber to avoid adding new duplicate prefixes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/contributing/setup.md` around lines 113 - 114, Clarify the rule around
duplicate migration prefixes by replacing the terse sentence "Do not commit a
duplicate prefix" with an explicit instruction: state that if a migration prefix
already exists upstream (see the example duplicate prefixes listed nearby), you
must rebase onto main and renumber your migration to a unique unused prefix
before committing, and never reuse an existing prefix even if your local file
name matches — include a brief example of the before/after renumbering to
illustrate; update the sentence that currently reads "Do not commit a duplicate
prefix" to this more precise guidance so readers know to both rebase and choose
a new unique prefix.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/contributing/setup.md`:
- Around line 113-114: Clarify the rule around duplicate migration prefixes by
replacing the terse sentence "Do not commit a duplicate prefix" with an explicit
instruction: state that if a migration prefix already exists upstream (see the
example duplicate prefixes listed nearby), you must rebase onto main and
renumber your migration to a unique unused prefix before committing, and never
reuse an existing prefix even if your local file name matches — include a brief
example of the before/after renumbering to illustrate; update the sentence that
currently reads "Do not commit a duplicate prefix" to this more precise guidance
so readers know to both rebase and choose a new unique prefix.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d9d7291e-3468-410d-92ff-862670eb3b4d

📥 Commits

Reviewing files that changed from the base of the PR and between 1c23974 and c459995.

📒 Files selected for processing (1)

• docs/contributing/setup.md