CONVENTIONAL COMMITS THAM KHẢO NHANH
Định dạng commit message, type, scope, breaking change
Định Dạng
Cấu Trúc Commit Message
[optional scope]:
[optional body]
[optional footer(s)]
Giải Thích Các Phần
| 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
| 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)
| 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)
| 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
| 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
| ! 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
| 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
| 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
| 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.