Skip to content

Schema-watch diff view — show what changed since last visit #185

Closed

Description

@thomas-stegemann

Problem

Bowire already has Schema-Watch (#138) that re-runs discovery on a configurable interval. What it doesn't do is TELL the operator what changed. The natural "I came back from lunch, what's new in this API?" workflow doesn't exist.

Proposal

Diff-aware schema watch. Every time the watch detects a change, capture:

  • Added services / methods (green)
  • Removed services / methods (red)
  • Changed signatures — input or output type changed, status code added/removed, deprecated tag added (yellow)
  • New annotations / descriptions

Surface as:

  • Statusbar pill — "3 changes since 14:30" → click expands
  • Discover rail badge — sidebar entry pulses gently when there's an unread change
  • Change log — chronological list of every detected change in the workspace, retained for 7 days

Diff is computed at the AST level (proto descriptors, OpenAPI nodes, GraphQL schema), not as a string-diff — so reordering a field doesn't show as a change but moving it from optional to required does.

Acceptance

  • AST-level diff between two discovery results
  • Statusbar pill with change count + dropdown
  • Discover rail badge for unread changes
  • 7-day change log per workspace
  • Click on a change navigates to the affected method in Discover
  • Detected change types: add / remove / signature-change / deprecation / annotation
  • Per-workspace setting for watch interval (already exists; surface in workspace-detail)

Related

Activity

  1. moved this to Backlog in Bowireon Jun 15, 2026
  2. thomas-stegemann commented on Aug 4, 2026

    @thomas-stegemann
    MemberAuthor

    Shipped in fecdacd (main).

    Every acceptance box, walked against a live OpenAPI host mutated under a running watch:

    • AST-level diff between two discovery results — the Schema watch mode #48 keyed-set diff now classifies each changed method by facet (route / invocation type / request / response shape), and field order is normalised before comparing, so a swagger-gen/protoc rebuild that merely reorders properties stays silent while optional → required still reports.
    • Statusbar pill + dropdown — "3 changes since 14:30" next to the watch toggle while unread, decaying to "12 changes · 7d" once read; the dropdown is the chronological log (glyphs + − ~ ! ±, colour-coded, unread rows accented).
    • Discover rail badge — gently pulsing dot on the rail icon while unread changes exist (suppressed in embedded mode, where the statusbar — and with it the pill that clears the pulse — is hidden).
    • 7-day change log per workspace — server-side at workspaces/<id>/schema-changes/log.json (new SchemaChangeLogStore + GET/POST /api/schema-changes, POST /api/schema-changes/read), 500-entry cap, duplicate-observation collapse across clients, write-then-rename for git-backed checkouts. Browser-only (Workspace storage mode — workspace-level field (precursor to #196) #212) workspaces stay session-local.
    • Click navigates to the method — rows open the affected method in Discover; removed entries are inert (nothing left to open).
    • Change types add / remove / signature-change / deprecation / annotation — deprecation flips are their own type; prose-only edits are recorded as the quiet ± annotation type in the log but never toast or mark the sidebar (Schema watch mode #48's discipline stands).
    • Watch interval surfaced in workspace-detail — per-workspace override in the General tab, inheriting the global Settings value when empty.

    One deliberate design point: entries are re-stamped with the server clock on append and the read watermark only moves forward, so skewed browser clocks can't produce changes that are born read or can never be read.

    Docs: settings.md, workspace.md, topbar.md (now documents the statusbar the watch controls actually live in), release notes. Tests: 482 JS + 2442 C# green, including an adversarial-review pass whose 23 findings are all addressed in the shipped commit.

  3. moved this from Backlog to Done in Bowireon Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    • Status
      Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions