[SemVer] 시맨틱 버저닝, 소프트웨어 버전 관리

semantic versioning

Posted Aug 12, 2025

By Kuandyk

6 min read

소프트웨어 개발에서 여러 프로그램이 서로 연결되어 작동하는 의존성은 복잡한 문제들을 만들기도 한다.
이를 의존성 지옥이라고 부르기도 하는데 이런 문제 때문에 개발자들이 어려움을 겪는다.

이러한 문제를 해결하기 위해 등장한 것이 바로 시맨틱 버저닝(Semantic Versioning, SemVer)이다.

SemVer는 버전 번호를 통해 소프트웨어 변경 사항을 명확하게 전달하는 표준화된 시스템이다.

1. 시맨틱 버저닝이란?

SemVer는 MAJOR.MINOR.PATCH (X.Y.Z) 형식의 버전 번호를 사용한다.
여기서 X, Y, Z는 음수가 아닌 정수이며 앞에 0이 붙지 않는다.

이 형식은 버전 번호를 컴퓨터가 쉽게 인식할 수 있게 하여 자동으로 의존성을 관리하는 데 도움을 준다.

SemVer의 핵심은 프로그램의 공개 API 변경에 따라 버전 번호 각 부분을 올리는 규칙에 있다.

MAJOR (X)
- API가 크게 변경되어 기존 방식이 작동하지 않을 때
- MINOR와 PATCH는 0으로 재설정
- 예: 1.x.x → 2.0.0
MINOR (Y)
- 기존 기능과 호환되는 새로운 기능 추가
- 기존 기능을 deprecated 처리할 때도 포함
- PATCH는 0으로 재설정
- 예: 1.1.x → 1.2.0
PATCH (Z)
- 기존 기능과 호환되는 버그 수정
- 예: 1.1.1 → 1.1.2

버전 증분 규칙 표:

버전 요소	올리는 시점	API 영향	하위 버전 재설정 여부	예시
MAJOR (X)	호환 불가 변경	기존 API 사용 불가	MINOR, PATCH 0으로 재설정	1.2.3 → 2.0.0
MINOR (Y)	새로운 기능 추가	기존 API와 호환	PATCH만 0으로 재설정	1.2.3 → 1.3.0
PATCH (Z)	버그 수정	기존 API와 호환	없음	1.2.3 → 1.2.4

초기 개발 (0.y.z): 언제든 변경 가능, 안정적이지 않음
안정적 시작 (1.0.0): API가 완성되고 안정적 사용 가능
릴리스 불변성: 한번 공개된 버전은 수정 불가, 변경 시 새로운 버전 부여
사전 릴리스 & 빌드 메타데이터
- 1.0.0-alpha: 정식 전 불안정 버전
- 1.0.0+build.123: 빌드 정보 포함

버전 우선순위는 MAJOR → MINOR → PATCH 순으로 숫자를 비교하여 결정한다. 사전 릴리스 버전은 일반 버전보다 우선순위가 낮다. 패키지 관리자가 올바른 버전을 선택하는 데 필수적인 규칙이다.

Git 태그로 릴리스 버전 관리 (예: git tag v0.2.0). Conventional Commits, semantic-release 사용 (버전 자동 증가 + changelog 생성). README에 버전 관리 방식을 명확히 기록

시맨틱 버저닝은 소프트웨어 버전 관리를 위한 강력하고 예측 가능한 틀을 제공한다. 명확한 의사소통, 효율적인 의존성 관리, 책임 있는 개발을 가능하게 하여 소프트웨어 생태계의 건강과 안정성에 기여한다.

모든 프로젝트에서 SemVer를 채택하는 것은 더 나은 개발 관행과 신뢰할 수 있는 소프트웨어 구축의 중요한 약속이다.

This post is licensed under CC BY 4.0 by the author.