시맨틱 버전

시맨틱 버전 지정

1) SemVer 란 무엇이며 왜 필요한가

SemVer는 버전을 아티팩트 (라이브러리, API, 서비스, 스키마) 에 할당하기위한 예측 가능한 규칙을 설정하여 소비자가 업데이트에서 기대할 수있는 것을 이해하도록합니다

메이저-변경 중단

MINOR는 새로운 API 호환 기능입니다.
PATCH-가역 결함 수정.

목표는 계약의 안정성에 동의하고 업그레이드 비용을 줄이는 것입니다.

2) 버전 형식

기본 형식:

'마조 르. 미노르. PATCH [-PRERELEASE] [+ BUILD] '

`1. 4. 7 '은 안정적인 릴리스입니다.
`1. 5. 0-rc. 2 '- 시험판 (릴리스 후보 번호 2).
`2. 0. 0 이상. arm64 '- 메타 데이터 구축 (버전 비교에는 영향을 미치지 않습니다).

비교 규칙:

1. 먼저 'MAJOR' 을 비교 한 다음 'MINOR', 'PATCH' 를 비교합니다.

2. 시험판은 해당 안정 버전 인 '1보다 작습니다. 2. 0-rc. 1 < 1. 2. 0`.

3. 메타 데이터 빌드 ('+...') 는 순서에 영향을 미치지 않습니다: '1. 2. 0+001 == 1. 2. 0`.

3) 변화를 깨는 것으로 간주되는 것

변화 중단-소비자 조치가 필요한 모든 변경:

공개 메소드/엔드 포인트의 서명을 삭제/이름 변경/변경합니다
입력/출력 형식 (JSON 체계, 유형) 을 변경합니다.
오류 계약 (코드/구조) 을 수정합니다.
부작용/SLA 변경 (예: 엄격한 제한 또는 새로운 필수 필드).

파손되지 않음 (올바르게 구현 된 경우): 선택적 필드 추가, 새 값으로 enum 확장 (클라이언트가이를 무시하는 경우), 새 엔드 포인트, 현재 호출에 영향을 미치지 않는 기본값이있는 새 플래그

4) 시험판 및 채널 전략

시험판을 통해 SemVer 약속을 어 기지 않고 테스트 할 수 있습니다

태그: '알파', '베타', 'rc'. 예: '2. 3. 0- 베타. 3`.
채널: 야간 → 알파 → 베타 → rc → 안정적.
정책: 시험판이 기본 생산 어셈블리의 전이 종속성으로 떨어지지 않아야합니다.

5) 버전 범위 및 제약 조건 정확도

실제 생태계는 범위 표현을 사용합니다

5. 1 노드/npm (기본 SemVer)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(MINOR/PATCH 허용, MAJOR 수정).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(MINOR 내에서 PATCH 허용).
`1. 4. x '는 1의 패치입니다. 4.
정확한 핀: '1. 4. 2`.

5. 2 파이썬 (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- 명시 적 경계.

5. 3 Maven/Gradle (자바)

`[1. 4,2. 0) '- 포함/독점.
음식에 중요한 유물에는 엄격한 발차기가 권장됩니다.

5. 4 이동 모듈

항상 'vMAJOR' 태그를 완료하십시오. 미노르. PATCH ';' v2 + '에는 모듈 접미사 '/v2' 가 필요합니다.

권장 사항: 응용 프로그램-정확한 핀 (재현 가능한 빌드). 라이브러리 - 캐럿 범위의 경우 (파손없이 업데이트를 용이하게합니다).

6) CHANELOG... 기존 코미트

구조화 된 변경 로그는 투명성을 향상시킵니다.

기존 커미션:


feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

"feat ',' fix ',' perf ',' docs ',' refactor ',' chore '... д.
느낌표 또는 'BREAKING CHANGE' 블록은 MAJOR을 선언합니다.
CHANELOG는 커밋의 역사 (봇별 릴리스 노트) 에서 생성됩니다.

7) API에 대한 수정 정책

공개 API: 엄격한 SemVer; → MAJOR를 깨뜨립니다.
모든 편지 선택 (c): '/v1/... ', '/v2/...' 또는 '수락: 응용 프로그램/vnd. org. 서비스. v2 + json '.
JSON 스키마: 사소한 확장 - 새로운 선택 필드; 주요 - 삭제/변경 필수.
gRPC/프로토: 새로운 숫자로 새 필드를 추가하십시오. 기존 번호를 깨뜨리지 않고 디 프레 케이트 → 를 삭제하는 필드 번호를 재사용하지 마십시오.

8) 데이터 및 마이그레이션 체계

데이터베이스 마이그레이션은 앱 @ 1 버전과 동기화됩니다. 8. 0 '에는' 스키마 @ 1이 필요합니다. 8. x '.
스키마 변경 중단 단계: 확장 (추가), 마이그레이션, 계약 (삭제). 이전 계약을 삭제할 때만 MAJOR로 업그레이드하십시오.
마이그레이션 기간 동안 이중 쓰기/읽기를 지원합니다.

9) 모노 레포와 마이크로 서비스

멀티 패키지: 각 패키지에는 자체 'MAJOR가 있습니다. 미노르. PATCH '; 메타 아티팩트에 대한 공통 루트 릴리스주기.

바리 전략:

독립 버전 (Lerna/Changesets) -격리를 증가시킵니다.
잠금 단계-더 쉬운 통신이지만 더 잘못된 MAJORS.
마이크로 서비스의 경우 별도의 버전 인 'contraction @ 2로 계약 (OpenAPI/Protoguy) 을 수정하십시오. 1. 0 ', 서비스가 이어집니다.

10) CI/CD의 릴리스 자동화

기존 코미트를 기반으로 한 버전의 자동 계산:

'수정' → 'PATCH', 'feat' → 'MINOR', '! '/' BREAKING' → 'MAJOR'.

자동 테그 및 아티팩트 서명:

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

CHANELOG 세대, 릴리스 노트 게시, GitOps repo의 종속성 업데이트로 '메인' 이 항상 마지막 안정적인 태그를 가리키는 지 확인하십시오.

11) 박탈 정책

발표: MINOR 릴리스에서 더 이상 사용되지 않는 기능을 표시하고 EOL 용어를 제공하십시오 (예: 90 일).

관찰 가능성: 사용자/테넌트 컨텍스트에 레거시 엔드 포인트 사용을 기록하십시

삭제: 다음 MAJOR에서. 마이그레이션 경로를 문서화

12) 예제 및 템플릿

12. 1 정규 SemVer 검증 표현

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 비교의 2 가지 예

`1. 2. 3` < `1. 10. 0 '(MINOR 비교).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3 + 빌드. 5` == `1. 2. 3`.

12. 3 의존성 정책 (YAML 예)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) 반 패턴

prod에서 '최신 '/부동 태그를 사용합니다.
실제 고장없이 메이저 향상 ("마케팅 버전").
'PATCH' 의 모습으로 숨겨진 파괴 변경.
생산 응용 프로그램의 전이 종속성에서 시험판.
새 태그 (변경 가능한 버전) 없이 아티팩트를 변경하십시오.

일관되지 않은 코드 버전 및 데이터베이스 스키마

14) 구현 점검표 (0-45 일)

0-10 일

SemVer를 필수 표준으로 받아들이고 속보 기준을 승인하십시오.
기존 커미션 및 'BREAKING CHANGE' 필드가있는 PR 템플릿 포함.

11-25 일

시맨틱 릴리스/체인지 세트, CHANELOG 자동 생성을 연결하십시오.
vX 태그에 대한 아티팩트 서명 및 게시를 설정합니다. Y.Z '.

26-45 일

레거시 API 사용에 대한 삭제 정책 및 원격 측정을 입력하십시오.
동기화 계약 버전 (OpenAPI/Proto) 및 서비스.
정책 수준 (OPA/CI 규정) 에서 '최신' 및 변경 가능한 태그를 금지합니다.

15) 성숙도 지표

SemVer 태그 만 게시 된 아티팩트의%.
MINOR 버전 간의 평균 마이그레이션 시간.

숨겨진 속보 변경으로 인한 사고 수

리포지토리의 기존 코미트 적용 범위 (> 95%).
제품의 부동 범위가없는 종속성 비율 (> 90%).

16) SemVer가 필요하지 않은 경우

외부 소비자가없는 내부 고속 프로토 타입 (날짜 버전이 적합).
실험 기능이있는 데이터/모델 (변환기 수준에서 호환성을 갖춘 더 나은 모델/스키마 버전).
안정적인 공개 API가없는 콘텐츠 패키지.

17) 결론

SemVer는 제조업체와 소비자 간의 신탁 계약입니다. 호환성을 깨뜨리고, 릴리스 유형 인식 및 아티팩트 게시를 자동화하고, 투명한 CHANELOG를 유지하고, 박탈 정책을 준수하는 것을 명확하게 정의하십시오. 그런 다음 업데이트는 일상적이고 예측 가능하며 안전하게되며 인프라와 API는 비즈니스에 충격을주지 않고 개발됩니다.

시맨틱 버전