Semantic Versioning, SemVer - 소프트웨어 버전 표기 방식

소프트웨어에서 1.2.3과 같이 세 개의 숫자로 버전을 표시하는 방식을 유의적 버전 명세(Semantic Versioning)라고 한다. 일반적으로 줄여서 SemVer라고 부른다.

 

SemVer는 소프트웨어와 라이브러리에서 널리 사용되는 버전 관리 규칙이다. 각 숫자는 왼쪽부터 Major, Minor, Patch를 의미한다.

[ Major ] . [ Minor ] . [ Patch ]
     1           2           3

 

처음에는 단순히 업데이트 횟수에 따라 숫자를 올리는 방식이라고 생각했다. 하지만 SemVer의 핵심은 변경된 코드의 양이 아니라, 이전 버전과의 호환성이 유지되는가에 있다.

각 자리의 의미와 업데이트 기준

첫 번째 자리: Major 버전

Major 버전은 기존 버전과의 하위 호환성이 깨지는 변경이 발생했을 때 올린다.

기존에 제공하던 기능이나 API를 삭제하거나, 같은 기능의 사용 방법과 동작 방식을 크게 변경한 경우가 여기에 해당한다. 사용자가 새 버전으로 업데이트하면서 기존 코드나 설정도 함께 수정해야 한다면 Major 변경으로 볼 수 있다.

1.8.2 → 2.0.0

 

기존 코드가 새 버전에서 정상적으로 작동하지 않을 수 있으므로, 업데이트 전에 변경 사항을 반드시 확인해야 한다.

두 번째 자리: Minor 버전

Minor 버전은 하위 호환성을 유지하면서 새로운 기능을 추가했을 때 올린다.

새로운 함수나 기능이 추가되더라도 기존 기능이 이전과 동일하게 작동한다면 Minor 변경에 해당한다. 내부 구조를 크게 리팩터링했더라도 공개된 사용 방법이나 API에 영향이 없다면 Major 버전이 아니라 Minor 또는 Patch 버전으로 처리할 수 있다.

1.8.2 → 1.9.0

 

새로운 기능이 필요하다면 업데이트할 수 있지만, 기존 버전을 계속 사용하더라도 원래 기능에는 문제가 없다.

세 번째 자리: Patch 버전

Patch 버전은 하위 호환성을 유지하는 버그 수정이나 경미한 개선이 있을 때 올린다.

기존 기능의 오류를 수정하거나 보안 취약점을 해결한 경우가 대표적이다. 새로운 사용 방법을 추가하기보다는 현재 기능을 더 안정적으로 만드는 변경에 가깝다.

1.8.2 → 1.8.3

 

기능 자체는 거의 달라지지 않지만 안정성과 보안이 개선되므로, 특별한 문제가 없다면 업데이트하는 것이 좋다.

0으로 시작하는 버전의 의미

개발을 처음 시작할 때는 최초 버전으로 0.1.0을 사용하는 경우가 많다.

Major 버전이 0인 0.y.z 형식은 소프트웨어가 아직 안정적인 공개 버전에 도달하지 않은 초기 개발 단계임을 나타낸다.

 

이 단계에서는 공개 API나 사용 방법이 빠르게 변경될 수 있다. 따라서 Minor 또는 Patch 버전이 올라가더라도 이전 버전과의 호환성이 항상 보장되는 것은 아니다.

0.1.0 → 0.2.0

 

위와 같은 변경에서도 기존 API가 크게 달라질 수 있으므로, 0.y.z 버전을 사용할 때는 변경 내역을 함께 확인해야 한다.

제품의 공개 API가 안정되고 실제 운영 환경에서 사용할 준비가 되었다고 판단하면 버전을 1.0.0으로 올린다.

정리

SemVer의 기본 규칙은 다음과 같이 정리할 수 있다.

Major: 하위 호환성이 깨지는 변경
Minor: 하위 호환성을 유지하는 기능 추가
Patch: 하위 호환성을 유지하는 버그 수정

 

버전 숫자는 단순한 업데이트 기록이 아니다. 소프트웨어를 사용하는 사람에게 변경의 범위와 위험도를 전달하는 하나의 약속이다.

 

앞으로 코드를 작성하고 배포할 때도 단순히 작업량을 기준으로 버전을 올리는 것이 아니라, 기존 기능과의 호환성이 유지되는지를 먼저 확인해야겠다. 규칙을 알고 나니 이전에는 무심코 지나쳤던 버전 숫자도 소프트웨어의 변경 내용을 설명하는 중요한 정보로 보인다.