컨벤셔널 커밋과 릴리즈
개요
커밋 메시지는 기계가 읽는 인터페이스이지, 단순한 서술이 아닙니다. 자동 버전 관리와 체인지로그 생성은 이를 파싱합니다. 잘못된 형식의 메시지는 잘못된 퍼블릭 버전이나 손상된 릴리즈를 초래합니다. 작은 규율(하나의 잘 작성된 메시지)로 큰 정확성(정확한 체인지로그, 올바른 버전 범프)을 자동으로 얻을 수 있습니다.
형식
<type>(<scope>): <description>
| 타입 | 효과 / 용도 |
|---|---|
feat | 새로운 기능 — minor 범프 |
fix | 버그 수정 — patch 범프 |
docs | 문서만 변경 |
chore | 유지보수, 의존성, 설정 |
refactor | 동작을 변경하지 않는 코드 변경 |
test | 테스트만 변경 |
ci / build | 파이프라인 / 빌드 시스템 변경 |
- 명령형 어조: "added X"나 "adds X"가 아닌 "add X"를 사용합니다.
- Breaking changes:
feat!:또는BREAKING CHANGE:푸터 — major 범프를 발생시킵니다. - 범위(scope) 는 선택 사항이지만 권장됩니다:
feat(auth):,fix(db):.
핵심 세부 사항
- 타입↔버전 연결은
feat와fix를 잘못 입력하면 잘못된 버전이 배포됨을 의미합니다. 타입을 신중하게 선택하세요: "add" = 새로운 기능, "update" = 기존 기능 개선, "fix" = 버그. - 스쿼시 병합: PR 제목이 배포되는 커밋이 됩니다. PR 제목 자체가 유효한 Conventional Commit이어야 합니다. 그렇지 않으면 릴리즈가 잘못됩니다.
- 인간 작성 어조. AI/어시스턴트 속성,
Co-authored-by트레일러, 생성됨 푸터를 사용하지 마세요. 커밋은 인간이 작성한 것처럼 읽혀야 합니다.
흔한 변명
| 변명 | 현실 |
|---|---|
| "메시지는 크게 중요하지 않아요" | 체인지로그와 버전 번호를 결정합니다. 기계적으로 중요합니다. |
"이 기능에는 chore가 충분히 비슷해요" | chore는 버전을 범프하지 않으므로 사용자가 릴리즈에서 기능을 받을 수 없습니다. 올바른 타입을 사용하세요. |
| "PR 제목은 나중에 고칠게요" | 스쿼시 병합 시 제목은 병합 시점에 최종입니다. 미리 수정하세요. |
| "Co-authored-by 트레일러는 괜찮아요" | 프로젝트 규칙에서 AI 속성을 금지합니다. 예외는 없습니다. |
적신호 — 즉시 중단
- 타입 접두사가 없는 커밋 메시지
- 사용자 동작을 추가하거나 수정하는 작업에
chore/docs사용 - 유효한 Conventional Commit이 아닌 스쿼시 PR 제목
- AI 속성 또는
Co-authored-by줄
강제 사항:
- PR 제목 — CI에서 검증되며, 차단됨 (
amannn/action-semantic-pull-request). 스쿼시 병합 시 제목이 배포되는 커밋이므로, 이것이 핵심 게이트입니다. - AI 속성 —
No AI Attribution차단 작업이Co-authored-by트레일러(Claude/Anthropic 명명)와Generated with [Claude…]푸터를 거부합니다. 이는 브랜치 커밋과 PR 본문(스쿼시 커밋 본문이 됨) 모두에서 검사됩니다. 인간Co-authored-by트레일러는 영향을 받지 않습니다. - 브랜치 커밋 본문 — 의도적으로 lint되지 않습니다. 스쿼시 병합 시 폐기되므로 체인지로그에 도달하지 않습니다. 병합 커밋으로 전환하는 경우 commitlint를 추가하세요.
알려진 격차: 에이전트 계정이 커밋을 작성한 경우, GitHub는 스쿼시 시점에 Co-authored-by 트레일러를 구성합니다. 이는 PR 검사가 실행된 후입니다. 위 게이트는 이를 감지할 수 없습니다. 에이전트 신원으로 커밋하지 마세요.
전체 근거: 헌법 제3조, engineering-constitution/references/engineering-constitution.md에 번들됨.