시맨틱 버전

Semantic Versioning (SemVer) -버전 번호가 변경 사항의 특성을 반영하는 방법에 대한 계약. 형식: MAJOR. 미노르. PATCH [-PRERELEASE] [+ BUILD].

• 메이저 - 호환되지 않는 변경 (파괴).
• MINOR-왕복 호환 기능/확장.
• PATCH-후방 호환 버그/보안 수정.

목표: 갑작스런 소비자 고장없이 API, 이벤트, 데이터 스키마, SDK 및 구성의 예측 가능한 진화.

1) 컨벤션 번호

X.Y.Z[-alpha.1    -rc.1][+build.sha]

시험판 ('-alpha', '-beta', '-rc') - 불안정한 어셈블리; 호환성을 약속하지 않습니다.
메타 데이터 빌드 ('+ sha') -추적에 유용한 비교 순서에는 영향을 미치지 않습니다.
최대 1. 0. 0 모든 변경 사항은 위반으로 간주 될 수 있습니다 (그러나 처음부터 규칙을 따르는 것이 좋습니다).

2) 브레이킹/마이너/패치를 고려해야 할 사항

• 계약을 변경하지 않고 버그 및 보안 수정
• 계약에 영향을 미치지 않는 도킹 업데이트.
• 응답/이벤트/체계를 변경하지 않고 최적화.

• 새 필드/메소드/엔드 포인트를 추가하십시오.
• 소비자가 익숙하지 않은 값을 허용하는 경우 enum 값을 확장
• 새로운 데이터베이스 색인, 기본 이벤트가있는 널링 가능한 열, 이전 이벤트 외에 새로운 이벤트.

• 필드 삭제/이름 변경, 유형 변경, 필수
• 의미론/상태/오류 코드를 변경합니다.
• 직렬화 형식, 주요 체계, 전송 프로토콜 변경.
• 압축/병합 주제, 이벤트 의미 전송, 분할 체계 변경.
• 이전 버전과의 호환성없이 "2 단계" 전환이 필요한 데이터베이스 마이그레이션.

3) 아티팩트 버전 지정

3. 1 REST

변형: '²/v1/...', 헤더 ('수락: 응용 프로그램/vnd. acme. 게임 + json; 버전 = 1 '), 매개 변수

추천: 공개 API에 대한 URI의 버전; 내부-헤더 c 협상을 통해.
MINOR: 옵션 필드, 새로운 필터/리소스 추가; 기존 답변을 변경하지 않습니다.
PATCH: 수정, 정의 개선, 안정적인 정렬.

3. 2 gRPC

옵션으로 표시된 새 필드; 서버는 알 수 없는 것을 무시해야 합니다

MAJOR → 서명/유형 변경 (새 패키지/서비스: 'acme. 지갑. v2 ').
필드를 삭제하지 않습니다: "deparcket + reserve a 숫자", 다음 MAJOR에서만 삭제하십시오.

3. 3 그래프 QL

MINOR: 새로운 필드/유형/쿼리; 제거-' @ 더 이상 사용되지 않음 '+ 마이그레이션 창을 통해 완전히 제거-MAJOR.
무효화 → 무효화-MAJOR.

3. 4 가지 이벤트 및 주제 (Kafka/SQS)

스키마 등록 소의 스키마: 첨가제의 진화 (기본값이있는 필드 추가).
새로운 호환되지 않는 버전 → 새로운 주제/주제 ('bet. 해결. v2 ').
파티션 키는 MAJOR에서 불변입니다.

3. 5 DB 다이어그램

1. 열을 추가합니다. (nullable/컨텍스트) →

2. 백필을 채우십시오 →

3. 번역 → 읽기

4. 오래된 것을 제거하십시오 (MAJOR 만 해당)

phicheflag 및 이중 항목에서 유형/PK/고유성 변경-MAJOR.

3. 6 SDK/CLI

공개 방법/서명은 동일한 규칙입니다.
자동 생성 (OpenAPI/Proto) 의 경우 - 배치 이름 및 아티팩트 버전.

4) 박탈 정책 및 수명주기

각 파괴 변경 앞에는 박탈 (일반적으로 외부의 경우 90-180 일, 내부의 경우 30-60 일) 이 선행됩니다.
커뮤니케이션: 변경 로그, 파트너에게 전자 메일/웹 후크, 개발자 포털의 배너.
듀얼 실행 모드: 'v1' 과 'v2' 를 병렬로 유지하고 트래픽 'v1' 의 점유율을 모니터링하십시오.
선셋 헤더 (REST): '일몰: 2026-03-31', '링크: <url>; rel = "deprencation" '.

5) 버전 협상

클라이언트는 원하는 버전 + 최대 지원 버전 (예: 'Accept-Version: 1,2') 을 보냅니다.
서버는 'Content-Version: 2' 로 응답합니다.
양방향 프로토콜 (WebSocket, gRPC) 에서 '지원되는 _ 버전' 과 Hello 프레임 교환.

6) 공급자 어댑터 통합 (ACL)

외부 공급자는 체계를 변경합니다-어댑터 내부에서 v1/v2 매퍼를 유지하고 내부 이벤트에 대해 MINOR를 릴리스하여 도메인 계약을 유지합니다.
외부 변경 사항이 적용되면 이는 도메인 이벤트의 주요 사항이며 새로운 주제입니다.

7) Changelog 및 커밋 라벨

Changelog 및 기존 코미트를 유지하십시오

'feat: ...' → 미노르

'수정: ... '/' chore ',' docs ',' perf '(계약 없음) → PATCH

'feat!: '/' fix!: '/' refactor!:' 또는 'BREAKING CHANGE:' MAJOR → body

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) 출시 자동화

CI: 회로 유효성 검사기 (OpenAPI/Proto/JSON-Schema), 파괴 확산 감지. 더 많은

SemVer-bot: 분석 기존 Commits → 는 범프 (메이저/마이너/패치) 를 계산하고 태그를 지정하며 변경 로그를 생성합니다.
CD: 별도의 배포 및 릴리스 (phicheflags/configs는 새 버전을 활성화합니다).
제어: 성공적인 카나리아 및 합의 된 SLO까지 PRO에 '최신' 을 게시하지 마십시오.

9) 구성 및 정책을위한 시맨틱

구성 요소 (YAML/JSON) 에는 스키마 버전 '스키마 _ 버전: 3' 도 있습니다.
MINOR-새로운 옵션 필드/규칙 MAJOR-구조/의무 변경.

유효성 검사기에서 v2/v3 지원; 비 호환성 보고서가있는 마이그레이터 설정

10) 호환성 테스트

소비자 중심 계약 테스트 (Pact): 통합 당.

스키마 진화 테스트: 새로운 스키마에서 오래된 페이로드를 실행하고 그 반대도 마찬가지입

재생-생산 트래픽 'v1' 에서 'v2' 를 그림자로 재생합니다.
속성 기반: 익숙하지 않은 필드/에넘에 대한 저항.

11) 버전 별 관찰 가능성

태그 메트릭/로그: 'api _ 버전', '스키마 _ 버전', '이벤트 _ 버전'.
마이그레이션 대시 보드: 버전 별 트래픽 공유, 'v1/v2' 의 오류/대기 시간.
경고: 'v1' 이 계획대로 내려 가지 않으면; 'v2' 방출 후 4xx/5xx 성장.

12) 다운 타임이없는 마이그레이션 패턴

(PHP 3 = 3.0.6, PHP 4)

이중 쓰기 + 는 읽기를 전환하기 전에 분기를 비교합니다.
순위/규칙에 대한 그림자 비교.
세입자/지역별 카나리아; 빠른 롤백을위한 플래그 기능.
Read-compat/Write-compat 창: 새 버전은 이전 데이터를 읽지 만 새 형식으로 작성합니다.

13) 반 패턴

리소스/이벤트를 버전으로 지정하는 대신 "각 필드의 버전".
MINOR에서 숨겨진 파괴 변경 사항 (예: 기본값 변경).
창 및 소비 지표없이 박탈 된 제거.
"Forever v1": 이전 버전의 → 기술 부채 및 취약점을 제거 할 계획이 없습니다.
비즈니스 버전과 컨테이너 이미지 버전을 혼합하십시오.

14) 정책 점검표 수정

• 고정 버전 형식 및 진실 소스 (레지스트리/포털).
• 아티팩트 별 중단 기준 목록 (REST/gRPC/GraphQL/이벤트/DB).
• 박탈 프로세스: 타이밍, 커뮤니케이션, 일몰/배너, 듀얼 런.
• 자동 diff 검사기 및 기존 코미트.
• 버전 및 경고 소비 대시 보드.
• 마이그레이션 플레이 북 (확장/마이그레이션/계약, 이중 쓰기, 그림자).
• 컨피그와 SDK에는 자체 버전과 케이스가 있습니다.
• 고객을위한 "버전 선택 방법" 및 팀을위한 "업그레이드 방법" 문서.

15) 버전의 예 (iGaming 케이스)

'BetSettled v1' 이벤트 → 'v2': 'void _ reason' (선택 사항) 및 '세금 추가. 금액 '(선택 사항) -MINOR. 새로운 주제 인 '지불' → 'win _ amount' -MAJOR로 이름이 변경되었습니다.
REST '/지갑/전송 ': 필터 추가? 테넌트 _ id = '- MINOR. 오류 코드 '409' → '422' -MAJOR을 변경했습니다.

GraphQL: 'Player' 로 표시되었습니다. 나이 '는' 플레이어 '를 위해' @ 더 이상 사용되지 않음 '으로 표시됩 ageGroup '- MINOR 릴리스, 기간 X 이후 MAJOR에서 삭제

DB: 'boners _ wager _ left' 열 추가-MINOR. null이 아닌 'bonus _ left' -MAJOR (확장/계약을 통해) 을 삭제했습니다.

결론

시맨틱 버전은 숫자가 아니라 신뢰와 예측 가능성에 관한 것입니다. 명확한 규칙, 자동 점검, 제어 된 박탈 및 투명한 원격 측정을 통해 API, 이벤트 및 통증이없는 스키마가 통합을 위해 진화 할 수 있으며 변경 사항을 자주, 안전하고 의미있게 해제합니다.