Semantic Versioning이란?
프로젝트를 진행하다 보면 라이브러리 버전이 1.2.3, 2.0.0처럼 세 개의 숫자로 표시된 것을 자주 보게 됩니다. 이 규칙을 ‘Semantic Versioning(유의적 버전, 줄여서 SemVer)’이라고 부릅니다. 버전 번호를 아무렇게나 올리는 것이 아니라, 그 변화가 어떤 의미를 가지는지 숫자 자체에 담아내는 약속입니다. 형식은 ‘MAJOR.MINOR.PATCH’이며, 각 자리마다 규칙이 정해져 있습니다.
- MAJOR: 기존 코드와 호환되지 않는 큰 변경이 있을 때 올림
- MINOR: 기존 기능은 유지하면서 새로운 기능이 추가될 때 올림
- PATCH: 기존 기능을 그대로 두고 버그만 수정했을 때 올림
예를 들어 어떤 라이브러리가 ‘2.4.1’이라면, 메이저 버전 2에서 새로운 기능이 4번 추가되었고 그 이후 버그 수정이 1번 있었다는 뜻입니다. 이는 마치 아파트 주소 체계와 비슷합니다. 동(MAJOR)이 바뀌면 완전히 다른 건물이고, 호수(MINOR)가 바뀌면 같은 동 안에서 방이 늘어난 것이며, 층(PATCH)만 바뀌면 같은 집 안에서 수리만 한 것과 같습니다.
실무에서 왜 중요한가
SemVer가 중요한 이유는 협업과 자동화 때문입니다. 여러 개발자가 같은 패키지를 사용할 때, 버전 번호만 보고도 ‘이 업데이트를 적용해도 안전한지’를 판단할 수 있습니다. 예를 들어 package.json에서 ^1.2.3처럼 표기하면 ‘1.x.x 범위 내에서는 자동으로 업데이트해도 된다’는 뜻이 됩니다. 이는 MINOR와 PATCH 변경은 하위 호환성을 지킨다는 SemVer의 약속을 신뢰하기 때문에 가능한 일입니다.
반대로 MAJOR 버전이 올라간다는 것은 ‘기존 코드가 깨질 수 있으니 마이그레이션 가이드를 확인하라’는 신호입니다. 실제로 React나 Vue 같은 프레임워크도 메이저 버전이 바뀔 때마다 마이그레이션 문서를 함께 제공합니다. 만약 이런 규칙 없이 버전을 관리한다면, 개발자는 매번 업데이트할 때마다 코드를 전부 검토해야 하는 비효율이 생깁니다.
정리
Semantic Versioning은 단순한 숫자 나열이 아니라 ‘이 버전을 올리면 무슨 일이 생기는지’를 미리 알려주는 약속입니다. MAJOR는 호환성 파괴, MINOR는 기능 추가, PATCH는 버그 수정이라는 규칙만 기억해도 오픈소스 생태계에서 의존성을 훨씬 안전하게 관리할 수 있습니다.