Open Plant WSI
WS-10

마이그레이션 가이드와 API 수명주기

API 변경을 도입하고 문서화하고 검증하는 기준 문서입니다. 업그레이드 시 이 페이지를 기준으로 판단하세요.

1. 안정성 계약

SemVer: patch = 버그 수정, minor = 하위호환 기능 추가, major = 브레이킹 변경.
무통보 변경 금지: 런타임 동작 변경은 배포 전 문서/체인지로그 공지가 필수.
타입 우선: 공개 타입 변경 시 API 표와 마이그레이션 예시를 같은 PR에서 갱신.

2. Deprecation 수명주기

N: 대체 API 추가 후 기존 API를 문서에서 deprecated 표시.
N+1 minor: 호환 유지 + 릴리스 노트에 마이그레이션 안내.
N+2 minor: 호환을 한 번 더 유지(보안 이슈 제외).
다음 major: deprecated API 제거 + 마이그레이션 섹션 유지.

3. 브레이킹 변경 체크리스트

  1. export 타입과 런타임 코드를 하나의 변경셋으로 반영한다.
  2. 이 문서에 before/after 사용 예시를 추가한다.
  3. `docs/en/api-reference.html`, `docs/ko/api-reference.html`를 동시 갱신한다.
  4. `CHANGELOG.md`에 마이그레이션 노트를 기록한다.
  5. 릴리스 게이트(`typecheck`, `test:ws9`, `build:lib`)를 통과한다.

4. `mpp`와 스탬프 물리 크기 변환식

mpp는 네이티브 피라미드 레벨(maxTierZoom) 기준 픽셀당 마이크론(μm/px)입니다. 스탬프 물리 크기는 mpp와 현재 줌으로 환산됩니다. 

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
mpp가 없으면 1μm/px 가정으로 계산합니다. 이 경우 물리 크기는 근사치입니다.

5. Before/After 예시

// Before (레거시 별칭, 아직 지원)
<WsiViewerCanvas drawTool="stamp-circle-hpf-0.2mm2" />

// After (권장)
<WsiViewerCanvas
  drawTool="stamp-circle"
  stampOptions={{ circleAreaMm2: 0.2 }}
/>
// Before (메인 스레드 클립)
<WsiViewerCanvas clipPointsToRois clipMode="sync" />

// After (권장 기본값)
<WsiViewerCanvas clipPointsToRois clipMode="worker" />

6. 릴리스 게이트(고정)

배포 전 아래 명령을 로컬과 CI에서 동일하게 통과해야 합니다.

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

CI 워크플로우: .github/workflows/release-gate.yml
publish 훅: prepublishOnly에서 release:gate를 선행 실행합니다.

Open Plant WSI Docs •