Quy ước khi sử dụng Git – Git conventions

Nếu bạn đang là một developer, chắc chắn bạn cũng đang sử dụng Git hàng ngày để quản lý hệ thống version cho mã nguồn của bạn. Việc sử dụng công cụ này rất quan trọng với quá trình phát triển ứng dụng, dù là làm việc theo nhóm hay làm việc cá nhân. Tuy nhiên, các bạn có thể đã gặp các repository lộn xộn với các commit không được rõ ràng và không truyền tải được các thông tin hữu ích, cũng như việc lạm dụng(misuse) các nhánh, cùng 1 số vấn đề khác. Biết cách sử dụng Git chính xác và tuân theo các phương pháp hay là điều cần thiết đối với tất cả các developer. Hôm nay mình sẽ cùng các bạn đi qua 1 số nguyên tắc trong quá trình sử dụng Git.

Quy ước đặt tên cho các nhánh (Naming conventions for Git branches)

Khi chúng ta làm việc với code versioning, việc đảm bảo quy trình làm việc ngắn gọn cho tất cả các thành viên trong nhóm là điều cần thiết. Ngoài việc đạt được năng suất, việc tài liệu hóa (documenting) quá trình phát triển của dự án còn giúp đơn giản hóa việc làm việc nhóm. Bằng việc làm theo những thực hành bên dưới, bạn sẽ sớm thấy được lợi ích của nó trong quá trình làm việc.

Dựa vào điều đó, cộng đồng đã tạo ra quy ước đặt tên nhánh mà bạn có thể tuân theo trong dự án của mình. Việc sử dụng các quy ước dưới đây là tùy chọn(optional) nhưng chúng có thể giúp cải thiện kỹ năng của bạn.

1. Viết thường (Lowercase): không sử dụng chữ in hoa trong tên nhánh, chỉ dùng chữ thường(trừ trường hợp tên nhánh đặt theo ký tự viết tắt theo ID của ticket/task).
2. Sử dụng gạch nối (Hyphen separated): nếu tên nhánh nhiều hơn 1 từ, hãy phân tách chúng bằng dấu gạch nối tuân theo nguyên tắc kebab-case. Tránh việc sử dụng PascalCase, CamelCase hoặc Snake_case trong khi tạo tên nhánh.
3. Chỉ sử dụng ký tự a-z, 0-9: Chỉ sử dụng các ký tự chữ và số cùng với dấu gạch nối trong tên nhánh của bạn. Tránh mọi ký tự không phải là chữ và số.
4. Không sử dụng dấu gạch nối liên tục (–): Nếu bạn có các loại nhánh (branch type) thì bạn nên sử dụng dạng tiền tố (prefix) và dấu gạch chéo (/) để ngăn cách. Ví dụ: feature/feature-1, bugfix/bugfix-1, hotfix/hotfix-1,…
5. Tránh việc kết thúc tên nhánh bằng dấu gạch nối: Nó không có ý nghĩ vì dấu gạch nối được dùng để ngăn cách các từ và không có từ nào ở cuối cần để phân tách.
6. Sử dụng các tên mô tả, ngắn gọn và rõ ràng để giải thích những gì được thực hiện trên nhánh của bạn.

Bad branch names:
fixSidebar
feature-new-sidebar-
FeatureNewSidebar
feat_add_sidebar

Good branch names:

bugfix/sidebar
feature/new-sidebar
hotfix/interval-query-param-on-get-historical-data

Tiền tố quy ước tên nhánh (Branch Names Convention Prefixes)

Đôi khi mục đích của một nhánh không rõ ràng. Đó có thể là một tính năng mới (feature), sửa lỗi (bug fix), cập nhật tài liệu hoặc bất cứ điều gì khác. Để giải quyết vấn đề này, cách phổ biến là sử dụng tiền tố trên tên nhánh để giải thích nhanh mục đích của nhánh. Dưới đây là 1 số tiền tố thường được sử dụng:

• feature: tiền tố này được sử dụng để truyền tải một tính năng mới sẽ được phát triển. Ví dụ: feature/add-filters;
• release: được sử dụng để chuẩn bị cho 1 bản phát hành(release) mới. Tiền tố release/ thường được sử dụng để thực hiện các tác vụ cuối cùng trước khi thực hiện hợp nhất(merging) các bản cập nhật mới nhất từ nhánh chính(master) để tạo 1 bản release. Ví dụ: release/v1.0.0.1-beta;
• bugfix: được sử dụng để truyền tải thông điệp bạn đang giải quyết 1 lỗi trong code và lỗi này thường liên quan đến 1 vấn đề hoặc chức năng nào đó. Ví dụ: bugfix/sign-in-flow;
• hotfix: tương tự như bugfix, nhưng nó liên quan đến việc sửa một lỗi nghiêm trọng trên môi trường production. Ví dụ: hotfix/cors-error;
• docs: được sử dụng trong trường hợp bạn cần viết một số tài liệu. Ví dụ: docs/quick-start;

Nếu bạn đang làm việc trên 1 hệ thống có tính năng quản lý tác vụ như Jira, Trello, ClickUp hoặc bất kỳ công cụ tương tự nào khác có thể tạo User Stories và mỗi card có một số liên kết(number associated). Khi đó, chúng ta thường sử dụng những số này ở đầu tên của nhánh. Ví dụ:

• feature/T-531-add-sidebar
• docs/T-789-update-readme
• hotfix/T-142-security-path

Commit Message

Commit message thực sự rất quan trọng trong quá trình phát triển (development process). Việc tạo ra một lịch sử tốt sẽ giúp ích cho các bạn rất nhiều trong hình trình của mình (giả sử trong quá trình phát triển bạn cần xem lại lịch sử làm việc trước đó). Giống như khi tạo branch, các commit cũng có các quy ước do cộng đồng đặt ra mà các bạn có thể tìm hiểu bên dưới:

• Một commit có 3 phần quan trọng: subject, description, footer. Trong đó subject là phần bắt buộc và nó xác định mục đích của một commit. Description được sử dụng để cung cấp bối cảnh và giải thích bổ sung cho mục đích của commit (trong trường hợp bạn muốn giải thích rõ ràng hơn cho commit của mình). Cuối cùng là footer, thường được sử dụng cho metadata như chỉ định 1 commit. Mặc dù việc sử dụng description và footer được coi như là một cách làm tốt nhưng cả 2 phần này là không bắt buộc (nếu tiêu đề đã đủ ý nghĩa thì bạn có thể bỏ qua description và footer).

• Sử dụng dạng mệnh lệnh trong subject. Ví dụ:

Good:
Add README.md ✅;

Bad:
Added README.md ❌;
Adding README.md ❌;

• Viết hoa chữ cái đầu tiên của subject. Ví dụ:

Good:
Add user authentication ✅;
Bad:
add user authentication ❌;

• Không kết thúc dòng subject bằng dấu chấm. Ví dụ:

Good
Update unit tests ✅;
Bad
Update unit tests. ❌;

• Giới hạn độ dài của subject không quá 50 ký tự, đảm bảo tính ngắn gọn và rõ ràng(nếu cần mô tả thêm thì sử dụng description).
• Phần description không quá 72 ký tự và ngăn cách với subject bằng 1 dòng trống.
• Nếu nội dung của commit có nhiều hơn 1 đoạn (paragraph), hãy sử dụng các dòng trống để phân tách chúng.
• Nếu cần thiết, bạn có thể sử dụng bullet points thay cho paragraph.

Cấu trúc Commit

<type>[optional scope]: <subject>

[optional description(body)]

[optional footer(s)]

Commit type

Commit type cung cấp bối cảnh rõ ràng về những gì được thực hiện trong commit. Dưới đây là danh sách các loại commit và thời điểm sử dụng chúng:

• feat: Khi thêm các tính năng mới;
• fix: Sửa các lỗi của phần mềm;
• refactor: Được sử dụng để thay đổi code nhưng vẫn đảm bảo chức năng tổng thể của nó.
• choro: Các cập nhật không ảnh hưởng đến production code, liên quan đến việc điều chỉnh tool, cấu hình (config) hoặc thư viện.
• docs: Bổ sung hoặc sửa đổi các tài liệu;
• perf: Thay đổi code để nâng cao hiệu suất (performance);
• style: Các điều chỉnh liên quan đến định dạng và khoảng trắng (cách trình bày của code);
• test: Bao gồm hoặc sửa chữa các test;
• build: Các sửa đổi ảnh hưởng đến hệ thống build hoặc các phần phụ thuộc bên ngoài;
• ci: Thay đổi các tệp hoạc tập lệnh cấu hình CI;
• env: Mô tả các điều chỉnh hoặc bổ sung cho tệp cấu hình trong quy trình CI, chẳng hạn như các tham số cấu hình vùng chứa (container).

Scope

Phạm vi là một cấu trúc có thể được thêm vào sau commit type để cung cấp thêm thông tin theo ngữ cảnh. Ví dụ:

fix(ui): resolve issue with button alignment

feat(auth): implement user authentication

Description/Body

Nội dung của 1 commit cung cấp các giải thích chi tiết về những thay đổi được đưa ra bởi commit. Nó thường được thêm vào sau một dòng trống sau dòng chủ đề (subject).

feat: Add new functionality to handle user authentication.

This commit introduces a new module to manage user authentication. It includes functions for user login, registration, and password recovery.

Footer

Footer của một commit được sử dụng để cung cấp thêm thông tin liên quan đến commit. Nó có thể bao gồm các chi tiết như ai đã xem xét (review) hoặc phê duyệt (approve) các thay đổi của commit. Ví dụ:

Signed-off-by: John <john.doe@example.com>
Reviewed-by: Anthony <anthony@example.com>

Breaking Change

Cho biết rằng commit bao gồm những thay đổi quan trọng có thể dẫn đến các vấn đề về tương thích hoặc yêu cầu sửa đổi mã phụ thuộc (dependent code). Bạn có thể thêm BREAKING CHANGE vào footer hoặc thêm dấu ! phía sau type/scope của commit. Ví dụ

chore!: drop support for Node 18

Ví dụ một commit có đầy đủ các thành phần subject, body, footer

feat: add function to convert colors in hexadecimal to rgba

Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.

Reviewed-by: huu.dao<huu.dao@example.com>
Refs: #345