namht-migratelisted

# namht-migrate — change a shared contract safely, with nobody paged The dangerous moment in a microservice system is changing something **other services depend on**. The whole skill is one idea: **never flip a breaking change in one step** — run old and new in parallel, move consumers, then remove the old only once nothing uses it. ## Step 1 — find who depends on it (before touching anything) A change is only "safe" once every consumer is known. - **Cross-service** consumers: the **Event/Contract Catalog** (`17-async-events.md`) + `system-map/` give you who publishes/consumes each queue/topic and which services call each endpoint. - **In-repo** consumers: grep callers of the symbol/endpoint/column. - Classify each: compatible (additive) vs **breaking** (removed/renamed/retyped/semantics changed). ## Step 2 — pick the safe strategy (parallel change) Default: **expand → migrate → contract**, shipped as separate, independently deployable steps. - **DB (Flyway / ActiveRecord / Prisma):** additive first — add a **nullable** column / new table (`V<n>__add_x`), **backfill** in a batched job, **dual-write** old+new, switch reads, then **drop the old in a LATER migration** once nothing reads it. Never rename/drop in the same release as the switch. - **API:** add fields as optional; for breaking shape changes use a **versioned** path (`/v2`) or content negotiation; keep `/v1` until consumers move. - **SQS / events:** add a `schemaVersion` and make producers emit and consume