Conventional Commits와 release notes

Conventional Commits는 message를 build 입력으로 바꿔

두 사람이 쓰는 repo라면 자유 형식 commit message도 괜찮아. 팀 규모에서는 모든 commit이 release 도구와 changelog, triage의 입력이 돼. Conventional Commits는 release bot과 changelog generator가 사람의 정리 없이 읽을 수 있는 작은 문법을 제목에 넣어. commit마다 prefix 하나를 쓰는 대신 changelog와 version bump를 자동화하지.

형식은 <type>(<optional scope>): <subject>야. Type은 feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert를 써. Scope는 feat(auth):나 fix(api):처럼 영역을 표시하고, type 또는 scope 뒤의 !는 feat(api)!: drop /v1/legacy처럼 breaking change를 뜻해. 본문과 footer에는 why, issue 참조, breaking change의 자세한 내용을 적어.

형식을 강제하면 semantic-release와 conventional-changelog가 힘을 발휘해. main push마다 fix:는 patch, feat:는 minor, !나 BREAKING CHANGE:는 major version을 계산해. 같은 message에서 feature, fix, breaking change로 나눈 CHANGELOG.md도 만들 수 있어. Release가 merge의 자동 결과가 되는 셈이야.

형식은 강제할 때 오래 살아. commitlint를 Git hook으로 두면 잘못된 message를 로컬에서 거부하고, commitizen은 올바른 message를 만드는 대화형 prompt를 제공하며, GitHub Action은 규칙을 어긴 PR을 막아. 가이드로만 두고 가볍게 어기면 자동화도 무너져. lint와 마찬가지로 틀린 입력은 거부하는 규칙으로 다뤄.

Code

형식 카탈로그·text

feat: add OAuth2 GitHub login
feat(auth): add OAuth2 GitHub login            # scope 포함
fix(api): handle empty array in /search response
docs(readme): document OAUTH_ENABLED flag
refactor(store): replace ad-hoc cache with TTL map
test(api): add property tests for /search edge cases
chore(deps): bump fastapi to 0.115.0
perf(query): index conversations.created_at
revert: "feat(auth): add OAuth2 GitHub login"

# Breaking change marker:
feat(api)!: drop /v1/legacy-search endpoint

# 또는 footer 로:
feat(api): replace /v1/search with /v2/search

BREAKING CHANGE: /v1/search endpoint is removed.
Migrate to /v2/search; response schema changes are
documented in docs/api/v2-migration.md.

Local + CI 강제·bash

# Git hook 으로 commitlint (Husky):
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
npx husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

# Interactive 올바른 메시지용 commitizen:
npm install --save-dev commitizen cz-conventional-changelog
echo '{"path": "cz-conventional-changelog"}' > .czrc
git cz                       # git commit 대신 이거 사용

# PR title + commit 검증 GitHub Action:
# .github/workflows/commitlint.yml — wagoid/commitlint-github-action 사용

Exercise

repo 하나에서 최근 commit 셋을 골라 Conventional Commits 형식의 message 초안을 써. 연습용 repo에는 commitlint와 Husky를 설치하고 잘못된 message로 commit해 거부 문구를 읽어. 고쳐서 commit한 뒤, 실제 프로젝트에서 Conventional Commits가 release를 도왔을 지점 하나를 적어봐.

Conventional Commits는 message를 build 입력으로 바꿔

Code

External links

Exercise

Progress

댓글 0