Standardized workflow for testing schema changes and migrations to the repository

[mutterback]

Summary

Add a clear, standardized workflow for testing schema changes and migrations to the repository README to prevent data loss and ensure safe deployments.

---

Problem

The repository currently includes migration and Postgres guidance, but does not define a clear, repeatable workflow for:

• testing schema changes safely
• validating migrations before deploy
• avoiding data loss during development

This has already led to confusion around:

• whether to run migrations on an existing dev database
• when to use seeding
• when to rely on Vercel preview

---

Scope

1. Add new README section

Create a new section in README.md:

## Testing schema changes and migrations

2. Document the required workflow

Add a clear, step-by-step process:

Local testing (required for schema changes)

• create a fresh local Postgres database per issue
• update .env to point to that database
• run:
  • pnpm payload migrate:create
  • pnpm payload migrate
• start the app and verify behavior in:
  • admin
  • frontend

Seeding rules

• clearly state that seeding is destructive
• only seed disposable databases

Preview validation

• use Vercel preview as a secondary check only
• ensure preview uses safe (non-production) data

Merge and deploy flow

• verify locally first
• verify preview deployment
• merge to main to trigger production deploy
• ensure migrations run successfully in CI (payload migrate && pnpm build)

3. Keep documentation concise and actionable

• avoid duplicating existing setup instructions
• reference existing Postgres and migration sections where appropriate
• focus on safe workflow and decision-making

---

Acceptance criteria

• README contains a new section: “Testing schema changes and migrations”
• Instructions clearly define:
  • when to use a fresh database
  • how to run migrations locally
  • when seeding is safe
  • when to use preview deployments
• Workflow is easy to follow and consistent with existing repo structure
• No contradictions with current README setup instructions
• Reduces ambiguity around migration safety and deployment flow

---

Notes for implementation

• Keep tone consistent with the rest of the README
• Place this section near existing Postgres / migration documentation
• Do not introduce a separate docs file — README should remain the single source of truth
• This should act as the canonical workflow for all future schema changes

---

Suggested Codex task framing

Update the README to include a clear “Testing schema changes and migrations” section that defines the required workflow for safely testing migrations locally, validating via preview, and merging without risking data loss.