Infra migration

A preview of how this template lays out — the boards, their custom workflow states, and where the sample issues land. WIP caps show a badge.

• Add the new schema columns (expand phase)

  Additive only — old code keeps working.

  P13pt

• Backfill historical rows in batches

  P15pt

• Verify parity before cutover

  • gate
  P03pt

These rules aren't created when you apply the template — they're recipes you can wire up in Settings → Automations once your board exists.

• When

  Issue moves to 'Cutover'

  Then

  Require the parity-verification gate to be checked first

• When

  Migration reaches 'Contract'

  Then

  Create a rollback-plan archive issue before dropping old paths

Plan, Expand, Backfill, Dual-write, Cutover, Contract. These are not arbitrary phases — they are the expand–contract pattern, and the column order encodes the single property that makes a migration survivable: at every step before Cutover, both the old and the new path work, so the answer to 'something is wrong' is always 'stop' rather than 'finish faster'. Contract being last and separate is the discipline most teams skip, and skipping it is how an organisation ends up permanently maintaining two systems it meant to consolidate.

1. 1.Write the rollback plan during Plan, not during Cutover

   For each phase, state what you would do if it goes wrong and how long that would take. This is cheap to think about now and impossible to think about clearly at two in the morning with an incident open. The phases where rollback turns out to be hard are exactly the ones that need to be broken down further before you start.

2. 2.Keep Expand strictly additive

   New columns, new tables, new endpoints — nothing removed, nothing renamed, no existing behaviour changed. Old code must continue to work untouched against the expanded shape. This is the phase teams compress because it feels like busywork, and it is the phase that makes every later step reversible. A rename smuggled into Expand converts the whole migration into a coordinated deploy.

3. 3.Backfill in batches with a resumable cursor

   Historical data is where the surprises are: rows that predate a constraint, nulls the schema said were impossible, encodings from an earlier era. Batch the work, record progress so a failure resumes rather than restarts, and rate-limit against production load. Also decide up front what you will do with rows that cannot be converted, because there will be some.

4. 4.Use Dual-write to prove parity, not just to hedge

   Writing to both paths is the safety net, but the value is the comparison: run both reads, diff the results, and log the mismatches. Real parity is a number you can quote — how many divergences over how many operations, and what caused each one. The verification gate before Cutover should be that number, not a feeling that it has been running for a while.

5. 5.Wait before you Contract, and archive first

   Once traffic is on the new path, let it run through a full cycle of your business — a month-end, a peak day, a batch job that only runs quarterly — before dropping anything. Contract is irreversible in a way no earlier phase is. Archive the old data and the rollback procedure before removing the code that could use them.

This board encodes one opinion about how the work should run. Here is where that opinion is wrong and something else fits better.

• The system is small enough to move in one deploy. Not everything needs six phases. A table with ten thousand rows and one consumer can be migrated in a maintenance window, and the ceremony here would cost more than the risk it removes.
• You can afford downtime. Expand–contract exists to avoid a service interruption. If a two-hour window on a Sunday is genuinely acceptable to your users, a straightforward stop-migrate-start is simpler, faster and has fewer intermediate states to get wrong.
• The migration has no verification story. If you cannot describe how you would detect that the new path is producing wrong results, dual-write gives you false confidence rather than safety — you will be writing two divergent datasets and noticing months later. Solve verification before starting.
• It is a vendor migration you do not control. Moving between SaaS providers is bounded by their export and import capabilities, their API rate limits, and often a hard cutover they impose. The phases here assume you own both sides of the write path.

Honest comparisons, including where the other tool wins. Planoda is pre-launch, so nothing below is a benchmark — it is a description of how each product approaches this job.

• Jira

  A large migration in Jira usually becomes an epic with linked issues per phase, and its strength is cross-team visibility: several teams' work on the same migration rolls up somewhere a programme manager can read it. Migrations are frequently multi-team, and that rollup is not nothing.

  Where Jira is better: For a migration spanning many teams over multiple quarters, Jira's epic and portfolio hierarchy tracks progress across organisational boundaries better than a single board with six columns.

• A design document

  The most important artifact in any migration is the written plan — the current state, the target state, the phase definitions, the rollback procedure and the parity criteria. This board tracks execution against that document; it is not a substitute for writing one, and a migration board with no design doc behind it is usually a migration nobody has thought through.

  Where A design document is better: For the reasoning, the diagrams and the decision record, a document is better and should exist first. The strongest setup is the design doc linked from the board's parent issue, reviewed before Expand starts.

• Terraform and schema-migration tooling

  The mechanical half of this belongs in tooling that applies changes idempotently, records what has been applied, and refuses to run twice — infrastructure as code for the platform layer, versioned migration files for the schema. This board tracks the phases and the human gates around those runs.

  Where Terraform and schema-migration tooling is better: For applying and tracking the changes themselves, purpose-built tooling is better without qualification: it is repeatable, auditable and reviewable in a pull request. Use the board only for the decisions and the sequencing.