# Conventional Commits Tham Khảo Nhanh

*Định dạng commit message, type, scope, breaking change*

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

## Định Dạng

### Cấu Trúc Commit Message

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

### Giải Thích Các Phần

| Command | Description |
|---------|-------------|
| `type` | Loại thay đổi (feat, fix, v.v.) |
| `scope` | Phần codebase bị ảnh hưởng (tùy chọn) |
| `description` | Tóm tắt ngắn gọn ở thể mệnh lệnh |
| `body` | Giải thích chi tiết (tùy chọn, sau dòng trống) |
| `footer` | Metadata như BREAKING CHANGE hoặc tham chiếu issue |

### Quy Tắc

| Command | Description |
|---------|-------------|
| `Thể mệnh lệnh` | "add feature" chứ không phải "added feature" |
| `Type viết thường` | feat: chứ không phải Feat: |
| `Không có dấu chấm` | Description không kết thúc bằng "." |
| `Dòng trống` | Phân cách body/footer với description |

## Types

### Type Cốt Lõi (Liên Quan SemVer)

| Command | Description |
|---------|-------------|
| `feat` | Tính năng mới (tăng phiên bản MINOR) |
| `fix` | Sửa lỗi (tăng phiên bản PATCH) |

### Type Mở Rộng (Quy Ước Phổ Biến)

| Command | Description |
|---------|-------------|
| `build` | Hệ thống build hoặc dependency ngoài |
| `chore` | Tác vụ bảo trì (không thay đổi src/test) |
| `ci` | Cấu hình và script CI |
| `docs` | Chỉ thay đổi tài liệu |
| `perf` | Cải thiện hiệu năng |
| `refactor` | Thay đổi code không sửa lỗi cũng không thêm tính năng |
| `revert` | Hoàn tác commit trước đó |
| `style` | Định dạng, khoảng trắng (không phải CSS) |
| `test` | Thêm hoặc sửa test |

## Scope

### Sử Dụng Scope

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

### Hướng Dẫn Scope

| Command | Description |
|---------|-------------|
| `Tên module` | feat(auth):, fix(parser): |
| `Tên layer` | feat(api):, fix(db): |
| `Khu vực tính năng` | feat(search):, fix(checkout): |
| `Dependency` | build(deps):, chore(npm): |
| `Bỏ qua nếu rộng` | Không cần scope cho thay đổi xuyên suốt |

## Breaking Changes

### Đánh Dấu Breaking Change

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

### Breaking Change Dạng Footer

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

### Quy Tắc

| Command | Description |
|---------|-------------|
| `! sau type/scope` | Ký hiệu tắt cho breaking change |
| `BREAKING CHANGE:` | Token footer (luôn viết hoa) |
| `BREAKING-CHANGE:` | Cũng hợp lệ (dạng gạch ngang) |
| `Ảnh hưởng SemVer` | Tăng phiên bản MAJOR |
| `Bất kỳ type nào` | Breaking change có thể áp dụng cho mọi type |

## Ví Dụ

### Commit Đơn Giản

```
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
```

### Có Scope

```
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
```

### Có Body và Footer

```
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
```

## Footer

### Các Token Footer

| Command | Description |
|---------|-------------|
| `BREAKING CHANGE:` | Mô tả thay đổi API breaking |
| `Closes #123` | Tự động đóng issue khi merge |
| `Fixes #456` | Tự động đóng issue (tham chiếu fix) |
| `Refs #789` | Tham chiếu issue không đóng |
| `Reviewed-by: name` | Ghi nhận người review |
| `Co-authored-by: name` | Ghi nhận đồng tác giả |

### Nhiều Footer

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

Migrate from session-based to JWT auth.

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

## Công Cụ

### Commit Linting

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

### Công Cụ Phổ Biến

| Command | Description |
|---------|-------------|
| `commitlint` | Kiểm tra commit message theo quy ước |
| `husky` | Git hook (chạy commitlint khi commit) |
| `commitizen (cz)` | Trình tạo commit message tương tác |
| `standard-version` | Tự động changelog + tăng phiên bản |
| `semantic-release` | Pipeline release hoàn toàn tự động |
| `release-please` | Công cụ tự động release của Google |

### Thiết Lập Commitizen

```
npm install -D commitizen \
  cz-conventional-changelog
npx commitizen init cz-conventional-changelog
# Dùng: npx cz (hoặc git cz với alias)
```

## Các Pattern Thường Gặp

### Ánh Xạ Tăng Phiên Bản

| 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:, v.v.` | Không tăng phiên bản |

### Nhóm Changelog

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

### Định Dạng Revert

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