85 lines
8.4 KiB
Markdown
85 lines
8.4 KiB
Markdown
---
|
||
title: "Semantic Versioning 2.0.0 — Official Specification (semver.org)"
|
||
source_type: official-doc
|
||
url: https://semver.org/spec/v2.0.0.html
|
||
archive_url:
|
||
related_branches: [feature-build-release-supply-chain-contract]
|
||
related_projects: [ca-skeleton]
|
||
vendor: "semver.org (Tom Preston-Werner)"
|
||
tags: [official-doc, ca-skeleton, ci-cd, build-tooling, semver, artifact-versioning]
|
||
created: 2026-06-15
|
||
---
|
||
|
||
# Semantic Versioning 2.0.0 — Official Specification (semver.org)
|
||
|
||
> Layer: `raw/official-docs/` — 외부 공식 표준 원문 발췌. 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.
|
||
|
||
## Parent / 활용 branch
|
||
|
||
| Branch | 이 자료가 정당화하는 결정 |
|
||
|---|---|
|
||
| [[raw/branch-notes/feature-build-release-supply-chain-contract]] | D9 — artifact version = SemVer + git sha suffix (1.2.3+a1b2c3d): build metadata(`+` suffix)는 precedence에서 무시되므로, sha를 `+` 뒤에 붙이면 동일 MAJOR.MINOR.PATCH 버전들 간 비교 순서를 깨지 않음 |
|
||
|
||
## 출처 / Source
|
||
|
||
- 원본 URL: https://semver.org/spec/v2.0.0.html
|
||
- 아카이브 URL: (미등록)
|
||
- 저자 / 조직: Tom Preston-Werner (semver.org)
|
||
- 발행일: 2013 (v2.0.0 확정)
|
||
- 마지막 확인일: 2026-06-15
|
||
|
||
## 왜 저장했는지 / Why archived
|
||
|
||
ca-skeleton build/release 계약(feature-build-release-supply-chain-contract)의 D9 결정 — `artifact version = SemVer + git sha suffix (1.2.3+a1b2c3d)` — 이 공식 spec 근거 없이 `UNSUPPORTED_DECISION`으로 남아 있었다. SemVer 2.0.0 spec §10(build metadata)이 `+` prefix를 precedence에서 무시하도록 명확히 규정하므로, sha를 build metadata로 붙이는 방식이 semver 의미 체계와 충돌하지 않음을 직접 증명한다.
|
||
|
||
## 핵심 인용 / Key quotes (verbatim)
|
||
|
||
> [§Summary] "MAJOR version when you make incompatible API changes"
|
||
> [§Summary] "MINOR version when you add functionality in a backward compatible manner"
|
||
> [§Summary] "PATCH version when you make backward compatible bug fixes"
|
||
(line 266–271, fetched text)
|
||
|
||
> [§Spec item 9] "A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version."
|
||
(line 385–390, fetched text)
|
||
|
||
> [§Spec item 10] "Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence."
|
||
(line 400–406, fetched text)
|
||
|
||
> [§Spec item 11] "Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence)."
|
||
(line 418–420, fetched text)
|
||
|
||
## Claims Extracted / 추출된 주장
|
||
|
||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||
|---|---|---|---|---|---|
|
||
| SEMVER-C1 | MAJOR.MINOR.PATCH 각 숫자는 파괴적 변경 / 호환 기능 추가 / 호환 버그 수정 순으로 증가해야 한다 | [§Summary] "MAJOR version when you make incompatible API changes" / "MINOR version when you add functionality in a backward compatible manner" / "PATCH version when you make backward compatible bug fixes" | `official-standard` | public API를 선언한 모든 SemVer 준수 소프트웨어 | 내부 구현 변경이 API에 미치는 영향을 자동으로 분류해주지 않는다; 무엇이 "breaking"인지는 별도 정책 필요 |
|
||
| SEMVER-C2 | pre-release 버전은 `-` hyphen suffix로 표기하며, 연관된 normal version보다 낮은 precedence를 가진다 | [§Spec item 9] "A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. [...] Pre-release versions have a lower precedence than the associated normal version." | `official-standard` | 1.2.3-alpha, 1.2.3-rc.1 등 pre-release 식별 | `-` suffix가 있는 버전이 자동으로 CI에서 제외되도록 보장하지 않음; tooling 별도 설정 필요 |
|
||
| SEMVER-C3 | build metadata는 `+` plus sign suffix로 표기하며, version precedence 결정 시 **완전히 무시된다** | [§Spec item 10] "Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. [...] Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence." | `official-standard` | 1.2.3+a1b2c3d, 1.0.0-beta+exp.sha.5114f85 등 build metadata 포함 버전 | 모든 패키지 매니저/레지스트리가 이 규칙을 올바르게 구현한다는 보장은 없다 (도구별 호환성 별도 확인 필요) |
|
||
| SEMVER-C4 | build metadata는 precedence 계산 식에서 제외되며, `+` suffix의 존재는 두 버전을 동일 precedence로 만든다 | [§Spec item 11] "Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence)." | `official-standard` | SemVer 2.0.0 를 준수하는 version comparator | `+sha` suffix가 registry 내 유일성(uniqueness)을 보장하지 않음; 동일 MAJOR.MINOR.PATCH+다른sha 두 버전은 precedence가 같음 |
|
||
| SEMVER-C5 | `-` pre-release suffix와 `+` build metadata suffix는 별도 의미 체계를 가지며, `1.2.3-sha`와 `1.2.3+sha`는 근본적으로 다르다 | [§Spec item 9] (hyphen = pre-release, lower precedence) vs [§Spec item 10] (plus = build metadata, ignored in precedence) | `official-standard` | `1.2.3+sha` 형식으로 build metadata를 붙이는 artifact versioning 패턴 | sha를 `-` suffix로 붙이면 (`1.2.3-sha`) spec상 pre-release로 간주되어 `1.2.3`보다 낮은 precedence를 가짐 — 이는 `1.2.3+sha`와 다른 동작 |
|
||
|
||
## Usage Boundaries / 적용 경계
|
||
|
||
- 이 자료가 직접 증명하는 것:
|
||
- `SEMVER-C3`, `SEMVER-C4`: `1.2.3+a1b2c3d` 형식으로 git sha를 build metadata로 붙이는 것이 SemVer 2.0.0 spec에 부합하며, MAJOR.MINOR.PATCH 비교 결과를 변경하지 않는다.
|
||
- `SEMVER-C5`: sha를 `+` 대신 `-`로 붙이면 pre-release로 처리되어 정식 release보다 낮은 precedence를 가짐 — 두 형식은 다른 결과를 낸다.
|
||
- `SEMVER-C1`: MAJOR/MINOR/PATCH 증가 의미론 (D9 버전 계획의 공식 근거).
|
||
- 이 자료가 증명하지 않는 것:
|
||
- Docker Hub, GitHub Container Registry, Maven Central, Gradle Plugin Portal 등 **구체적 레지스트리**가 `+` build metadata를 포함한 버전 문자열을 수용하는지 여부 (도구별 검증 필요).
|
||
- CalVer 형식이 왜 forbidden인지 — D9의 CalVer 금지는 팀 컨벤션이며 이 spec이 직접 금지하는 것은 아니다.
|
||
- 특정 packaging system(Maven, npm 등)에서 SemVer 2.0.0이 실제로 강제되는지 여부.
|
||
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
||
- Gradle 빌드 스크립트에서 `1.2.3+a1b2c3d` 형식의 version 문자열이 정상 처리되는지 실제 build 검증.
|
||
- GitHub Container Registry / Harbor 등 사용 레지스트리가 `+` 포함 OCI image tag를 허용하는지 확인 (OCI spec과 SemVer spec은 별개).
|
||
|
||
## 메모 / Notes
|
||
|
||
- OCI image tag는 SemVer 2.0.0를 따르는 게 일반적이나, `+` 문자가 일부 레지스트리에서 tag로 허용되지 않을 수 있음 (URL encoding 문제). 실제 ca-skeleton 구현 시 `+` → `-` 치환 또는 `.` 구분 방식으로 변환 여부를 확인할 것 — 이 점은 SEMVER-C3가 아닌 도구 호환성 문제.
|
||
- BNF grammar에서 `<version core> "+" <build>` 가 valid semver임이 명시되어 있음 (spec Backus-Naur Form 섹션).
|
||
|
||
## Related / 관련
|
||
|
||
- [[raw/branch-notes/feature-build-release-supply-chain-contract]] — D9 artifact versioning 결정 (소비 branch)
|
||
- [[raw/official-docs/supply-chain-slsa-provenance-framework]] — SLSA provenance 스키마 (D7/D13 지지)
|
||
- [[raw/official-docs/supply-chain-cosign-keyless-sigstore]] — Cosign keyless signing (D6 지지)
|