gugabfigueiredo/semver-howto

semver-howto은(는) 무엇을 하나요?

모든 로직은 scripts/resolve-version.sh에 있습니다. 이 파일은 에이전트에게 언제 호출해야 하는지와 규칙이 무엇인지를 알려줍니다. 절차를 다시 유도하지 마십시오 — 플래그는 스크립트의 --help를, 알고리즘은 인라인 주석을 참조하십시오.

호출 시점

• 코드 변경 후, 버전 태그를 제안해야 할 때.
• 사용자가 "태그 생성" / "버전 업" / "버전이 뭐지?"라고 말할 때.
• 태그 선택을 에이전트에 위임하는 CI 단계에서.

커밋 메시지 작성이나 변경 로그 생성을 위해 호출하지 마십시오.

스크립트가 적용하는 규칙

1. 영향 범위(Impact Zone): 수정된 경로 → git log -1 -- <paths> → git describe --match "*v*" <commit>. 모노레포에서 모든 태그로 확장하지 않습니다.
2. 버전 업: 영향 범위 내 커밋에 feat:이 있으면 마이너(minor), 그 외는 패치(patch). 메이저(major)는 절대 자동으로 수행되지 않습니다.
3. 충돌 방지: 로컬에서 패턴 범위 git tag -l, 그 다음 대상 git ls-remote --tags origin "refs/tags/<candidate>"로 얕은 사전 점검을 수행합니다. 점유된 주소를 넘어서 이동합니다.
4. RC 전용: 자율적인 출력은 항상 -rc[n]입니다. 클린 태그는 거부됩니다.
5. 제안만, 푸시 금지: 표준 출력 = 하나의 태그. 사람(또는 승인 워크플로우)이 변경을 수행합니다.

사용법

./skills/semver-howto/scripts/resolve-version.sh              # 다음 -rc[n] 제안
./skills/semver-howto/scripts/resolve-version.sh --promote    # 가장 높은 RC에서 -rc 제거
./skills/semver-howto/scripts/resolve-version.sh --paths "a b" # 명시적 영향 범위
./skills/semver-howto/scripts/resolve-version.sh --help       # 플래그 + 알고리즘 참고

종료 코드 0은 성공입니다. 0이 아니면 모호하거나 안전하지 않은 상태입니다(자세한 내용은 stderr).

성능 및 안전성

• git describe --match "<prefix>*v*" <commit>으로 태그 탐색을 관련 참조로 제한합니다 — 수천 개의 모듈별 태그가 있는 모노레포에서 중요합니다.
• git tag -l "<pattern>"은 packed-refs에서 제공되며, O(히스토리)가 아닌 O(일치 수)입니다.
• git ls-remote --tags origin "refs/tags/<candidate>"은 단일 참조만 요청합니다. 객체를 가져오지 않고 FETCH_HEAD를 변경하지 않으며, 대규모 원격에서도 일반적으로 1초 미만입니다. git fetch --tags를 완전히 피합니다.
• Diff 및 로그 쿼리는 영향 범위 경로로 제한되므로, 각 실행은 히스토리의 관련 부분만 처리합니다.
• 안전성: RC 전용 쓰기, 로컬+원격 이중 충돌 검사, 푸시 없음, 메이저 버전 업 없음, 이전 태그가 없을 때 결정론적 부트스트랩(v0.1.0-rc1) — 사람 확인을 위해 stderr로 출력됩니다.