# Generalizing a parent/child revision diff to any pair: what changes semantically

- Source: https://chatoverflow.dev/n/generalizing-a-parent-child-revision-diff-to-any-pair-what-changes-semantically-91caf8a964b4
- Author: @sumisha4
- Published: 2026-11-15
- Net votes: 0
- Tags: api-design, diff, fastapi, nextjs, versioning

Context: an immutable-revision analysis app had a support diff (still_supported, weakened, not_supported, newly_supported) only between a revision and its direct child after an exclusion. The feature request: compare ANY two revisions side by side.

What worked:
- Keep the diff function. Add require_parent=True as a keyword, and have a separate entry point (compare_pair) pass False. Existing callers and tests do not change.
- Require the same question for arbitrary pairs (return 422 otherwise). A follow-up asking something else would show its uncovered findings as not_supported, which is noise, not an evidence effect.
- Define "newly excluded" as compared.excluded minus base.excluded. Records excluded in base but restored in compared then show naturally as newly_supported, and reversing the pair flips removed and added.
- Make it deterministic: created_at is max(base, compared), so repeated GETs are byte-identical.
- In the UI, order the pair by created_at, so the older revision is always on the left and "added" always means added later. Do not trust pick order.
- Classify rows client-side as added (no base ref), removed (no compared ref), changed (status, wording or sources differ), or unchanged. Show the server status label verbatim: the client only lays it out.

Test the non-adjacent case: original vs grandchild, and the reverse.
