# Conventional Commits 빠른 참조

*커밋 메시지 형식, 타입, 스코프, 브레이킹 체인지*

> Source: Conventional Commits (conventionalcommits.org) · MIT

## 형식

### 커밋 메시지 구조

```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```

### 구성 요소 설명

| Command | Description |
|---------|-------------|
| `type` | 변경 범주 (feat, fix 등) |
| `scope` | 영향받는 코드베이스 영역 (선택) |
| `description` | 명령형 어조의 짧은 요약 |
| `body` | 상세 설명 (선택, 빈 줄 후 작성) |
| `footer` | BREAKING CHANGE 또는 이슈 참조 등 메타데이터 |

### 규칙

| Command | Description |
|---------|-------------|
| `Imperative mood` | "add feature" not "added feature" |
| `Lowercase type` | feat: 이며 Feat: 가 아님 |
| `No period` | 설명 끝에 마침표 없음 |
| `Blank line` | 설명과 본문/푸터 사이 빈 줄 |

## 타입

### 핵심 타입 (SemVer 관련)

| Command | Description |
|---------|-------------|
| `feat` | 새 기능 (MINOR 버전 업) |
| `fix` | 버그 수정 (PATCH 버전 업) |

### 확장 타입 (일반 관례)

| Command | Description |
|---------|-------------|
| `build` | 빌드 시스템 또는 외부 의존성 |
| `chore` | 유지보수 작업 (소스/테스트 변경 없음) |
| `ci` | CI 설정 및 스크립트 |
| `docs` | 문서만 변경 |
| `perf` | 성능 개선 |
| `refactor` | 버그 수정도 기능 추가도 아닌 코드 변경 |
| `revert` | 이전 커밋 되돌리기 |
| `style` | 포맷팅, 공백 (CSS 스타일링 아님) |
| `test` | 테스트 추가 또는 수정 |

## 스코프

### 스코프 사용

```
feat(auth): add OAuth2 login flow
fix(parser): handle empty input gracefully
docs(readme): update installation steps
refactor(api): extract validation middleware
```

### 스코프 가이드라인

| Command | Description |
|---------|-------------|
| `Module name` | feat(auth):, fix(parser): |
| `Layer name` | feat(api):, fix(db): |
| `Feature area` | feat(search):, fix(checkout): |
| `Dependency` | build(deps):, chore(npm): |
| `Omit if broad` | 횡단 관심사 변경 시 스코프 생략 |

## 브레이킹 체인지

### 브레이킹 체인지 표시

```
feat!: remove deprecated login endpoint
feat(api)!: change response format to JSON:API
fix!: drop Node 14 support
```

### 푸터 방식 브레이킹 체인지

```
feat(api): change user endpoint response
BREAKING CHANGE: response now returns array
instead of object. Update client parsing.
```

### 규칙

| Command | Description |
|---------|-------------|
| `! after type/scope` | 브레이킹 체인지 약식 표시 |
| `BREAKING CHANGE:` | 푸터 토큰 (항상 대문자) |
| `BREAKING-CHANGE:` | 하이픈 형식도 유효 |
| `SemVer impact` | MAJOR 버전 업 트리거 |
| `Any type` | 브레이킹 체인지는 모든 타입에 적용 가능 |

## 예시

### 간단한 커밋

```
feat: add email notifications
fix: prevent race condition in checkout
docs: correct typo in contributing guide
style: format with prettier
refactor: simplify error handling logic
```

### 스코프 포함

```
feat(blog): add comment threading
fix(auth): refresh token before expiry
test(api): add missing edge case coverage
ci(github): add Node 20 to test matrix
```

### 본문 및 푸터 포함

```
fix(parser): handle nested quotes correctly

Previously, nested quotes caused the parser
to enter an infinite loop. This adds a depth
counter to prevent unbounded recursion.

Closes #234
```

## 푸터

### 푸터 토큰

| Command | Description |
|---------|-------------|
| `BREAKING CHANGE:` | 브레이킹 API 변경 설명 |
| `Closes #123` | 머지 시 이슈 자동 닫기 |
| `Fixes #456` | 이슈 자동 닫기 (수정 참조) |
| `Refs #789` | 닫지 않고 이슈 참조 |
| `Reviewed-by: name` | 리뷰어 표시 |
| `Co-authored-by: name` | 공동 작성자 표시 |

### 복수 푸터

```
feat(api)!: redesign authentication flow

Migrate from session-based to JWT auth.

BREAKING CHANGE: /auth endpoints changed
Closes #101
Refs #98, #99
```

## 도구

### 커밋 린팅

```
npm install -D @commitlint/cli \
  @commitlint/config-conventional
echo "module.exports = { extends: \
  ['@commitlint/config-conventional'] }" \
  > commitlint.config.js
```

### 주요 도구

| Command | Description |
|---------|-------------|
| `commitlint` | 커밋 메시지 컨벤션 린팅 |
| `husky` | Git 훅 (커밋 시 commitlint 실행) |
| `commitizen (cz)` | 대화형 커밋 메시지 작성기 |
| `standard-version` | 자동 changelog + 버전 업 |
| `semantic-release` | 완전 자동 릴리즈 파이프라인 |
| `release-please` | Google의 릴리즈 자동화 도구 |

### Commitizen 설정

```
npm install -D commitizen \
  cz-conventional-changelog
npx commitizen init cz-conventional-changelog
# Use: npx cz (or git cz with alias)
```

## 일반 패턴

### 버전 업 매핑

| Command | Description |
|---------|-------------|
| `fix:` | PATCH (1.0.0 → 1.0.1) |
| `feat:` | MINOR (1.0.0 → 1.1.0) |
| `BREAKING CHANGE` | MAJOR (1.0.0 → 2.0.0) |
| `docs:, style:, etc.` | 버전 업 없음 |

### Changelog 그룹화

```
## [1.2.0] - 2026-03-27
### Features
- add email notifications (abc1234)
### Bug Fixes
- prevent race condition (#123) (def5678)
```

### 리버트 형식

```
revert: feat(blog): add comment threading
This reverts commit abc1234def5678.
```