@aliosmanozturk
# Nguyên tắc Viết Git Commit Dành cho Các Mô hình Ngôn ngữ AI ## Các Nguyên tắc Cốt lõi 1. **Tuân thủ chuẩn Conventional Commits** (https://www.conventionalcommits.org/) 2. **Ngắn gọn và chính xác** - Không dùng ngôn từ hoa mỹ, từ ngữ so sánh bậc nhất hoặc các tính từ không cần thiết 3. **Tập trung vào CÁI GÌ đã thay đổi, chứ không phải NÓ hoạt động NHƯ THẾ NÀO** - Mô tả sự thay đổi, không sa đà vào chi tiết triển khai bên trong 4. **Mỗi commit chỉ chứa một thay đổi hợp lý về mặt logic** - Tách các thay đổi có liên quan nhưng độc lập với nhau thành các commit riêng biệt 5. **Viết ở thức mệnh lệnh (imperative mood)** - Dùng "Add feature" (Thêm tính năng) chứ không dùng "Added feature" hay "Adds feature" 6. **Luôn luôn bao gồm phần nội dung thân bài (body text)** - Tuyệt đối không tạo các commit chỉ có dòng tiêu đề (subject-only commits) ## Cấu trúc Thông điệp Commit ``` <type>(<scope>): <subject> <body> <footer> ``` ### Loại thay đổi - Type (Bắt buộc) - `feat`: Tính năng mới - `fix`: Sửa lỗi (Bug fix) - `refactor`: Thay đổi mã nguồn không sửa lỗi cũng không thêm tính năng mới - `perf`: Cải thiện hiệu năng - `style`: Thay đổi định dạng trình bày mã nguồn (căn lề, thiếu dấu chấm phẩy, v.v.) - `test`: Thêm mới hoặc cập nhật các bài kiểm thử - `docs`: Thay đổi về tài liệu - `build`: Hệ thống biên dịch hoặc các gói phụ thuộc bên ngoài (npm, gradle, Xcode, SPM) - `ci`: Thay đổi trong đường ống CI/CD - `chore`: Các tác vụ bảo trì định kỳ (gitignore, tệp cấu hình, bảo trì chung) - `revert`: Hoàn tác một commit trước đó ### Phạm vi - Scope (Tùy chọn nhưng Khuyến khích) Chỉ rõ khu vực diễn ra thay đổi: `auth`, `ui`, `api`, `db`, `i18n`, `analytics`, v.v. ### Tiêu đề - Subject (Bắt buộc) - **Tối đa 50 ký tự** - **Viết thường chữ cái đầu tiên** (trừ khi đó là danh từ riêng) - **Không đặt dấu chấm ở cuối dòng** - **Thức mệnh lệnh (Imperative mood)**: dùng "add" chứ không dùng "added" hay "adds" - **Phải cụ thể**: viết "add email validation" chứ không viết chung chung "add validation" ### Phần thân - Body (Bắt buộc) - **Luôn luôn có văn bản phần thân** - Tối thiểu 1 câu hoàn chỉnh - **Giải thích CÁI GÌ đã thay đổi và TẠI SAO** - Cung cấp ngữ cảnh rõ ràng - **Ngắt dòng ở mức 72 ký tự** - **Ngăn cách với dòng tiêu đề bằng một dòng trống** - **Sử dụng danh sách gạch đầu dòng khi có nhiều thay đổi** (dùng dấu `-` hoặc `*`) - **Tham chiếu mã số issue** nếu có liên quan - **Đề cập rõ tên các lớp/hàm/tệp cụ thể khi có liên quan** ### Phần chân - Footer (Tùy chọn) - **Thay đổi gây gãy tương thích (Breaking changes)**: `BREAKING CHANGE: <mô tả>` - **Tham chiếu issue**: `Closes #123`, `Fixes #456` - **Đồng tác giả**: `Co-Authored-By: Name <email>` ## Các Từ & Cụm từ Bị Cấm **TUYỆT ĐỐI KHÔNG sử dụng những từ sau đây** (chúng mơ hồ, mang tính chủ quan hoặc phóng đại): ❌ Comprehensive (Toàn diện) ❌ Robust (Mạnh mẽ/Vững chắc) ❌ Enhanced (Nâng cao) ❌ Improved (Cải thiện - trừ khi bạn chỉ rõ chỉ số đo lường nào đã cải thiện) ❌ Optimized (Tối ưu hóa - trừ khi bạn chỉ rõ chỉ số đo lường nào đã cải thiện) ❌ Better (Tốt hơn) ❌ Awesome (Tuyệt vời) ❌ Great (Rất tốt) ❌ Amazing (Đáng kinh ngạc) ❌ Powerful (Mạnh mẽ) ❌ Seamless (Liền mạch) ❌ Elegant (Thanh lịch) ❌ Clean (Sạch sẽ) ❌ Modern (Hiện đại) ❌ Advanced (Tiên tiến) ## Ví dụ Tốt so với Xấu ### ❌ XẤU (Không có phần thân) ``` feat(auth): add email/password login ``` **Vấn đề:** - Không có văn bản phần thân (body text) - Không giải thích những gì thực sự đã được triển khai ### ❌ XẤU (Phần thân mơ hồ) ``` feat: Add awesome new login feature This commit adds a powerful new login system with robust authentication and enhanced security features. The implementation is clean and modern. ``` **Vấn đề:** - Dùng các tính từ chủ quan (awesome, powerful, robust, enhanced, clean, modern) - Không chỉ rõ cái gì đã được thêm vào - Phần thân chỉ mô tả tính chất khen ngợi chứ không mô tả chức năng ### ✅ TỐT ``` feat(auth): add email/password login with Firebase Implement login flow using Firebase Authentication. Users can now sign in with email and password. Includes client-side email validation and error handling for network failures and invalid credentials. ``` **Tại sao ví dụ này tốt:** - Đề cập rõ công nghệ cụ thể (Firebase) - Phạm vi rõ ràng (auth) - Phần thân mô tả cụ thể chức năng nào đã được thêm vào - Giải thích rõ phần xử lý lỗi bao phủ những trường hợp nào --- ### ❌ XẤU (Không có phần thân) ``` fix(auth): prevent login button double-tap ``` **Vấn đề:** - Không có văn bản phần thân giải thích về bản sửa lỗi ### ✅ TỐT ``` fix(auth): prevent login button double-tap Disable login button after first tap to prevent duplicate authentication requests when user taps multiple times quickly. Button re-enables after authentication completes or fails. ``` **Tại sao ví dụ này tốt:** - Sử dụng thức mệnh lệnh - Mô tả vấn đề cụ thể - Phần thân giải thích cả nguyên nhân sự cố lẫn hướng giải quyết --- ### ❌ XẤU ``` refactor(auth): extract helper functions Make code better and more maintainable by extracting functions. ``` **Vấn đề:** - Mang tính chủ quan (better, maintainable) - Không nêu cụ thể những hàm nào ### ✅ TỐT ``` refactor(auth): extract helper functions to static struct methods Convert private functions randomNonceString and sha256 into static methods of AppleSignInHelper struct for better code organization and namespacing. ``` **Tại sao ví dụ này tốt:** - Mô tả thay đổi cụ thể - Đề cập chính xác tên của các hàm - Phần thân giải thích lý do và cấu trúc mới --- ### ❌ XẤU ``` feat(i18n): add localization ``` **Vấn đề:** - Không có phần thân - Quá mơ hồ ### ✅ TỐT ``` feat(i18n): add English and Turkish translations for login screen Create String Catalog with translations for login UI elements, alerts, and authentication errors in English and Turkish. Covers all user-facing strings in LoginView, LoginViewController, and AuthService. ``` **Tại sao ví dụ này tốt:** - Nêu rõ các ngôn ngữ cụ thể - Phạm vi rõ ràng (i18n) - Phần thân liệt kê những gì đã được dịch và nằm trong những tệp nào --- ## Nguyên tắc Commit Nhiều Tệp (Multi-File Commit Guidelines) ### Khi nào Cần Tách Nhỏ Commit Hãy tách các thay đổi thành các commit riêng biệt khi: 1. **Khác mối quan tâm về mặt logic (Different logical concerns)** - ✅ Commit 1: Thêm hàm mới - ✅ Commit 2: Thêm các bài kiểm thử cho hàm đó 2. **Khác phạm vi (Different scopes)** - ✅ Commit 1: `feat(ui): add button component` - ✅ Commit 2: `feat(api): add endpoint for button action` 3. **Khác loại thay đổi (Different types)** - ✅ Commit 1: `feat(auth): add login form` - ✅ Commit 2: `refactor(auth): extract validation logic` ### Khi nào Nên Gộp Chung vào Một Commit Hãy gộp các thay đổi vào cùng một commit khi: 1. **Các thay đổi gắn kết chặt chẽ với nhau (Tightly coupled changes)** - ✅ Thêm một hàm và lệnh gọi sử dụng nó trong cùng một thành phần (component) 2. **Thay đổi mang tính nguyên tử (Atomic change)** - ✅ Đổi tên một hàm xuyên suốt nhiều tệp 3. **Bị lỗi biên dịch nếu tách rời nhau (Breaking without each other)** - ✅ Thêm giao diện (interface) và lớp triển khai (implementation) của nó cùng nhau ## Chiến lược Commit ở Cấp độ Tệp ### Ví dụ: Các Thay đổi trong LoginView Nếu `LoginView` có 2 thay đổi độc lập nhau: **Thay đổi 1:** Tái cấu trúc cấu trúc stack view **Thay đổi 2:** Thêm biểu tượng báo đang tải (loading indicator) **Hãy tách thành 2 commit:** ``` refactor(ui): extract content stack view as property in login view Change inline stack view initialization to property-based approach for better code organization and reusability. Moves stack view definition from setupUI method to lazy property. ``` ``` feat(ui): add loading state with activity indicator to login view Add loading indicator overlay and setLoading method to disable user interaction and dim content during authentication. Content alpha reduces to 0.5 when loading. ``` ## Nguyên tắc Dành riêng cho Bản địa hóa (Localization) ### ✅ TỐT ``` feat(i18n): add English and Turkish translations Create String Catalog (Localizable.xcstrings) with English and Turkish translations for all login screen strings, error messages, and alerts. ``` ``` build(i18n): add Turkish localization support Add Turkish language to project localizations and enable String Catalog generation (SWIFT_EMIT_LOC_STRINGS) in build settings for Debug and Release configurations. ``` ``` feat(i18n): localize login view UI elements Replace hardcoded strings with NSLocalizedString in LoginView for title, subtitle, labels, placeholders, and button titles. All user-facing text now supports localization. ``` ### ❌ XẤU ``` feat: Add comprehensive multi-language support Add awesome localization system to the app. ``` ``` feat: Add translations ``` ## Thay đổi Gây Gãy Tương thích (Breaking Changes) Khi đưa vào các thay đổi làm gãy tính tương thích ngược: ``` feat(api): change authentication response structure Authentication endpoint now returns user object in 'data' field instead of root level. This allows for additional metadata in the response. BREAKING CHANGE: Update all API consumers to access response.data.user instead of response.user. Migration guide: - Before: const user = response.user - After: const user = response.data.user ``` ## Thứ tự Sắp xếp Các Commit (Commit Ordering) Khi chuẩn bị nhiều commit, hãy sắp xếp chúng theo trình tự hợp lý: 1. **Các gói phụ thuộc đi trước (Dependencies first)**: Thêm thư viện/cấu hình trước khi sử dụng 2. **Nền tảng đi trước tính năng (Foundation before features)**: Các mô hình dữ liệu (Models) đi trước giao diện hiển thị (Views) 3. **Cấu hình biên dịch đi trước mã nguồn (Build before source)**: Cấu hình build đi trước các thay đổi trong mã nguồn 4. **Hàm tiện ích đi trước nơi sử dụng (Utilities before consumers)**: Các hàm bổ trợ (Helpers) đi trước các thành phần gọi chúng ### Ví dụ về Trình tự Commit: ``` 1. build(auth): add Sign in with Apple entitlement Add entitlements file with Sign in with Apple capability for enabling Apple ID authentication. 2. feat(auth): add Apple Sign-In cryptographic helpers Add utility functions for generating random nonce and SHA256 hashing required for Apple Sign-In authentication flow. 3. feat(auth): add Apple Sign-In authentication to AuthService Add signInWithApple method to AuthService protocol and implementation. Uses OAuthProvider credential with idToken and nonce for Firebase authentication. 4. feat(auth): add Apple Sign-In flow to login view model Implement loginWithApple method in LoginViewModel to handle Apple authentication with idToken, nonce, and fullName. 5. feat(auth): implement Apple Sign-In authorization flow Add ASAuthorizationController delegate methods to handle Apple Sign-In authorization, credential validation, and error handling. ``` ## Các Trường hợp Đặc biệt ### Các Tệp Cấu hình (Configuration Files) ``` chore: ignore GoogleService-Info.plist from version control Add GoogleService-Info.plist to .gitignore to prevent committing Firebase configuration with API keys. ``` ``` build: update iOS deployment target to 15.0 Change minimum iOS version from 14.0 to 15.0 to support async/await syntax in authentication flows. ``` ``` ci: add GitHub Actions workflow for testing Add workflow to run unit tests on pull requests. Runs on macOS latest with Xcode 15. ``` ### Tài liệu (Documentation) ``` docs: add API authentication guide Document Firebase Authentication setup process, including Google Sign-In and Apple Sign-In configuration steps. ``` ``` docs: update README with installation steps Add SPM dependency installation instructions and Firebase setup guide. ``` ### Tái cấu trúc Mã nguồn (Refactoring) ``` refactor(auth): convert helper functions to static struct methods Wrap Apple Sign-In helper functions in AppleSignInHelper struct with static methods for better code organization and namespacing. Converts randomNonceString and sha256 from private functions to static methods. ``` ``` refactor(ui): extract email validation to separate method Move email validation regex logic from loginWithEmail to isValidEmail method for reusability and testability. ``` ### Hiệu năng (Performance) **Chỉ rõ mức độ cải thiện đạt được:** ❌ `perf: optimize login` ✅ ``` perf(auth): reduce login request time from 2s to 500ms Add request caching for Firebase configuration to avoid repeated network calls. Configuration is now cached after first retrieval. ``` ## Yêu cầu Đối với Văn bản Phần thân (Body Text Requirements) **Các yêu cầu tối thiểu cho văn bản phần thân:** 1. **Ít nhất 1-2 câu hoàn chỉnh** 2. **Mô tả cụ thể CÁI GÌ đã được thay đổi** 3. **Giải thích TẠI SAO thay đổi đó lại cần thiết (khi không hiển nhiên)** 4. **Đề cập các thành phần/tệp bị ảnh hưởng khi có liên quan** 5. **Bao gồm các chi tiết kỹ thuật không thể hiện rõ trên dòng tiêu đề** ### Ví dụ Phần thân Tốt: ``` Add loading indicator overlay and setLoading method to disable user interaction and dim content during authentication. ``` ``` Update signInWithApple method to accept fullName parameter and use appleCredential for proper user profile creation in Firebase. ``` ``` Replace hardcoded strings with NSLocalizedString in LoginView for title, labels, placeholders, and buttons. All UI text now supports English and Turkish translations. ``` ### Ví dụ Phần thân Xấu: ❌ `Add feature.` (quá mơ hồ) ❌ `Updated files.` (không giải thích cập nhật cái gì) ❌ `Bug fix.` (không giải thích sửa lỗi nào) ❌ `Refactoring.` (không giải thích tái cấu trúc cái gì) ## Khung Mẫu Dành cho Các Mô hình AI (Template for AI Models) Khi một mô hình AI được yêu cầu tạo các thông điệp commit: ``` 1. Đọc git diff để hiểu TOÀN BỘ các thay đổi 2. Nhóm các thay đổi theo từng mối quan tâm logic 3. Sắp xếp thứ tự các commit theo mối quan hệ phụ thuộc 4. Đối với mỗi commit: - Chọn loại (type) và phạm vi (scope) phù hợp - Viết tiêu đề (subject) cụ thể, ngắn gọn (tối đa 50 ký tự) - Viết phần thân (body) chi tiết (tối thiểu 1-2 câu, bắt buộc) - Sử dụng thức mệnh lệnh (imperative mood) - Tránh các từ bị cấm - Tập trung vào CÁI GÌ đã thay đổi và TẠI SAO 5. Định dạng đầu ra: ## Commit [N] **Title:** ``` type(scope): subject ``` **Description:** ``` Body text explaining what changed and why. Mention specific components, classes, or methods affected. Provide context. ``` **Files to add:** ```bash git add path/to/file ``` ``` ## Danh sách Kiểm tra Cuối cùng (Final Checklist) Trước khi đề xuất một thông điệp commit, hãy xác minh: - [ ] Loại thay đổi (Type) đã chính xác (feat/fix/refactor/v.v.) - [ ] Phạm vi (Scope) cụ thể và có ý nghĩa - [ ] Tiêu đề (Subject) viết ở thức mệnh lệnh - [ ] Tiêu đề dài ≤50 ký tự - [ ] **Có văn bản phần thân (Body text - bắt buộc)** - [ ] **Phần thân có ít nhất 1-2 câu hoàn chỉnh** - [ ] Phần thân giải thích rõ CÁI GÌ và TẠI SAO - [ ] Không sử dụng bất kỳ từ bị cấm nào - [ ] Không sử dụng các tính từ mang tính chủ quan - [ ] Nêu cụ thể về CÁI GÌ đã thay đổi - [ ] Đề cập các thành phần/tệp bị ảnh hưởng - [ ] Mỗi commit chỉ chứa một thay đổi hợp lý về mặt logic - [ ] Các tệp được nhóm lại chính xác --- ## Ví dụ Thông điệp Commit Hoàn chỉnh ``` feat(auth): add email validation to login form Implement client-side email validation using regex pattern before sending authentication request. Validates format matches standard email pattern (user@domain.ext) and displays error message for invalid inputs. Prevents unnecessary Firebase API calls for malformed emails. ``` **Điều gì làm nên một commit tốt ở ví dụ này:** - Loại thay đổi (type) và phạm vi (scope) rõ ràng - Tiêu đề cụ thể - Phần thân giải thích bước xác thực thực hiện việc gì - Phần thân giải thích tại sao việc này lại cần thiết - Đề cập rõ lợi ích mang lại (ngăn chặn các lệnh gọi API không cần thiết) - Không dùng từ bị cấm - Sử dụng thức mệnh lệnh xuyên suốt toàn bộ thông điệp --- **Hãy nhớ:** Một thông điệp commit tốt phải giúp người đọc hiểu được sự thay đổi mà không cần phải mở bản so sánh mã nguồn (diff) ra xem. Hãy cụ thể, ngắn gọn, khách quan và luôn luôn đính kèm văn bản phần thân có ý nghĩa.
