릴리스 자동화
5. 자주 하는 실수 (Tip)
❌ 실수 1. VERSION 파일과 태그 버전이 어긋남
VERSION 은 고쳤는데 태그를 깜빡하거나 반대로 태그만 만들면, 빌드 산출물 버전과 릴리스 태그가 서로 다른 숫자를 가리킵니다. 한 커밋에서 VERSION·CHANGELOG.md 를 같이 고치고 바로 그 커밋에 태그를 답니다.
❌ 실수 2. 커밋 메시지가 Conventional Commits 형식을 안 지킴
"로그인 고침" 처럼 타입 없이 쓰면 bump_type 이 none 으로 판정해 버전이 올라가지 않습니다. fix: 로그인 오류 수정 처럼 타입을 반드시 붙입니다.
❌ 실수 3. 경량 태그만 쓰고 메시지 없음
git tag v1.1.0 으로 만든 경량 태그는 릴리스 노트를 담을 곳이 없습니다. 릴리스에는 항상 git tag -a 로 주석 태그를 씁니다.
❌ 실수 4. 태그를 로컬에만 만들고 push 하지 않음
로컬 태그는 원격에 자동으로 올라가지 않습니다. git push origin v1.1.0 을 빠뜨리면 태그 트리거 워크플로가 영원히 실행되지 않습니다.
❌ 실수 5. CHANGELOG.md 를 수동으로 덮어씀
자동 생성 스크립트가 있는데 릴리스 직전에 사람이 파일을 직접 고치면, 다음 자동 생성 때 그 수정이 사라지거나 형식이 깨집니다. 수동으로 넣을 내용은 커밋 메시지 본문에 적어 스크립트가 함께 반영하게 합니다.
❌ 실수 6. BREAKING CHANGE 표시 없이 호환성 깨는 변경 배포
설정 형식이나 API 를 바꾸면서 feat: 으로만 커밋하면 MINOR 로 판정돼 사용자가 대비 없이 업그레이드합니다. 호환성을 깨면 반드시 ! 나 BREAKING CHANGE: 를 붙입니다.
❌ 실수 7. 핫픽스를 main 최신에서 만듦
main 에는 아직 릴리스되지 않은 기능이 섞여 있을 수 있습니다. 핫픽스는 배포된 태그(v1.0.0)에서 분기해야 미출시 기능이 급한 배포에 함께 나가지 않습니다.
❌ 실수 8. 릴리스 노트에 커밋 해시만 나열
git log --oneline 결과를 그대로 붙이면 사용자는 무엇이 바뀌었는지 알 수 없습니다. Features·Fixes 로 묶고 사람이 읽을 수 있는 설명으로 바꿔야 합니다.
❌ 실수 9. 태그 이름 형식이 저장소마다 다름
어떤 릴리스는 v1.0.0, 어떤 릴리스는 1.0.0 으로 태그하면 on: push: tags: 'v*' 트리거가 일부 릴리스를 놓칩니다. 팀 전체가 v 접두사로 통일합니다.
❌ 실수 10. 프리릴리스 버전을 정식 릴리스처럼 태그
1.2.0-rc.1 같은 프리릴리스는 GitHub Release 화면에서 "Set as a pre-release" 로 표시해야 정식 배포와 구분됩니다. 구분 없이 올리면 사용자가 검증 안 된 버전을 받습니다.