Hướng dẫn Git

Cấu hình git của bạn

Dựa trên kinh nghiệm tổ tiên và truyền thống truyền miệng, những điều sau đây sẽ giúp các commit của bạn trở nên hữu ích hơn:

  • Hãy chắc chắn định nghĩa cả user.email và user.name trong cấu hình git cục bộ của bạn

    git config --global <var> <value>
    
  • Hãy chắc chắn thêm tên đầy đủ của bạn vào hồ sơ Github của bạn ở đây. Hãy cảm thấy thú vị và thêm đội của bạn, avatar, câu trích dẫn yêu thích của bạn, và bất cứ điều gì khác ;-)

Cấu trúc thông điệp commit

Thông điệp commit có bốn phần: thẻ, mô-đun, mô tả ngắn và mô tả đầy đủ. Hãy cố gắng tuân theo cấu trúc ưa thích cho các thông điệp commit của bạn

[TAG] module: describe your change in a short sentence (ideally < 50 chars)

Long version of the change description, including the rationale for the change,
or a summary of the feature being introduced.

Please spend a lot more time describing WHY the change is being done rather
than WHAT is being changed. This is usually easy to grasp by actually reading
the diff. WHAT should be explained only if there are technical choices
or decision involved. In that case explain WHY this decision was taken.

End the message with references, such as task or bug numbers, PR numbers, and
OPW tickets, following the suggested format:
task-123 (related to task)
Fixes #123  (close related issue on Github)
Closes #123  (close related PR on Github)
opw-123 (related to ticket)

Thẻ và tên mô-đun

Thẻ được sử dụng để đặt trước commit của bạn. Chúng nên là một trong những thẻ sau

  • [FIX] để sửa lỗi: chủ yếu được sử dụng trong phiên bản ổn định nhưng cũng hợp lệ nếu bạn đang sửa một lỗi gần đây trong phiên bản phát triển;

  • [REF] để tái cấu trúc: khi một tính năng được viết lại nhiều;

  • [ADD] để thêm các mô-đun mới;

  • [REM] để xóa các tài nguyên: xóa mã không sử dụng, xóa các chế độ xem, xóa mô-đun, ...;

  • [REV] để hoàn tác commit: nếu một commit gây ra sự cố hoặc không mong muốn, việc hoàn tác sẽ được thực hiện bằng cách sử dụng thẻ này;

  • [MOV] for moving files: use git move and do not change content of moved file otherwise Git may loose track and history of the file; also used when moving code from one file to another;

  • [REL] cho các commit phát hành: phiên bản ổn định lớn hoặc nhỏ mới;

  • [IMP] cho các cải tiến: hầu hết các thay đổi được thực hiện trong phiên bản phát triển là các cải tiến gia tăng không liên quan đến thẻ khác;

  • [MERGE] cho các commit hợp nhất: được sử dụng trong việc chuyển tiếp các bản sửa lỗi nhưng cũng như là commit chính cho tính năng liên quan đến nhiều commit riêng biệt;

  • [CLA] để ký Giấy phép Người đóng góp Cá nhân của SoOn;

  • [I18N] cho các thay đổi trong tệp dịch;

Sau thẻ là tên mô-đun đã được sửa đổi. Sử dụng tên kỹ thuật vì tên chức năng có thể thay đổi theo thời gian. Nếu nhiều mô-đun được sửa đổi, liệt kê chúng hoặc sử dụng 'various' để cho biết đó là các mô-đun chéo. Trừ khi thực sự cần thiết hoặc dễ dàng hơn, tránh sửa đổi mã trên nhiều mô-đun trong cùng một commit. Hiểu lịch sử của mô-đun có thể trở nên khó khăn.

Tiêu đề thông điệp commit

After tag and module name comes a meaningful commit message header. It should be self explanatory and include the reason behind the change. Do not use single words like "bugfix" or "improvements". Try to limit the header length to about 50 characters for readability.

Tiêu đề thông điệp commit nên tạo thành một câu hợp lệ khi được nối với if applied, this commit will <header>. Ví dụ [IMP] base: ngăn chặn lưu trữ người dùng liên kết với đối tác hoạt động là đúng vì nó tạo thành một câu hợp lệ if applied, this commit will prevent users to archive....

Mô tả đầy đủ thông điệp commit

Trong mô tả thông điệp, hãy chỉ định phần mã bị ảnh hưởng bởi các thay đổi của bạn (tên mô-đun, lib, đối tượng ngang, ...) và mô tả các thay đổi.

Trước tiên, giải thích TẠI SAO bạn đang sửa đổi mã. Điều quan trọng nếu ai đó xem lại commit của bạn sau khoảng 4 thập kỷ (hoặc 3 ngày) là lý do tại sao bạn đã làm điều đó. Đó là mục đích của sự thay đổi.

Những gì bạn đã làm có thể được tìm thấy trong chính commit. Nếu có một số lựa chọn kỹ thuật liên quan, sẽ là một ý tưởng tốt để giải thích nó trong thông điệp commit sau phần lý do. Đối với các nhà phát triển R&D của SoOn, "Đội PO yêu cầu tôi làm điều đó" không phải là một lý do hợp lệ, nhân tiện.

Vui lòng tránh các commit tác động đồng thời đến nhiều mô-đun. Hãy cố gắng chia thành các commit khác nhau nơi các mô-đun bị ảnh hưởng khác nhau. Điều này sẽ hữu ích nếu chúng tôi cần hoàn tác các thay đổi trong một mô-đun cụ thể một cách riêng biệt.

Đừng ngần ngại viết dài dòng một chút. Hầu hết mọi người chỉ thấy thông điệp commit của bạn và đánh giá tất cả những gì bạn đã làm trong cuộc đời chỉ dựa trên vài câu đó. Không có áp lực gì cả.

Bạn dành nhiều giờ, ngày hoặc tuần làm việc trên các tính năng có ý nghĩa. Hãy dành một chút thời gian để bình tĩnh và viết các thông điệp commit rõ ràng và dễ hiểu.

Nếu bạn là một nhà phát triển R&D của SoOn, lý do TẠI SAO nên là mục đích của nhiệm vụ bạn đang làm. Các thông số kỹ thuật đầy đủ tạo nên phần cốt lõi của thông điệp commit. Nếu bạn đang làm việc trên một nhiệm vụ thiếu mục đích và thông số kỹ thuật, vui lòng xem xét làm rõ chúng trước khi tiếp tục.

Cuối cùng, đây là một số ví dụ về các thông điệp commit đúng:

[REF] models: use `parent_path` to implement parent_store

 This replaces the former modified preorder tree traversal (MPTT) with the
 fields `parent_left`/`parent_right`[...]

[FIX] account: remove frenglish

 [...]

 Closes #22793
 Fixes #22769

[FIX] website: remove unused alert div, fixes look of input-group-btn

 Bootstrap's CSS depends on the input-group-btn
 element being the first/last child of its parent.
 This was not the case because of the invisible
 and useless alert.

Ghi chú

Sử dụng mô tả dài để giải thích lý do tại sao chứ không phải là , cái có thể được thấy trong sự khác biệt