Open Plant WSI
WS-10

Migration Guide and API Lifecycle

This page defines how API changes are introduced, documented, and validated before release. Use it as the source of truth for upgrades.

1. Stability contract

SemVer: patch = fixes only, minor = backward-compatible additions, major = breaking changes.
No silent breakage: runtime behavior changes must be announced in docs and changelog before release.
Type-first policy: public type changes require updated API tables and migration examples in the same PR.

2. Deprecation lifecycle

N: add replacement API and mark old API deprecated in docs.
N+1 minor: keep compatibility and emit migration guidance in release notes.
N+2 minor: keep compatibility one more cycle unless security issue forces faster removal.
Next major: remove deprecated API, keep explicit migration section.

3. Breaking-change checklist

  1. Update exported types and runtime code in one change-set.
  2. Add before/after usage snippets in this guide.
  3. Update `docs/en/api-reference.html` and `docs/ko/api-reference.html`.
  4. Update `CHANGELOG.md` with migration notes.
  5. Pass release gate (`typecheck`, `test:ws9`, `build:lib`).

4. `mpp` and stamp conversion formulas

mpp means microns per pixel at native pyramid level (maxTierZoom). Stamp physical size is computed from mpp and current zoom. 

resolution_um_per_px = 2^(imageZoom - currentZoom) * imageMpp
area_um2 = area_mm2 * 1000 * 1000

square_side_px = sqrt(area_um2) / resolution_um_per_px
circle_radius_px = sqrt(area_um2 / PI) / resolution_um_per_px
If mpp is missing, Open Plant falls back to 1μm/px. In that case, stamp physical size is approximate.

5. Before/after examples

// Before (legacy alias, still supported)
<WsiViewerCanvas drawTool="stamp-circle-hpf-0.2mm2" />

// After (preferred explicit control)
<WsiViewerCanvas
  drawTool="stamp-circle"
  stampOptions={{ circleAreaMm2: 0.2 }}
/>
// Before (main-thread clipping)
<WsiViewerCanvas clipPointsToRois clipMode="sync" />

// After (recommended default)
<WsiViewerCanvas clipPointsToRois clipMode="worker" />

6. Release gate (fixed)

Every publish must pass the same command locally and in CI. 

npm run release:gate
# typecheck + test:ws9 + build:lib

CI workflow: .github/workflows/release-gate.yml
Publish hook: prepublishOnly runs release:gate before packing.

Open Plant WSI Docs •