시맨틱 버저닝 — 버전 숫자가 말하는 호환성 — 실습 Lab

INCIDENT RESPONSE

0 / 5 단계 완료

📚 PREREQUISITES

Theorysw-engineering/semantic-versioning

TRACK

SW-ENGINEERING

SLA

45분

LEVEL

중급

PHASES

3단계

ENV

local

INCOMING TICKET

“플랫폼 팀장: "우리 내부 공용 라이브러리를 올릴 때마다 소비 팀들이 빌드가 깨져요. 어떤 건 버그픽스인데 major를 올려서 다들 겁먹고, 어떤 건 호환을 깨면서 patch만 올려서 자동 업데이트로 조용히 프로덕션이 터집니다. 버전 숫자가 호환성을 제대로 말하도록 규칙을 잡아주세요 — 어떤 변경에 어느 자리를 올리고, 소비자는 어떤 범위로 물고, 배포 때 태그·체인지로그를 어떻게 맞추는지까지요."”

YOUR ROLE

공용 라이브러리·API의 버저닝 규칙을 정하는 플랫폼/백엔드 담당

안 하면 나중에

버전이 호환성을 신뢰성 있게 말하지 않으면, 소비자는 매 업그레이드를 도박처럼 하게 되고, 자동 업데이트가 breaking change를 조용히 끌고 들어와 프로덕션을 깬다. 태그·체인지로그가 버전과 어긋나면 "무엇이 왜 바뀌었는지"를 아무도 재현하지 못한다.

📋상황 브리핑

플랫폼 팀장이 말합니다.

"사내 공용 결제 SDK를 여러 팀이 물고 씁니다. 그런데 릴리스할 때마다 소비 팀들이 빌드가 깨져요. 지난주엔 응답 필드 하나를 지우면서 patch만 올렸더니, 캐럿 범위로 자동 업데이트를 받던 팀 셋이 새벽에 프로덕션이 터졌습니다. 반대로 오타 하나 고치면서 major를 올린 릴리스는, 다들 마이그레이션 겁나서 몇 주째 안 올리고 있고요. 우리는 버전 숫자만 봐도 '내 코드를 고쳐야 하나'를 알 수 있게 하고 싶어요. 어떤 변경에 어느 자리를 올릴지, 소비자는 어떤 범위로 물지, 배포할 때 태그랑 체인지로그를 어떻게 맞출지 규칙으로 정해 주세요."

시맨틱 버저닝은 "숫자를 몇으로 할까"가 아니라 "이 버전이 소비자에게 무엇을 약속하는가"의 문제다. MAJOR는 "고쳐야 한다", MINOR는 "새 게 생겼지만 안 고쳐도 된다", PATCH는 "조용히 나아졌다"는 신호다. 이 Lab은 변경을 호환성으로 분류하고, 그 약속을 범위·lockfile·태그·체인지로그로 끝까지 관철한다.

⏱ 45분📊 중급🔧 3단계#versioning#semver#compatibility#dependency

MISSION

변경을 호환성으로 분류 — MAJOR / MINOR / PATCH

실제 변경 목록을 호환 깨짐(MAJOR)·기능 추가(MINOR)·버그 수정(PATCH)으로 분류하고, "호환이 깨지는가"를 판정하는 기준을 세운다.

의존성 범위 + lockfile — 약속을 어디까지 믿고, 무엇으로 잠그나

핵심 의존성에 캐럿/틸드/고정 중 어떤 범위를 쓸지 근거로 정하고, lockfile로 실제 설치 버전을 잠가 로컬·CI·프로덕션의 재현성을 확보한다.

배포 · 태그 · 체인지로그 연결 + 0.x 프리릴리스 규칙

버전 = git 태그 = 릴리스 노트 = 체인지로그를 하나로 맞추고, 0.x와 프리릴리스(-rc 등)의 규칙을 정해 "무엇이 왜 바뀌었는지"가 재현 가능하게 한다.

📌 선수 지식

• [이론] sw-engineering/semantic-versioning

ℹ️ 실습 환경

환경: local

🔒

실습 실행은 Pro 플랜 전용입니다

인시던트 브리프와 학습 자료는 지금 바로 확인할 수 있습니다. 실제 실습 진행 및 터미널 사용은 Pro 플랜에서 가능합니다.

Pro로 업그레이드 →

>_ LAB TERMINAL↔ 너비 조절

NOTES