Hướng dẫn về Git¶
Cấu hình git của bạn¶
Dựa trên kinh nghiệm truyền lại và truyền thống truyền miệng, những điều sau đây sẽ giúp ích rất nhiều trong việc làm cho commit của bạn hữu ích hơn:
Hãy chắc chắn rằng bạn đã định nghĩa cả user.email và user.name trong cấu hình git cục bộ của mình
git config --global <var> <value>
Hãy chắc chắn thêm họ tên đầy đủ của bạn vào hồ sơ Github của bạn tại đây. Cứ thoải mái làm cho nó thật ấn tượng bằng cách thêm team của bạn, avatar, câu trích dẫn yêu thích và nhiều thứ khác nữa ;-)
Cấu trúc thông điệp commit¶
Thông điệp commit gồm bốn phần: tag, module, mô tả ngắn và mô tả đầy đủ. Hãy cố gắng tuân theo cấu trúc được khuyến nghị cho 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)
Tag và tên module¶
Tag được dùng để làm tiền tố cho commit của bạn. Chúng nên là một trong các loại sau
[FIX] dành cho việc sửa lỗi: chủ yếu được dùng trong phiên bản ổn định (stable) nhưng cũng hợp lệ nếu bạn đang sửa một lỗi mới phát sinh trong phiên bản đang phát triển;
[REF] dành cho việc tái cấu trúc (refactoring): khi một tính năng được viết lại đáng kể;
[ADD] dành cho việc thêm module mới;
[REM] dành cho việc loại bỏ tài nguyên: xóa mã chết (dead code), xóa view, xóa module, ...;
[REV] dành cho việc revert commit: nếu một commit gây ra vấn đề hoặc không còn cần thiết, việc revert nó sẽ được thực hiện bằng tag này;
[MOV] dành cho việc di chuyển tệp: hãy dùng git move và không thay đổi nội dung của tệp được di chuyển, nếu không Git có thể mất dấu vết và lịch sử của tệp đó; cũng được dùng khi di chuyển mã từ tệp này sang tệp khác;
[REL] dành cho các commit phát hành (release): các phiên bản ổn định major hoặc minor mới;
[IMP] dành 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 đang phát triển là những cải tiến nhỏ, tăng dần và không liên quan đến tag khác;
[MERGE] dành cho các commit merge: được dùng khi forward port các bản sửa lỗi, nhưng cũng được dùng làm commit chính cho một tính năng bao gồm nhiều commit riêng biệt;
[CLA] dành cho việc ký Odoo Individual Contributor License;
[I18N] dành cho các thay đổi trong tệp dịch (translation files);
[PERF] dành cho các bản vá hiệu năng;
[CLN] dành cho việc dọn dẹp mã nguồn;
[LINT] dành cho các lượt chạy linter;
Sau tag là tên module bị thay đổi. Hãy 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 module bị thay đổi, hãy liệt kê chúng ra hoặc dùng various để cho biết đây là thay đổi xuyên nhiều module. Trừ khi thực sự cần thiết hoặc dễ dàng hơn, hãy tránh việc thay đổi mã trên nhiều module trong cùng một commit. Việc hiểu lịch sử của module có thể trở nên khó khăn.
Tiêu đề thông điệp commit¶
Sau tag và tên module là một tiêu đề thông điệp commit có ý nghĩa. Nó nên tự giải thích được và bao gồm lý do đằng sau sự thay đổi. Đừng dùng những từ đơn lẻ như "bugfix" hay "improvements". Hãy cố gắng giới hạn độ dài tiêu đề khoảng 50 ký tự để dễ đọc.
Tiêu đề thông điệp commit nên tạo thành một câu hợp lệ khi được ghép nối với if applied, this commit will <header>. Ví dụ [IMP] base: prevent to archive users linked to active partners là đúng vì nó tạo thành câu hợp lệ if applied, this commit will prevent users to archive....
Mô tả đầy đủ của thông điệp commit¶
Trong phần mô tả của thông điệp, hãy chỉ rõ phần mã nguồn bị ảnh hưởng bởi thay đổi của bạn (tên module, lib, đối tượng xuyên suốt, ...) và mô tả về các thay đổi đó.
Trước tiên, hãy giải thích TẠI SAO bạn thay đổi mã nguồn. Điều quan trọng nếu ai đó quay lại xem commit của bạn sau khoảng 4 thập kỷ (hoặc 3 ngày) chính là lý do bạn làm điều đó. Đó chính là mục đích của thay đổi.
Những gì bạn đã làm có thể được tìm thấy trong chính commit đó. Nếu có những lựa chọn kỹ thuật liên quan, thì cũng nên giải thích chúng 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 Odoo, tiện đây xin nói "PO team asked me to do it" không phải là một lý do hợp lệ.
Vui lòng tránh các commit ảnh hưởng đồng thời đến nhiều module. Hãy cố gắng tách thành các commit khác nhau khi các module bị ảnh hưởng là khác nhau. Điều này sẽ hữu ích nếu chúng ta cần revert thay đổi ở một module 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 sẽ chỉ nhìn 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 đờ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ờ, nhiều ngày hoặc nhiều tuần để làm việc trên những tính năng có ý nghĩa. Hãy dành chút thời gian để bình tĩnh lại và viết những thông điệp commit rõ ràng, dễ hiểu.
Nếu bạn là một nhà phát triển R&D của Odoo, phần TẠI SAO nên là mục đích của công việc bạn đang thực hiện. Đặc tả đầy đủ chính là phần cốt lõi của thông điệp commit. Nếu bạn đang làm một công việc thiếu mục đích và đặc tả, hãy cân nhắc làm rõ chúng trước khi tiếp tục.
Cuối cùng, dưới đây là một số ví dụ về thông điệp commit đúng chuẩn:
[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 phần mô tả dài để giải thích tại sao (why) chứ không phải cái gì (what), phần cái gì (what) đã có thể thấy được trong diff