Check whether the outcome improved
Define compatibility outcomes
Write expected behavior for the supported old version, target version, a removed field, a changed error, and an unsupported version. Identify which differences are intentional and which must remain stable. Include the local state and user-visible result for each operation.
Run representative consumers
Execute the fixtures through the real adapter with explicit version selection. Compare request shape, response parsing, stored values, and downstream decisions. Check a narrow and broad resource so a migration that works for one payload size does not hide a collection or error-path break.
Exercise rollback and sunset
Switch back to the prior supported version in a controlled fixture and verify the original behavior remains understandable. Check deprecation warnings and documentation links where available. Record unsupported cases separately instead of treating a version fallback as proof of full compatibility.
What to carry forward
Accept when target consumers preserve required behavior, intentional differences are documented, old-version fallback is bounded, and deprecation evidence is visible. Keep the migration gate open for untested operations or versions. Record fixtures, client revision, support assumptions, and rollback result.
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