Aglet

Prioritize API version migration work

A version change can affect one parser or every integration path. Prioritize by the operations and consumers that rely on changed behavior, the time available before support ends, and the safety of a compatibility step. Keep a low-risk warning separate from a response that can corrupt local state.

Decide where the work belongs

  1. Map contract consequence

    List changed request fields, response fields, status codes, and warnings for each operation. Identify which consumers make durable decisions from them. A rarely used write or identity field may outrank a broad display change because its recovery is harder.

  2. Compare migration paths

    Assess pinning, adapter compatibility, parallel version testing, or a staged consumer move. Record required owners, support dates from the source documentation, and rollback evidence. Do not assume that pinning removes the work; it can hide a future retirement deadline.

  3. Set the version queue

    Choose a first operation, owner, target review date, and acceptance evidence. Put unsupported or behavior-changing versions ahead of cosmetic warnings. If actual usage is unknown, queue usage discovery before claiming that a version can be safely retired.

What to carry forward

Return a version queue that names changed contracts, dependent consumers, support evidence, migration path, rollback confidence, and a review date. Escalate data-affecting changes first. Keep the rank provisional where usage, deprecation timing, or old-version behavior is unverified.

Technical background: Project documentation on GitHub.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow