gh-release

gh-release은(는) 무엇을 하나요?

버전 업데이트, 체인지로그, 태그, 푸시, 모니터링.

아래 명령어들은 ~/.claude/skills/gh-release/scripts/ 전체 경로를 명시합니다. 지정된 그대로 정확히 실행하세요 - 앞의 ~를 유지하고 확장하지 마세요. 권한 규칙이 리터럴 명령 문자열과 일치하므로 /home/<you>/.claude/... (틸데 확장), python3 ~/..., 상대 경로, cd 후 실행은 각각 다른 문자열이며 각각 다시 프롬프트를 띄웁니다. 틸데 경로는 "비공식적으로 적은 절대 경로"가 아닙니다. 권한 규칙에게는 경로 그대로입니다.

릴리즈가 잘못되는 두 가지 이유가 있으며, 둘 다 태그가 생기기 전에 발생합니다:

1. 리포지토리가 이미 자동화한 버전 업데이트를 다시 발명하는 경우. 수동 편집은 리포지토리 자체 태스크가 처리했을 파일을 건드리고, 그 태스크가 알고 있는 파일은 놓치며, 게이트를 건너뜁니다.
2. 아무것도 트리거하지 않는 태그. 느린 CI 대기열처럼 보이며, 20분 후에 알게 됩니다.

1단계와 3단계는 이러한 상황을 잡기 위해 존재합니다.

0. 버전 결정

태그를 읽어(git tag --sort=-v:refname | head -5) 리포지토리의 형식(v1.2.3 vs 1.2.3)과 현재 버전을 확인합니다. 사용자가 버전을 지정했다면 그 버전을 사용합니다. 그렇지 않으면 마지막 태그 이후의 커밋을 기반으로 제안합니다 - breaking change는 major, feat:는 minor, 나머지는 patch - 그리고 이유를 설명합니다.

더티 트리, 분리된 HEAD, 원격보다 뒤처진 브랜치에서는 진행을 거부합니다. 커밋되지 않은 작업을 릴리즈하면 아무도 재현할 수 없는 태그가 생성됩니다.

1. 리포지토리 자체 릴리즈 메커니즘 사용

수동으로 하기 전에 항상 확인하세요:

~/.claude/skills/gh-release/scripts/versiontool.py discover

이 명령은 프로젝트 스킬, mise 태스크, npm 스크립트, Make 타겟, just 레시피, scripts/-bin/ 항목, 도구 설정(cargo-release, bumpversion, release-please, git-cliff)을 보고합니다. 우선순위:

kind=project-skill - 이 스킬 읽기를 중단하고 해당 스킬을 따릅니다. 이는 리포지토리 자체의 절차이며 이 일반 스킬이 알 수 없는 것을 알고 있습니다.

태스크 또는 스크립트 (kind=mise-task|npm-script|make-target|just-recipe|script)

• 실행하기 전에 읽고, 실행하세요. 무엇을 다루는지 알아야 중복되거나 누락되지 않습니다. 일반적인 태스크는 버전 업데이트, 체인지로그 프로모션, 게이트, 커밋, 태그, 푸시 중 일부만 수행합니다. 어떤 작업을 수행하는지 확인하고 나머지만 수행하세요.

많은 태스크는 버전만 받고 접두사를 직접 추가합니다(mise run release 0.13.0이 v0.13.0 태그를 생성). 따라서 버전이 필요한 곳에 태그를 전달하지 마세요. --dry-run이 있다면 먼저 사용하고 사용자에게 계획을 보여주세요.

태스크가 없는 도구 설정 - 해당 도구의 자체 명령어(cargo release <version>, bump-my-version bump ...)를 사용하고 수동 편집하지 마세요.

result=none - 그때만 2단계로 넘어갑니다.

2. 대체: 버전이 있는 모든 위치 찾기

1단계에서 아무것도 찾지 못한 경우에만.

~/.claude/skills/gh-release/scripts/versiontool.py locations <current-version>

"version"이라는 단어가 아닌 리터럴 버전 문자열을 검색합니다. 실제 리포지토리에서 측정한 결과: version 키 검색은 5개 파일 찾았고, 리터럴 문자열은 8개를 찾았습니다. 놓친 것은 "version-name" (GNOME 메타데이터) 및 "Version" (Plasma) 키를 사용했습니다. 놓치면 잘못된 버전을 보고하는 바이너리가 출시됩니다.

출력은 분류됩니다: edit (변경), regenerate (잠금 파일 - 힌트의 명령어 실행, 절대 수동 편집 금지, 그렇지 않으면 CI에서 --locked 실패), changelog (4단계).

그런 다음 이전 버전도 확인하세요 - 해당 버전의 히트는 마지막 릴리즈에서 놓친 파일이며 그 이후로 오래되었습니다. 이번 릴리즈에서 수정하세요.

3. 태그 사전 점검

~/.claude/skills/gh-release/scripts/relwatch.py preflight <tag>

이 명령은 .github/workflows/*.yml을 읽고 모든 on.push.tags 패턴을 추출하여 태그가 일치하는 패턴이 있는지와 해당 워크플로우가 릴리즈를 생성할 것 같은지 알려줍니다. result=NO_MATCH는 태그를 푸시해도 아무 일도 일어나지 않음을 의미합니다.

커밋하기 전에 실행하세요, 태그 변경이 무료일 때.

또한 워크플로우의 릴리즈 단계가 푸시하려는 태그를 사용하는지 직접 확인하세요. 많은 워크플로우가 태그가 코드의 버전과 일치하는지 확인하지 않으므로, 불일치는 녹색 CI와 함께 조용히 잘못된 버전을 보고하는 바이너리를 생성합니다.

4. 체인지로그

1단계의 태스크가 체인지로그를 직접 프로모션한다면 맡기고 5단계로 건너뛰세요.

체인지로그 유지 (## [Unreleased] 헤더가 있는 경우): 프로모션합니다.

• ## [Unreleased]는 ## [X.Y.Z] - YYYY-MM-DD가 됩니다.
• 그 위에 새로운 빈 ## [Unreleased]를 추가합니다.
• 하단의 링크 정의를 업데이트하고, [Unreleased] 비교 링크의 새 기준을 포함합니다.

체인지로그가 없거나 Unreleased 섹션이 없는 경우: 마지막 태그 이후의 커밋에서 항목을 작성하며, 파일이 이미 그룹화한 방식대로 그룹화합니다. 기존 어조를 정확히 일치시키세요 - 항목이 한 줄이면 한 줄로 작성하고, 굵은 리드가 있는 산문 형식이면 그렇게 작성하세요.

어느 쪽이든: 프로젝트 사용자에게 무엇이 변경되었는지 설명하고, 리포지토리에 무엇을 했는지 설명하지 마세요.

모든 항목에 unslop 스킬을 적용하세요. 체인지로그는 수년간 읽히며 업그레이드 여부를 결정하는 사람들이 읽습니다. "다양한 개선 및 버그 수정"은 항목이 없는 것보다 나쁩니다. 커밋 제목을 더 긴 단어로 다시 말하는 항목도 마찬가지입니다. 문서 특정 힌트는 docs-update/SKILL.md 5단계에 나열되어 있으며 여기에 그대로 적용됩니다: 불필요한 서두, 빈 강조, 확실한 답변에 대한 모호함 없음.

5. 태깅 전 검증

~/.claude/skills/gh-release/scripts/versiontool.py verify <old-version>    # result=clean을 출력해야 함

리포지토리 태스크가 버전 업데이트를 수행했을 때도 실행하세요. 6개월 전에 작성된 버전 업데이터는 지난주에 추가된 파일을 모르며, 이것이 바로 버전이 트리의 한 모퉁이에서 오래되는 방식입니다. 체인지로그 기록은 무시됩니다. 편집 가능한 파일만 계산됩니다.

그런 다음 프로젝트 게이트(빌드, 테스트, 린트)를 실행하세요. 빨간 커밋을 가리키는 태그는 삭제하고 다시 잘라야 하며, 푸시된 태그를 삭제하는 것은 이미 가져온 사람에게 지저분합니다.

6. 커밋, 태그, 푸시

1단계의 태스크가 이미 수행한 단계는 건너뛰세요. 이미 커밋, 태그, 푸시했다면 7단계로 바로 가세요.

그렇지 않으면: 릴리즈에 대한 하나의 커밋, ~/.claude/CLAUDE.md에 따라 브랜치 이름 접두사로 제목을 지정합니다. 버전 업데이트와 체인지로그는 동일한 커밋에 속합니다. 하나의 변경 사항입니다.

git commit -m "[<branch>] chore(release): <version>"
git tag -a <tag> -m "<tag>"
git push && git push origin <tag>

커밋을 태그보다 먼저 푸시하세요. 먼저 도착한 태그는 원격에 아직 없는 커밋에 대한 빌드를 시작할 수 있습니다.

푸시 시간을 기록하세요. 모니터링 시간을 제한합니다.

7. 릴리즈가 존재할 때까지 모니터링

~/.claude/skills/gh-release/scripts/relwatch.py watch <tag> --timeout 1800

결과	의미
released url=...	완료
ci_failed run=... conclusion=...	8단계
no_run	트리거되지 않음. 태그가 어떤 패턴과도 일치하지 않음 - preflight 실행
still_running	실패 아님. 다시 모니터링

녹색 CI는 릴리즈가 아닙니다: 게시 단계가 빌드보다 늦어질 수 있으므로, 와처는 Release 객체가 실제로 존재할 때까지 계속 기다립니다.

babysit-pr과 동일한 하위 에이전트 규칙: 단일 Bash 호출 내에서 하나의 watch(--timeout 540)가 인라인으로 더 저렴합니다. 대기가 여러 호출에 걸칠 때만 위임하세요. 릴리즈가 존재하거나 차단 항목이 있기 전에 멈추지 마세요.

8. 태그 후 CI 실패 시

태그가 잘못되었으므로, 패치로 우회하지 말고 철회하세요:

git push --delete origin <tag>
git tag -d <tag>

수정한 후 5단계부터 동일한 버전 번호로 다시 시작하세요. 실패를 건너뛰기 위해 버전을 올리지 마세요: 아직 릴리즈되지 않은 버전은 태울 가치가 없으며, 그 간격은 누군가가 누락된 릴리즈를 찾도록 유도합니다.

태그가 한동안 공개되었거나 부분 릴리즈가 존재하는 경우, 그렇게 말하고 사용자가 삭제와 위에 패치를 배송하는 것 중에서 선택하도록 하세요.

9. 보고

PR/비교 링크, 태그, 릴리즈 URL, 변경 사항, 업데이트된 모든 파일을 보고합니다. 사용자에게 남겨진 것이 있으면 언급하세요.