03 · Versioning

버전 · 변경이력

ADMap 은 세 버전 축이 독립적으로 움직인다 — API 표면 · SDK 패키지 · 데이터 스냅샷. 문서는 SDK major 에 고정되고, 기능 업데이트는 changeset 이 버전 · 변경이력 · 마이그레이션 노트로 전파한다.

SDK 연동 API 레퍼런스

세 버전 축 — 독립

API 표면

URL 경로 /api/v1/*. breaking 변경 시에만 v2 를 신설하고 v1 은 하위호환으로 유지 — 기존 컨슈머 무중단.

SDK 패키지

1.2.0

react · map-sdk · @admap/api 는 fixed lockstep — 항상 같은 버전으로 동시 bump. changeset 으로 semver 관리.

데이터 · 스타일

?version=vN

style.json 은 불변(immutable) 핀. 미지정 시 latest 체인을 따른다. 재현성이 필요한 컨슈머만 vN 을 고정한다.

앱 릴리즈 자체는 GET /api/health/version({ version, releasedAt })으로 확인한다 — 컨슈머 호환 체크용이며 SDK semver 와 별개 축이다.

문서 버전 핀

이 가이드는 SDK major(1.x) 에 고정된다. 1.0.0 이 첫 정식(GA), 1.2.0 이 현재 릴리즈다 — 상단 v1.2.0 ▾ 셀렉터는 1.x major 라인을 가리키고(minor 는 같은 문서 안에서 갱신), 이후 새 major 릴리즈 시 이전 문서가 읽기 전용 아카이브로 추가돼 오래된 링크가 깨지지 않는다.

v1.2.0 — 현재 (current) · 논리 레이어 opacity/filter/visibility family + feature-click logicalLayerId
v1.1.0 — buildStyleUrl origin 보존 + style X-API-Key 규약(ADM-150)
v1.0.0 — 첫 정식(GA) baseline
이전 내부 반복(구 5.x~7.x)은 GA 전 pre-release 라 1.0.0 에서 버전을 리셋했다.

코드 예제의 @1.2.0 핀은 현재 SDK 버전과 일치한다 — v1 문서의 모든 pnpm add …@1.2.0 은 그 문서가 설명하는 SDK 버전을 정확히 가리킨다. minor(1.x) 는 additive 라 같은 major 문서 안에서 갱신된다.

변경 이력 — changeset 기반

릴리즈마다 changeset(Added / Changed / Removed)이 CHANGELOG + 문서 재생성을 트리거한다. semver 영향은 additive = minor, breaking = major 다.

1.2.0minor현재

ADDAdded — 논리 레이어 opacity multiplier. AdMap#setLayerOpacity(id, opacity) / React useLayerOpacity — 파생(__casing/__cluster/__3d) 일괄, 테두리·텍스트 제외.
CHGChanged — logical layer family. setLayerVisibility 가 companion 까지 함께 토글하고, feature-click 에 logicalLayerId 추가.
CHGChanged — setFilter 가 family 전체에 적용(authored baseline 보존 + AND 합성, non-stacking, null=복원).

1.1.0minor이전

CHGChanged — buildStyleUrl 이 절대 baseUrl 의 origin 을 보존한 완전 URL 반환(상대 기본값은 path+search 유지, 하위호환).
CHGChanged — style 요청은 apiKey 지정 시 URL host 매칭과 무관하게 항상 X-API-Key 부착(ADM-150).

1.0.0major첫 정식(GA)

ADDAdded — SDK 클라이언트 축 로깅. X-Admap-Client(react / map-sdk) 자동 주입으로 사용량 리포팅을 SDK ↔ 직접 API 로 분리(X-API-Key 인증 무변경).
ADDAdded — 컨슈머 셀프서브 레이어 write. useConsumerLayers / ApiClient CRUD(api-key 소유 격리).
ADDAdded — 발행 카탈로그 read + 지도 임베드(AdMap / <ADMap>) + read 훅.
CHGBaseline — taxonomy segments 트리 · category polygon_poi/point_poi · 3D 는 style layer metadata['admap:extrude'] 플래그로 표현.

1.0.0 은 버전 리셋 후 첫 정식 릴리즈다. GA 이전 내부 반복(구 5.x~7.x)에서 통합검색 · 공간분석 · routing · Impact/three.js 오버레이 표면이 정리됐고, 그 결과가 1.0.0 baseline 이다(제거 표면 상세는 SDK 연동 참조). 이후 릴리즈는 changeset(Added / Changed / Removed, additive = minor · breaking = major)으로 관리한다.

기능 업데이트 → 버전 전파 흐름

기능 PR 하나가 어떻게 버전 · 문서 · 마이그 노트로 퍼지는지의 순서다.

STEP 01

changeset

기능 PR 에 Added / Changed / Removed + semver 영향을 기록한다.

.changeset/*.md

STEP 02

lockstep bump

react · map-sdk · @admap/api 를 같은 버전으로 동시 bump 한다.

fixed versioning

STEP 03

release

main push 시 release 워크플로가 발행 + 태그한다.

release.yml

STEP 04

docs + 마이그

CHANGELOG 갱신 · 가이드 재생성, major 면 마이그레이션 노트를 동반한다.

/guide · CHANGELOG

major(breaking) 릴리즈만 마이그레이션 노트를 동반한다 — 제거 · 시그니처 변경 표면을 "걷어낼 참조" 목록으로 명시한다(SDK 연동의 1.0.0 마이그레이션 절이 그 예).