SemVer 계산기 — 무료 온라인 도구

시맨틱 버전 관리란?

시맨틱 버전 관리(SemVer)는 세 자리 숫자 형식인 MAJOR.MINOR.PATCH(예: 2.4.1)를 사용하는 버전 관리 명세입니다. 각 릴리스의 변경 사항을 표준화된 방식으로 전달하여, 개발자가 의존성을 업데이트할 때 어떤 영향이 있는지 이해할 수 있도록 합니다.

SemVer 명세(semver.org)는 명확한 규칙을 정의합니다: 호환성 파괴 변경 시 MAJOR 증가, 하위 호환되는 새 기능 추가 시 MINOR 증가, 하위 호환되는 버그 수정 시 PATCH 증가.

각 버전 파트를 올려야 하는 시점

• MAJOR (호환성 파괴 변경): 공개 API 메서드 제거, 함수 시그니처 변경, 이전 동작의 폐기 및 제거, 인증 흐름 변경.
• MINOR (새 기능): 새 엔드포인트 추가, 기존 함수에 선택적 매개변수 추가, 새 설정 옵션 추가.
• PATCH (버그 수정): 크래시 수정, 잘못된 동작 수정, API 변경 없는 성능 개선, 문서 수정.

npm 버전 범위 구문

• ^1.2.3 — 1.2.3과 호환. MINOR 및 PATCH 업데이트 허용 (>=1.2.3 <2.0.0)
• ~1.2.3 — 대략적으로 동등. PATCH 업데이트만 허용 (>=1.2.3 <1.3.0)
• >=1.2.3 <2.0.0 — 명시적 범위, 의도가 매우 명확
• 1.x — Major 버전 1의 모든 버전
• * — 모든 버전 (프로덕션에 위험)
• 1.2.3 — 정확한 버전만 (업데이트 없음)

실전 시맨틱 버저닝: 이론을 넘어서

시맨틱 버저닝(SemVer)은 각 릴리스에서 어떤 변경을 예상할 수 있는지에 대해 라이브러리 작성자와 소비자 간의 명확한 계약을 제공합니다. 그러나 실제 버저닝 결정은 단순한 MAJOR.MINOR.PATCH 공식이 제시하는 것보다 더 미묘한 경우가 많습니다.

각 버전 번호를 올려야 할 때

• MAJOR (호환성 깨지는 변경): 공개 API 제거, 함수 시그니처 변경, 내보내기 모듈 이름 변경, 런타임 버전 지원 중단(Node.js 16 → 18 최소 요구), 기존 사용자가 의존하는 기본 동작 변경.
• MINOR (새 기능, 하위 호환): 새 함수, 엔드포인트, 옵션 추가. 기존 함수에 선택적 매개변수 추가. 기존 API 사용 중단(제거가 아닌). 새 이벤트 타입이나 열거형 값 추가.
• PATCH (버그 수정만): 잘못된 동작 수정, 보안 패치, API를 변경하지 않는 성능 개선, 문서 수정, 공개 API에 영향을 주지 않는 의존성 업데이트.

package.json의 버전 범위 전략

• ^1.2.3 (캐럿 — npm 기본값): MINOR와 PATCH 업데이트 허용: ≥1.2.3 <2.0.0. 대부분의 의존성에 최적 — 라이브러리가 SemVer를 올바르게 따른다고 신뢰합니다.
• ~1.2.3 (틸드): PATCH 업데이트만 허용: ≥1.2.3 <1.3.0. 더 보수적 — 마이너 버전에서 호환성이 깨진 이력이 있는 의존성에 사용합니다.
• 1.2.3 (정확): 이 버전으로 정확히 잠금. 가장 보수적 — 변경이 위험한 중요한 의존성(데이터베이스 드라이버, 인증 라이브러리)에 사용합니다.

프리릴리스 버전과 빌드 메타데이터

SemVer는 프리릴리스 식별자(1.0.0-alpha.1, 2.0.0-beta.3, 1.0.0-rc.1)를 지원합니다. 프리릴리스 버전은 릴리스 버전보다 낮은 우선순위를 가집니다: 1.0.0-alpha < 1.0.0. 빌드 메타데이터(1.0.0+20260314)는 버전 우선순위 비교에서 무시되지만 빌드 정보 추적에 유용합니다.

시맨틱 버전 관리에 대한 자주 묻는 질문

npm에서 ^1.0.0과 ~1.0.0의 차이점은 무엇입니까?

캐럿(^)은 동일한 Major 버전 내에서 호환되는 업데이트를 허용합니다. ^1.0.0은 >=1.0.0이고 <2.0.0인 모든 버전을 허용하며 Minor 및 Patch 업데이트가 가능합니다. 틸드(~)는 더 제한적입니다. ~1.0.0은 Patch 업데이트만 허용하며 >=1.0.0이고 <1.1.0인 버전만 일치합니다. npm은 기본적으로 캐럿(^)을 사용합니다. 설치되는 버전을 더 엄격하게 제어해야 할 때 틸드를 사용하십시오.

Major 버전 번호를 올려야 하는 시점은 언제입니까?

이전 버전과 호환되지 않는 호환성 파괴 변경이 있을 때만 Major를 올리십시오(예: 1.x.x → 2.0.0). 여기에는 공개 API 메서드의 제거 또는 이름 변경, 함수의 매개변수 시그니처 변경, 이전에 지원하던 런타임 또는 환경의 지원 중단, 기존 통합을 깨뜨리는 기본 동작 변경이 포함됩니다. 호환성 파괴 없는 추가 기능은 항상 Minor, 버그 수정은 항상 Patch로 관리합니다.

0으로 시작하는 버전 번호는 무엇을 의미합니까?

0으로 시작하는 버전(예: 0.x.x)은 소프트웨어가 초기 개발 중이며 공개 API가 아직 안정적이지 않음을 나타냅니다. SemVer 규정에 따르면 0.x 개발 중에는 Minor 버전 범프(0.1.0 → 0.2.0)에서도 호환성 파괴 변경이 발생할 수 있습니다. 안정적이고 문서화된 공개 API에 대한 하위 호환성을 유지할 준비가 되었을 때만 1.0.0으로 올리십시오.

SemVer를 사용하여 프리릴리스 버전을 배포하는 방법은?

하이픈 뒤에 프리릴리스 식별자를 추가합니다: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. 프리릴리스 버전은 정식 릴리스보다 낮은 우선순위를 가집니다: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. npm에서는 npm publish --tag next로 배포하여 기본 설치에 포함되지 않도록 합니다. 캐럿과 틸드 범위 선택자는 프리릴리스 버전을 자동으로 매칭하지 않습니다.

관련 개발자 도구

• Git 명령어 찾기 — 태깅, 브랜치, 릴리스를 위한 정확한 Git 명령어 검색
• Docker Compose 생성기 — 프로덕션 수준의 docker-compose.yml 설정 생성
• .ENV 파일 검사기 — 환경 파일 검증 및 노출된 시크릿 탐지
• JWT 디코더 및 검사기 — JWT 토큰을 디코딩하고 클레임을 브라우저에서 안전하게 검사
• 모든 무료 개발자 도구 보기