Git Workflow Convention

1. Git Commit Convention

1.1 Cấu trúc commit message

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

1.2 Các thành phần

Type (bắt buộc):

• feat: Thêm tính năng mới
• fix: Sửa lỗi
• docs: Thay đổi tài liệu
• refactor: Tái cấu trúc code (không thêm feature, không fix bug)
• perf: Cải thiện hiệu năng
• test: Thêm hoặc sửa test
• chore: Thay đổi build process, dependencies, tooling
• style: Thay đổi format code (không ảnh hưởng logic)

Scope (tuỳ chọn): Phần code bị ảnh hưởng, ví dụ: auth, parser, api

Description (bắt buộc): Mô tả ngắn gọn, dùng thì hiện tại (imperative mood)

• ✅ "add login feature"
• ❌ "added login feature" hoặc "adds login feature"

Body (tuỳ chọn): Giải thích chi tiết "what" và "why", cách một dòng trống sau description

Footer (tuỳ chọn): Thông tin bổ sung

• BREAKING CHANGE: <description> - Thay đổi phá vỡ API/hành vi
• Closes #123 - Đóng issue
• Refs: #456 - Tham chiếu issue

1.3 Breaking Changes

Khi có thay đổi phá vỡ tương thích ngược:

• Thêm ! sau type/scope: feat(api)!: remove deprecated endpoint
• Hoặc dùng footer: BREAKING CHANGE: API v1 endpoints removed

1.4 Ví dụ

feat(auth): add JWT token validation

Implement middleware to validate JWT tokens on protected routes.
This improves security by verifying token signatures and expiration.

Closes #234

fix!: correct data parsing logic

BREAKING CHANGE: Input format changed from XML to JSON

1.5 Lợi ích

• Tự động sinh CHANGELOG từ lịch sử commit
• Xác định version bump theo Semantic Versioning (fix → patch, feat → minor, BREAKING CHANGE → major)
• Dễ dàng review và tìm kiếm lịch sử thay đổi
• Hợp tác hiệu quả trong team

---

2. Git Branch Convention

2.1 Cấu trúc branch name

<prefix>/<issue-ID>-<short-description>

hoặc nếu không có issue:

<prefix>/<short-description>

2.2 Quy tắc đặt tên

• Chữ thường toàn bộ: feature/user-login ✅, Feature/User-Login ❌
• Dấu nối (-) giữa các từ: add-search-feature ✅, add_search_feature ❌
• Không khoảng trắng và ký tự đặc biệt (trừ dấu nối và slash)
• Ngắn gọn nhưng rõ ràng: mô tả đúng mục đích thay đổi

2.3 Tiền tố (prefix) chuẩn

Prefix	Mục đích	Ví dụ
feature/	Phát triển tính năng mới	feature/user-login feature/PROJ-123-add-search
bugfix/	Sửa lỗi thường	bugfix/login-button-issue bugfix/JIRA-456-fix-validation
hotfix/	Sửa lỗi nghiêm trọng production	hotfix/payment-crash hotfix/security-vulnerability
release/	Chuẩn bị phiên bản release	release/v1.2.0 release/2024-Q1
docs/	Cập nhật tài liệu	docs/api-documentation docs/readme-update
refactor/	Tái cấu trúc code	refactor/database-layer refactor/user-service
improvement/	Cải thiện hiệu năng/UX	improvement/query-optimization

2.4 Best practices

• Luôn include issue ID nếu có: feature/PROJ-123-description
• Mô tả cụ thể: feature/new ❌ → feature/user-authentication ✅
• Xoá branch sau merge: Giữ repository sạch sẽ
• Không làm việc trực tiếp trên main/master/develop

2.5 Ví dụ

feature/PROJ-42-add-user-authentication
bugfix/JIRA-789-fix-memory-leak
hotfix/payment-gateway-timeout
release/v2.1.0
docs/update-deployment-guide
refactor/optimize-database-queries

---

3. Pull Request (PR) Convention

3.1 Yêu cầu trước khi tạo PR

• ✅ Tạo PR từ branch riêng (không dùng main/master)
• ✅ Branch name tuân thủ convention (phần 2)
• ✅ Build & test đã pass
• ✅ Code đã được review tự kiểm

3.2 PR Title

Format:

<type>[(scope)]: <description> [(closes #issue)]

Quy tắc:

• Dùng imperative mood (mệnh lệnh): "Add", "Fix", "Update"
• Ngắn gọn: < 72 ký tự nếu có thể
• Rõ ràng: Người đọc hiểu ngay mục đích

Ví dụ:

feat(auth): add JWT authentication (closes #42)
fix: resolve memory leak in worker threads
docs: update API documentation
refactor(database): optimize query performance

3.3 PR Description

Template chuẩn:

## What
[Mô tả ngắn gọn thay đổi gì]

## Why
[Lý do thực hiện thay đổi này]

## How
[Cách tiếp cận/giải pháp kỹ thuật - nếu cần]

## Changes
- Change 1
- Change 2
- Change 3

## Testing
[Hướng dẫn test hoặc test cases đã chạy]

## Screenshots/Videos
[Nếu có thay đổi UI]

## Related Issues
Closes #123
Refs #456

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
- [ ] CI/CD passes

3.4 Best practices

Kích thước PR:

• ✅ Nhỏ gọn và tập trung: 1 PR = 1 mục tiêu (1 feature hoặc 1 bugfix)
• ❌ Tránh gom nhiều thay đổi không liên quan

Trong quá trình review:

• ✅ Commit thêm để fix feedback (giữ lịch sử conversation)
• ⚠️ Tránh force push khi đang review (trừ khi thật cần thiết và thông báo)
• ✅ Reply và resolve từng comment

Sau khi merge:

• ✅ Xoá branch remote
• ✅ Cập nhật ticket/issue status

3.5 Ví dụ hoàn chỉnh

Branch: feature/PROJ-42-add-user-authentication

PR Title:

feat(auth): add user login endpoint (closes #42)

PR Description:

## What
Implement JWT-based authentication endpoint for user login

## Why
Users need secure authentication to access protected resources.
Current system lacks proper token-based auth mechanism.

## How
- Add POST /api/auth/login endpoint
- Implement JWT token generation with 24h expiration
- Add middleware for token validation
- Store refresh tokens in Redis

## Changes
- New AuthController with login method
- JWT service for token operations
- Authentication middleware
- Unit tests for auth flow

## Testing
1. POST /api/auth/login with valid credentials
2. Verify JWT token in response
3. Use token to access protected endpoint
4. Test token expiration (mock time)

## Related Issues
Closes #42
Refs #38 (related to user management)

## Checklist
- [x] Tests added/updated
- [x] Documentation updated
- [x] No breaking changes
- [x] CI/CD passes

---

4. Tóm tắt Workflow

1. Tạo branch theo convention: feature/PROJ-123-description
2. Commit thường xuyên với message chuẩn: feat: add feature
3. Push và tạo PR với title/description đầy đủ
4. Review và update dựa trên feedback
5. Merge và xoá branch sau khi hoàn thành