Aller au contenu

Migrations

Status: Placeholder — to be developed. Last reviewed: — Reference structural sibling: guidelines/i18n/translation-rules.md (process + rules style — short and prescriptive, not component-style).

Scope (when this guideline lands)

Conventions for Django migrations: when a data migration is required, naming, reversibility, how to coordinate migrations across environments (make migrate ENV=...), large-table guardrails, what to do when extracting i18n changes generates AlterField migrations.

Out of scope (cross-refs)

  • Model field conventions (which fields belong on a model, naming, choices) → guidelines/backend/models.md (placeholder).
  • Test-data reset (the make targets and scripts for clearing dev DBs) → docs/RESET_TEST_DATA.md (reference, not a guideline).
  • Database schema overview / table-level design → docs/entity-model.md and docs/CCAM_DATABASE_STRUCTURE.md (reference docs).

Sources to mine when writing this

  • Makefile — migrations, migrate, migrate ENV=staging|prod targets. Document what each runs and the env propagation logic.
  • Recent migrations across apps that involved data migrations or schema renames: scan apps/*/migrations/ for non-_auto_ named files.
  • The 2026-04 i18n convergence sweep (roadmap/done/i18n-french-source-convergence-2026-04.md) — generated metadata-only AlterField migrations across most apps; document the pattern.
  • Past incident notes on migrations that broke staging or prod (check roadmap/done/ for relevant entries).

Starter hard rules to investigate

  1. Always use make migrations, never raw python manage.py makemessages (per CLAUDE.md).
  2. Name migrations with intent: 0042_add_practice_timezone.py, not 0042_auto_20240418_1234.py. Pass --name to makemigrations.
  3. Never edit historical migrations. If a migration shipped to staging or prod, it's frozen — write a new one to fix.
  4. Data migrations need a reverse function (or explicit migrations.RunPython.noop with a comment explaining why irreversible).
  5. Large-table operations (>100k rows): require explicit batching, avoid AlterField that rewrites the table, prefer concurrent index creation.

Decision points to settle

  1. squashmigrations policy: when (yearly? per major release? never?), which apps have squash points already?
  2. Data migration vs management command: when does a one-off data fix go in a migration vs a separate command?
  3. Migration naming convention: 0042_add_X vs 0042_practice_add_X (app prefix in name)?
  4. Pre-deploy migration check: is there a CI step that verifies migrations apply cleanly to a staging-like DB? If not, propose.

Known deviations to look for during writing

  • Migrations with 0001_auto_* or generic _auto_ names (lost intent).
  • Edited historical migrations (compare git log against the migration file's apply date).
  • Data migrations without a reverse function and without a noop comment.
  • Migrations that drop+recreate columns (data loss risk).

If found, file as roadmap/backlog/backend-migrations-drift-2026-MM.md.