Choosing a Versioning Scheme: SemVer and CalVer
TOC
Overview
버전 번호를 정하기 전에 프로젝트가 사용자에게 어떤 정보를 전달해야 하는지 정해야 한다.
이 글에서는 SemVer와 CalVer를 비교하고, 프로젝트에 맞는 버전 체계를 선택할 때 고려할 항목을 정리한다.
버전 체계가 표현해야 하는 것
버전 체계를 선택할 때 다음 항목을 확인한다.
- 변경 시점을 알 수 있는가
- 호환성 변화를 표현할 수 있는가
- 릴리스를 쉽게 식별할 수 있는가
- 다음 버전의 의미를 예측할 수 있는가
버전 번호만 정하고 변경 기준을 문서화하지 않으면 같은 번호 체계도 프로젝트마다 다르게 해석된다.
SemVer
SemVer란?
Semantic Versioning의 약자다.Semantic은 각 숫자에 의미를 부여한다는 뜻이며, 공개 인터페이스의 호환성 변화를 버전에 반영한다.
MAJOR.MINOR.PATCH
MAJOR: 호환되지 않는 변경MINOR: 하위 호환 가능한 기능 추가PATCH: 하위 호환 가능한 버그 수정
공개 API를 제공하는 라이브러리, 패키지, CLI, 서비스 계약 등에 적용할 수 있다. 0.x, pre-release, 실제 변경의 버전 판정 기준은 별도로 정의해야 한다.
CalVer
CalVer란?
Calendar Versioning의 약자다.Calendar는 달력을 의미하며, 릴리스 연도나 월처럼 배포 시점을 버전에 포함하는 방식이다.
2025.12
2025.12.1
위 형식은 예시이며 구체적인 표기 형식은 프로젝트마다 다를 수 있다. 릴리스 날짜나 주기를 사용자에게 바로 전달할 수 있어 정기적으로 릴리스하는 배포판이나 제품에서 사용할 수 있다.
날짜만으로는 호환성 변화를 알 수 없다. 호환성 정보가 필요하면 별도의 정책이나 API 버전을 함께 제공해야 한다.
프로젝트에 맞는 방식 선택하기
| 상황 | 고려할 방식 | |—|—| | 외부 API와 라이브러리 호환성이 중요함 | SemVer | | 릴리스 시점과 주기가 중요함 | CalVer | | 여러 구성요소가 독립적으로 배포됨 | 구성요소별 규칙 | | 이미 사용하는 규칙이 있음 | 기존 규칙을 문서화하고 유지 |
방식을 선택한 뒤에는 버전 변경 기준, pre-release 표기, 지원 기간, 폐기 정책을 문서로 남긴다.
Git tag와 배포 정보 연결하기
버전 체계와 Git tag는 다음처럼 연결할 수 있다.
Version
→ Git tag
→ Commit
→ Build
→ Artifact
버전 번호나 tag는 사람이 읽는 릴리스 식별자다. commit hash와 artifact 식별자는 실제 소스와 배포 결과물을 추적하기 위해 사용한다.
정리
SemVer와 CalVer 중 항상 정답인 방식은 없다. 프로젝트가 사용자에게 전달해야 하는 정보와 릴리스 방식을 기준으로 선택해야 한다.
다음 글에서는 SemVer를 선택했을 때 MAJOR, MINOR, PATCH를 실제 변경에 적용하는 기준을 다룬다.