시맨틱 버저닝(Semantic Versioning)

시맨틱 버저닝(Semantic Versioning)이란?

소프트웨어의 버전 번호에 명확한 의미를 부여해 관리하는 규칙이다.

이 방식은 소프트웨어를 사용하는 개발자와 사용자 모두가 버전 번호만 보고 어떤 변화가 있었는지 파악할 수 있도록 고안되었다.

---

버전 표기 방식

시맨틱 버저닝은 Major.Minor.Patch 형식의 세 자리 숫자로 버전을 관리한다.

각 숫자는 점(.)으로 구분되며, 각각 다음과 같은 의미를 가진다.

• Major (주버전): 하위 호환성이 깨지는 변경이 있을 때 올린다.
• Minor (부버전): 하위 호환성을 유지하면서 새로운 기능이 추가될 때 올린다.
• Patch (패치버전): 하위 호환성을 유지하면서 버그 수정이나 작은 개선이 있을 때 올린다.

ex) 버전이 2.9.1 이라면,

• 2: Major 버전
• 9: Minor 버전
• 1: Patch 버전

---

버전 증가 규칙

변경 사항에 따라 버전 번호를 올리는 규칙은 다음과 같다.

• Major 버전 증가: 기존 API와 호환되지 않는 변경(함수 이름 변경, 파라미터 삭제 등)이 있을 때
• Minor 버전 증가: 기존 API와 호환되면서 새로운 기능이 추가될 때(새로운 함수 추가 등)
• Patch 버전 증가: 기존 API와 호환되면서 버그 수정, 성능 개선 등 사소한 변경이 있을 때

💡 Major 나 Minor 버전이 올라갈 때 오른쪽 숫자는 0으로 초기화된다.

• Major 버전 증가

  • 2.9.1 ➔ 3.0.0

• Minor 버전 증가

  • 1.2.3 ➔ 1.3.0

사전 릴리즈와 메타데이터

정식 출시 전의 베타, 알파 등은 버전 뒤에 하이픈(-), 점(.)을 붙여서 표기한다.

빌드 메타데이터는 플러스(+) 붙여서 표기한다.

• 베타, 알파
  • 1.0.0-beta.1
  • 1.0.0-alpha.1
• 빌드 메타데이터
  • 1.0.0+2025020944700

초기 개발(0.y.z) 버전

Major 버전이 0인 경우(ex. 0.1.1)는 아직 정식 릴리즈 전이며, 이 때는 하위 호환성이 보장되지 않을 수 있다.

즉 0.1.0 에서 0.2.0 으로 변경될 때도 큰 변화가 있을 수 있다.

---

시맨틱 버저닝의 장점

• 예측 가능성: 버전 번호만 보고 어떤 변화가 있었는지 예측 할 수 있다.

• 의존성 관리: 패키지 관리 도구에서 의존성 충돌을 줄이고, 안전하게 업데이트할 수 있다.

• 커뮤니케이션: 개발자 간에 변경 사항의 크기와 위험성을 명확하게 전달할 수 있다.

---

버전 관리 기호

시맨틱 버저닝을 기반으로 패키지 관리 도구에서는 버전 앞에 캐럿(^),틸드(~)같은 특수 기호를 붙여 의존성 업데이트의 허용 범위를 지정한다.

이 기호들은 하위 호환성을 보장하는 선에서 자동으로 업데이트할 수 있는 버전의 범위을 정해준다.

캐럿(^)

• 형식: ^1.2.3
• 의미: Major 버전이 바뀌지 않는 범위 내에서 Minor , Patch 버전 업데이트를 허용한다.
  • 즉 1.x.x 버전 내에서 최신 버전까지 자동 업데이트가 가능하다.

틸드(~)

• 형식: ~1.2.3
• 의미: Minor 버전이 바뀌지 않는 범위 내에서 Patch 버전 업데이트만 허용한다.
  • 즉 1.2.x 버전 내에서 최신 버전까지 자동 업데이트가 가능하다.

---

정리하기

시맨틱 버저닝은 소프트웨어 버전을 Major.Minor.Patch 형식으로 관리해, 버전 번호만 보고 하위 호환성, 새로운 기능 추가, 버그 수정 여부를 쉽게 알 수 있도록 하는 규칙이다.

이를 통해 개발자와 사용자는 변경 사항을 예측하고 안전하게 의존성을 관리할 수 있다.

이외의 시맨틱 버저닝 관련 FAQ는 위 링크에서 확인할 수 있다.

참고 자료

https://semver.org/lang/ko/