document-haness/RELEASING.md

technical-doc-flow 릴리스 체크리스트

VERSION은 릴리스 버전의 단일 진실 원천(SSOT)이다. 플러그인·마켓플레이스·Gemini 매니페스트의 버전은 반드시 이 값과 일치해야 하며, CI가 이를 검사한다.

버전이 반영되는 파일

파일	필드
VERSION	평문 SemVer, 예: 0.1.0
.claude-plugin/plugin.json	version
.claude-plugin/marketplace.json	metadata.version, 해당 plugin의 version
gemini-extension.json	version

SKILL frontmatter는 호환성을 위해 name과 description만 두며 버전을 복제하지 않는다. harness.json도 버전 문자열 대신 version_file: VERSION으로 이 파일을 가리킨다. README의 과거 릴리스 기록이나 예제 버전까지 일괄 치환하지 않는다. 현재 배포·경로·에이전트·산출물 계약은 scripts/check_release_sync.py가 검사한다.

릴리스 전 필수 검증

python3 scripts/check_release_sync.py
python3 scripts/build_quick_rules.py --check
python3 -m pytest -q
bash -n install.sh uninstall.sh update.sh .github/scripts/test_install_dry_run.sh .github/scripts/fixtures/gemini
bash .github/scripts/test_install_dry_run.sh

추가 확인 항목:

• canonical skill은 skills/technical-doc-flow/SKILL.md 한 곳이며 Claude와 Codex가 같은 디렉토리를 설치한다.
• Claude 에이전트 정의는 루트 agents/*.md에 있다.
• --copy는 Claude/Codex 설치에만 적용되고 Gemini는 항상 extension link를 사용한다.
• Gemini 공개 명령은 /technical-doc, /technical-doc-review이며 두 alias 모두 cwd 상대경로 대신 등록된 technical-doc-flow 스킬을 활성화한다. gemini-extension.json.contextFileName은 GEMINI.md이고, 두 alias는 절차를 복제하지 않는다.
• Gemini 제거는 JSON 목록의 이름과 현재 checkout 경로가 모두 일치할 때만 uninstall하며, 조회·파싱·소유권 확인 실패 시 fail-closed로 중단한다.
• quick rules 생성물이 SSOT와 일치한다.
• 설치 스크립트의 symlink·copy·force backup·dry-run 경로가 모두 통과한다.
• 제거 스크립트가 이 checkout을 가리키는 symlink만 제거하고 copy·백업·사용자 파일은 보존한다.
• update.sh가 upstream 없는 저장소와 diverged history에서 명확히 중단하고, pull 뒤 release contract·quick-rules 검사가 실패하면 설치를 재적용하지 않는다.
• 릴리스 노트의 품질·성능 수치는 실제 검증 결과만 사용한다.

버전 올리는 순서

1. VERSION을 새 SemVer로 변경한다.
2. 위 표의 매니페스트 버전을 같은 값으로 변경한다.
3. 생성 규칙을 다시 빌드하고 모든 검증을 실행한다.
4. 사용자 문서와 릴리스 노트를 갱신한다.
5. PR을 리뷰하고 모든 변경을 기본 브랜치에 머지한다.
6. 머지 커밋에 vX.Y.Z 태그를 생성하고 push한다.
7. 같은 태그로 GitHub Release를 발행한다.

태그는 문서·매니페스트·생성물·테스트 변경이 모두 기본 브랜치에 들어간 뒤에만 만든다. 공개된 태그는 이동하지 않는다.