Keep the lesson for the next incident
Maintain the version matrix
Record operation, request and response contract, explicit version, client revision, support status, and migration owner. Define which additions, removals, and behavior changes are breaking for this consumer. Link source documentation without copying a provider promise into product copy.
Keep cross-version fixtures
Retain a working pair for each important operation, including changed fields, errors, warnings, and an unsupported case. Store expected consumer state and redacted payload shapes. Keep one fixture for the last supported version so a later upgrade has a concrete comparison.
Schedule compatibility review
Set a review trigger for dependency upgrades, deprecation notices, new version defaults, and changed generated schemas. Assign a date and owner before the old version becomes urgent. Close the follow-up only when the matrix and fixtures match the versions actually selected in each environment.
What to carry forward
Close learning with a version matrix, cross-version fixtures, migration and rollback owners, and review triggers. Keep unknown consumer usage and external retirement dates visible. The goal is a deliberate upgrade path, not a permanent promise that versions will never diverge.
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