Skip to content

backend-changelog.md

Latest commit

 

History

History
151 lines (100 loc) · 4.81 KB

backend-changelog.md

File metadata and controls

151 lines (100 loc) · 4.81 KB
Raw

Backend API Changelog

This document tracks breaking backend API changes that may impact this frontend. Keep entries brief, actionable, and linked to implementation artifacts.

Purpose

  • Provide a single source of truth for backend API breaking changes.
  • Help frontend engineers plan migrations before backend deploys.
  • Record rollout status and required frontend action.

When to Add an Entry

Add an entry when any backend change can break existing clients, including:

  • Endpoint path or HTTP method changes.
  • Required request field changes (rename, type change, removal).
  • Response contract changes (field removal/rename/type change).
  • Auth, permission, or signature requirements that invalidate prior calls.
  • Error code/shape changes relied on by clients.

Process (Lightweight)

  1. Open a changelog entry in the same PR as the backend breaking change.
  2. Mark Status as Planned, then update to Released when deployed.
  3. Link migration notes and owning team.
  4. Frontend owner updates Frontend Impact and marks Frontend Ready.

Entry Template

Copy this block for each new change:

## YYYY-MM-DD — <Short Change Title>

- **Status:** Planned | Released | Rolled Back
- **Effective Date:** YYYY-MM-DD
- **API Surface:** <endpoint(s) / webhook(s) / contract area>
- **Change Type:** Breaking
- **Owner:** <team/person>
- **Tracking:** <PR/issue/incident link>

### What Changed

- <concise list of contract-level changes>

### Frontend Impact

- <what breaks and where in frontend>

### Required Frontend Action

- [ ] <migration step 1>
- [ ] <migration step 2>

### Migration Notes

- <request/response before/after summary>
- <fallback/rollout notes if any>

2026-02-25 — Backend API changelog process introduced

  • Status: Released
  • Effective Date: 2026-02-25
  • API Surface: Process / Documentation
  • Change Type: Breaking-change governance
  • Owner: Frontend + Backend maintainers
  • Tracking: docs/backend-changelog.md

What Changed

  • Added a dedicated process for recording backend API breaking changes.
  • Standardized a single entry template for migration planning.

Frontend Impact

  • None to runtime behavior.
  • Future breaking backend updates now require this document to be updated.

Required Frontend Action

  • Add changelog process documentation.
  • Enforce changelog updates in backend PR template (follow-up).

Migration Notes

  • This is a non-runtime governance entry that establishes the baseline process.

2026-02-25 — Initial baseline: no pending breaking backend changes

  • Status: Released
  • Effective Date: 2026-02-25
  • API Surface: Existing documented frontend-consumed APIs
  • Change Type: Baseline
  • Owner: Frontend + Backend maintainers
  • Tracking: docs/backend-changelog.md

What Changed

  • Recorded the starting point for changelog adoption.

Frontend Impact

  • No known pending breaking changes at the time of baseline creation.

Required Frontend Action

  • Use this baseline as reference for all future breaking-change entries.

Migration Notes

  • First true backend contract break after this date must be added as a new dated entry.

2026-05-28 — Compliance score scaling consistency fix

  • Status: Released
  • Effective Date: 2026-05-28
  • API Surface: Contracts service (src/lib/backend/services/contracts.ts)
  • Change Type: Bug fix (data consistency)
  • Owner: Frontend team
  • Tracking: Internal issue

What Changed

  • Fixed compliance score scaling asymmetry in the contracts service
  • Previously: recordAttestationOnChain divided scores by 100 before sending on-chain, but parseChainCommitment and parseAttestationResult did not re-scale when reading back
  • Now: Both write and read paths consistently use ANALYTICS_SCALE (100) for scaling
  • Added comprehensive documentation for the ANALYTICS_SCALE constant
  • Added round-trip scaling tests covering boundary values (0, 50, 100)

Frontend Impact

  • Compliance scores displayed to users will now show correct values (e.g., 85 instead of 0.85)
  • Previously corrupted scores from blockchain reads will now display correctly
  • No API contract changes - this is an internal implementation fix

Required Frontend Action

  • Fix scaling in parseChainCommitment (multiply by ANALYTICS_SCALE)
  • Fix scaling in parseAttestationResult (multiply by ANALYTICS_SCALE)
  • Add documentation for ANALYTICS_SCALE constant
  • Add round-trip scaling tests with boundary values

Migration Notes

  • This fix corrects a data consistency bug where compliance scores were incorrectly displayed
  • The scaling convention is now: divide by 100 on write, multiply by 100 on read
  • Example: Score 85 → 0.85 on-chain → 85 in application (correct round-trip)
  • Tests verify no float precision loss for typical scores (0, 25, 50, 75, 85, 92, 100)