릴리스 엔지니어링 정책
버전 관리, 릴리스 태그 지정, 지원 중단 주기, 호환성을 깨는 변경, 롤백 절차에 관한 다섯 가지 표준 정책입니다.
다섯 가지 정책이 apothem의 릴리스 방식을 규정합니다.
1. 시맨틱 버저닝
이 프로젝트는 시맨틱 버저닝 2.0에 따라 배포됩니다.
버전 번호는 MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] 형식을 따릅니다.
| 증가 | 트리거 |
|---|---|
| MAJOR | 아티팩트 스키마, 맨데이트 식별자(CM-N / TM-N / CP-N), 또는 훅 계약에 대한 호환성을 깨는 변경 |
| MINOR | 새 규칙, 위임 작업자, 명령, 스킬, 훅 이벤트, 또는 호환성을 깨지 않는 스키마 확장 |
| PATCH | 명확화, 안티패턴 추가, 문서 수정, 동작을 바꾸지 않는 편집 |
후보 태그는 vX.Y.Z-rc.N(릴리스 후보)
또는 vX.Y.Z-alpha.N / vX.Y.Z-beta.N(조기 액세스) 형식을 사용합니다.
2. 릴리스 태그
모든 릴리스는 main에 vMAJOR.MINOR.PATCH 형식의 서명된 git 태그를
안착시킵니다. 이 태그는 .github/workflows/release.yml을 트리거하며, 이
워크플로는 빌드하고, 서명하고, SBOM과 SLSA-3 출처를 생성하고,
GitHub Release 페이지를 게시합니다.
태그 규칙:
- 형식 — 정확히
vMAJOR.MINOR.PATCH입니다.release-접두사도-final접미사도 없습니다. - 주석 — 모든 태그는 주석 태그(
git tag -a -s)이며, 태그 메시지에 릴리스 노트 요약을 담습니다. - 서명 — 모든 태그는 GPG로 서명됩니다. 릴리스 워크플로는 추가로 각 아티팩트에 대한 Sigstore 키리스 cosign 서명과 SLSA-3 출처 기록을 생성하며, 둘 다 GitHub Release 페이지에 첨부됩니다.
릴리스 모델: 추가형
릴리스는 추가형입니다. 각 릴리스는 main에 커밋 하나와 태그 하나를
추가합니다. main은 절대 강제 푸시되지 않으며, 게시된 태그, GitHub Release,
npm 버전은 어느 것도 삭제되거나, 이동되거나, 재사용되지 않습니다. 각 릴리스는 자체 태그, 자체 GitHub Release, 자체 npm 버전을 유지하며, 모든 릴리스가 게시된 상태로 남습니다. npm 버전은 변경할 수
없습니다. 게시된 name@version은 절대 교체할 수 없으며, 게시가 취소된 번호는
절대 다시 사용할 수 없습니다. 고정된 설치와 재현 가능한 빌드는 게시된 모든
태그에 의존합니다. 릴리스 주기 런북과
릴리스 복구 런북 모두 이 모델을
따릅니다.
저장소의 릴리스 파사드 규칙(기여자 지침의 Release Facade 섹션)은 이 모델을 명시합니다. 현재 버전만 나타내야 한다는 요건은 freshness-facade 규칙에도 미러링되어 있으며, 공개 표면이 말하는 내용에 적용됩니다. 이 요건은 어떤 릴리스가 게시된 상태로 남을지를 제한하지 않습니다.
3. 지원 중단 정책
현재 공개 지원 라인은 가장 최근에 릴리스된 마이너 버전입니다. 프로젝트에 공개 마이너 버전이 여러 개 있는 경우, SECURITY.md의 지원 버전 매트릭스가 추가적인 중요 수정 전용 지원 기간에 대한 기준 출처입니다.
지원 중단 주기:
- 공지 — 지원 중단되는 심볼이나 동작은 해당 지원 중단이 반영되는
릴리스의
CHANGELOG.md### Deprecated섹션에서 공지됩니다. 릴리스 노트는 이 지원 중단 공지를 그대로 반영합니다. - 유예 기간 — 지원 중단된 심볼은 제거되기 전에 최소 한 번의 완전한 마이너 주기 동안 사용 가능한 상태로 유지됩니다.
- 제거 — 제거는
MAJOR증가에서 이루어집니다. 제거되는 각 심볼에는CHANGELOG.md### Removed줄과 사용법 가이드 아래의 마이그레이션 가이드 항목이 따릅니다.
런타임 최저 버전
Apothem은 두 가지 런타임 최저 버전을 선언합니다. pyproject.toml의
requires-python = ">=3.10"과 package.json의 "engines": {"node": ">=18"}입니다.
- 선언된 모든 최저 버전은 테스트됩니다. Python 최저 버전은 CI
quality매트릭스와CI Matrix워크플로에서 실행됩니다.npm Shim워크플로는 Node 최저 버전과 그 이후의 모든 LTS 메이저 버전에서 npm 심을 실행합니다. 이 워크플로는 전제 조건 누락 오류,node bin/apothem.mjs --version, 격리된 홈 디렉터리에서의 드라이런 설치, 그리고npx를 통한 패킹된 tarball을 점검합니다. 테스트되지 않는 런타임은 선언되지 않습니다. - 수명 종료는 공개됩니다. 여전히 선언된 최저 버전인 런타임이 업스트림 수명 종료에 도달하면, 설치 가이드가 그 사실을 밝히고 우선 사용할 버전을 명시합니다. Python 3.10은 2026-10-01에 수명 종료에 도달했고, Node.js 18과 20은 각각 2025-04-30과 2026-04-30에 도달했습니다. 세 가지 모두 지원되는 최저 버전으로 남아 있습니다.
- 최저 버전 상향은 지원 중단입니다. 이는 위의 주기를 따릅니다.
### Deprecated아래의 공지, 이전 최저 버전이 계속 테스트되는 최소 한 번의 완전한 마이너 주기를 거친 다음, 최저 버전을 올리는 릴리스가 그 변경을 기록합니다.requires-python,engines.node, 설치 프로그램의 버전 프로브, CI 매트릭스는 그 릴리스에서 함께 변경됩니다.
4. 호환성을 깨는 변경 정책
호환성을 깨는 변경에는 다음이 필요합니다.
- RFC 이슈 —
rfcs이슈 레이블로 열리며, 호환성을 깨는 변경, 마이그레이션 경로, 롤백 전략을 설명합니다. - 30일 의견 수렴 기간 — RFC는 병합 전에 최소 30일 동안 열려 있습니다. 피드백상 필요한 경우 메인테이너는 기간을 연장할 수 있습니다.
- MAJOR 증가 — 호환성을 깨는 변경을 반영하는 릴리스는 MAJOR 구성 요소를 증가시킵니다.
- 마이그레이션 가이드 — 변경은 운영자에게 마이그레이션을 단계별로 안내하는 사용법 가이드 항목과 함께 제공됩니다.
5. 롤백 정책
릴리스에 채택을 가로막는 회귀가 나타나는 경우:
- 되돌리기 — 문제를 일으킨 커밋이
main에서 되돌려집니다. - 전진 수정 릴리스 — 되돌리기와 모든 증분 수정을 담은 후속 릴리스가
vMAJOR.MINOR.PATCH+1로 안착합니다. 이전의 잘못된 릴리스는 GitHub Releases에서 삭제되지 않으며, 해당 npm 버전은 게시된 상태로 남고(npm 버전은 변경할 수 없음)npm deprecate로 표시됩니다.CHANGELOG.md의### Yanked주석이 이 상황을 문서화하여 재현 가능한 빌드가 고정된 상태로 유지됩니다. - 커뮤니케이션 — 롤백에는 보안 권고 공지(보안 관련인 경우) 또는 해당 인시던트를 위해 고정된 GitHub 이슈(신뢰성 관련인 경우)가 동반됩니다.
함께 보기
- CHANGELOG.md — 표준 릴리스 원장.
- SECURITY.md — 지원 버전 매트릭스와 보고 채널.
- cicd-pipeline.md — 모든 릴리스를 게이트하는 CI 검사 클래스.
- deployment-checklist.md — 릴리스별 프로덕션 준비 점검.