시맨틱 버저닝(SemVer) — 버전 번호 x.y.z가 뜻하는 것

핵심 요약

시맨틱 버저닝(SemVer)은 버전 번호에 의미를 부여하는 규칙이다. MAJOR.MINOR.PATCH 형식으로, "이 업데이트가 내 코드를 깨뜨리는가"를 번호만 보고 판단할 수 있게 한다. 의존성 관리(npm 등)의 ^·~ 범위도 이 규칙 위에서 동작한다.

1. 세 자리의 의미

MINOR·PATCH가 오르면 "그냥 올려도 안전"하고, MAJOR가 오르면 "코드 수정이 필요할 수 있다"는 신호다.

2. npm 범위 기호

"react": "^18.2.0"   // 18.x.x 허용 (MAJOR 고정) → 18.9.9까지 OK, 19는 X
"react": "~18.2.0"   // 18.2.x 허용 (MINOR 고정) → 18.2.9까지 OK
"react": "18.2.0"    // 정확히 이 버전만

• ^(캐럿) — MAJOR만 고정. 기능 추가·버그 수정은 자동으로 받음(가장 흔함)
• ~(틸드) — MINOR까지 고정. 버그 수정만 받음(보수적)

3. 0.x의 특별한 의미

버전이 0으로 시작하면(0.y.z) "초기 개발 중, 아무 때나 깨질 수 있음"을 뜻한다. SemVer 규칙상 0.x에선 MINOR 변경도 깨질 수 있으므로, ^0.2.7은 사실상 0.2.x만 허용한다. 1.0.0이 되어야 "안정 API 약속"이다.

4. 실무 팁

• 라이브러리를 배포한다면 깨는 변경엔 반드시 MAJOR를 올려라 — 사용자 신뢰의 핵심
• lock 파일(package-lock.json 등)로 실제 설치 버전을 고정해 재현성을 확보
• 사전 릴리스는 1.0.0-beta.1, 빌드 메타는 +build.5

자주 묻는 질문

^와 ~ 중 뭘 써야 하나요?

대부분 ^가 기본입니다(버그 수정·기능 추가를 자동으로 받되 깨는 변경은 막음). 매우 보수적으로 버그 수정만 받고 싶으면 ~를 쓰세요. 어느 쪽이든 lock 파일로 실제 버전을 고정하는 게 중요합니다.

0.x 버전 라이브러리는 위험한가요?

API가 안정화 전이라 마이너 업데이트에도 깨질 수 있음을 의미합니다. 쓸 수는 있지만 버전을 좁게 고정하고 업데이트 시 체인지로그를 확인하세요. 1.0.0부터 SemVer의 하위호환 약속이 적용됩니다.

버전만 보고 깨지는지 100% 아나요?

규칙을 잘 지킨 라이브러리라면 MAJOR 여부로 판단할 수 있지만, 모두가 완벽히 지키진 않습니다. 그래서 실제 업데이트 시엔 체인지로그·릴리스 노트를 확인하고 테스트로 검증하는 게 안전합니다.