Tại sao lại cần quan tâm đến nội dung của commit message
Trong hầu hết các dự án thì chúng ta có thể thấy rằng các nội dung commit ít nhiều rất lộn xộn. Ví dụ như hình ảnh commit phía trên. Trong dự tôi đã từng tham gia, một nội dung rất buồn cười đã được đưa vào nội dung của commit. Trước ngày nghỉ lễ mùng 2 tháng 9, một thành viên dự án sau khi fix một bug của dự án đã commit code với nội dung là "Chào mừng ngày quốc khánh mùng 2 tháng 9" LOL. Hoặc bạn thử sục sạo vào các dự án lớn và chuyên nghiệp như `Spring` thì cũng có thể tìm thấy nhiều nội dung commit khá là dài dòng, vô nghĩa và không rõ ràng như sau.
Dangs-MacBook-Pro:spring-framework hadv$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"
e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishingThật sự là một ác mộng nếu nhìn vào những nội dung commit như trên. So sánh, với những nội dung commit gần đây hơn của dự án thì thấy rằng nội dung commit đã được tổ chức một cách tốt hơn.
$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"
5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage
Rất ngắn gọn và rõ ràng phải không? Đây chính là mục tiêu mà chúng ta sẽ hướng tới. Viết commit code sao cho ngắn gọn, súc tích và đầy đủ ý nghĩa. Nếu cần mô tả chi tiết thì chúng ta nên bổ sung vào phần body của message hơn là giải thích dài dòng trong tiêu đề của commit.
Khi chúng ta nhận thức được rằng nội dung commit là một phương pháp giao tiếp hiệu quả trong môi trường làm việc cộng tác trong dự án có nhiều thành viên thì chúng ta sẽ thấy tầm quan trọng của việc viết nội dung commit một cách ngắn gọn và ý nghĩa. Và các thành viên trong dự án có thể nắm bắt được nội dung thay đổi của source code thông qua nội dung commit. Nhìn vào nội dung commit của một người chúng ta có thể đánh giá được phần nào các thành viên của dự án có tố chất làm việc nhóm tốt hay không.
Thông thường, để có được nội dung commit tốt và ý nghĩa, các nhóm làm việc sẽ đưa ra một số quy định khi viết nội dung dựa trên các tiêu chí sau đây:
1. Các quy định về việc trình bày và sử dụng ngôn ngữ trong nội dung commit như: các từ khoá, ngữ pháp (chủ động hay bị động), khi nào cần viết hoa, sử dụng các ký tự đặc biệt hay dấu chấm câu....
2. Nội dung nào cần được mô tả chi tiết trong nội dung của message (nếu có)?, nội dung nào không cần?
3. Quy định về chỉ định hay tham chiếu đến các nội dung khác như: id của issue, id của pull-request, commit hash hay bất kỳ nội dung nào có thể tham chiếu đến.
Để có được nội dung commit tốt, chúng ta có thể tuân theo các quy tắc sau đây
7 quy tắc để cần có để viết nội dung git commit hiệu quả
1. Tách biệt tiêu đề và nội dung commit bằng một dòng trắng
Tuy không phải commit nào cũng cần phải có nội dung chi tiết về commit nhất là đối với những commit có nội dung thay đổi không nhiều thì tiêu đề đã là đủ để thể hiện được nội dung thay đổi rồi. Ví dụ như nội dung commit sau đây
Fix typo in introduction to user guideNội dung commit như trên đã đầy đủ, nếu ai đó muốn xem chi tiết lỗi chính tả là gì thì họ có thể sử dụng `git show`, `git diff` hoặc `git log -p` để xem chi tiết hơn nội dung thay đổi.
Đối với những commit có nội dung thay đổi đơn giản thì chúng ta chỉ cần chỉ định nội dung tiêu đề của commit bằng lệnh `git commit -m` như sau
$ git commit -m "Fix typo in introduction to user guide"Còn đối với những nội dung commit cần mô tả chi tiết thì chúng ta không đơn giản chỉ dùng `git commit -m` mà chúng ta cần sử dụng một trình soạn thảo để bổ sung nội dung chi tiết khi thực hiện commit. Khi đó thì nội dung commit sẽ được hiển thị chi tiết khi xem lịch sử commit bằng `git log` như sau:
$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date: Fri Jan 01 00:00:00 1982 -0200
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.Nếu bạn chỉ muốn xem nhanh nội dung tiêu đề của từng commit thì có thể sử dung `git log --oneline`
$ git log --oneline
42e769 Derezz the master control programHoặc bạn cũng có thể sủ dụng `git shortlog` để hiện thị nội dung tiêu đề của từng commit nhưng được nhóm theo tên từng thành viên của dự án
$ git shortlog
Kevin Flynn (1):
Derezz the master control program
Alan Bradley (1):
Introduce security program "Tron"
Ed Dillinger (3):
Rename chess program to "MCP"
Modify chess program
Upgrade chess program
Walter Gibbs (1):
Introduce protoype chess program2. Viết tiêu đề commit ngắn gọn và súc tích, tối đa khoảng 50 chữ
Tất nhiên, chúng ta không cần thiết phải quá cứng nhắc trong việc chỉ sử dụng tối đa 50 chữ cái, đây là chỉ một quy tắc mang tính hình thức để giúp chúng ta suy nghĩ một cách thấu đáo để có thể mô tả nội dung một cách súc tích trước khi commit và kết quả là chúng ta sẽ có những nội dung commit dễ đọc cho toàn dự án.
Một điểm bạn có thể chú ý là GitHub sẽ chỉ hiện thị khoảng 69 ký tự cho mỗi commit, phần vượt quá sẽ được cắt đi và hiển thị bằng dấu `...` nên chúng ta có thể coi 69 ký tự là một quy định cứng và chúng ta chỉ nên viết comment tối đa là 69 ký tự.
3. Viết hoa chữ cái đầu tiên của tiêu đề commit
4. Không kết thúc tiêu đề bằng dấu `.`
5. Sử dụng câu mệnh lệnh khi viết tiêu đề commit
Nên sử dụng câu mệnh lệnh hay câu chỉ dẫn khi viết nội dung commit. Vi dụ như những câu mệnh lệnh đơn giản như sau
- Clean the room
- Close the door
- Take out the trash
Câu mệnh lệnh đôi khi nghe có vẻ thô lỗ và cục cằn nên chúng ta ít sử dụng trong cuộc sống hàng ngày. Tuy nhiên, với nội dung `git commit` thì đó là 1 lựa chọn tốt và hiệu quả. Bản thân các commit mặc định của git cũng sử dụng những câu mệnh lệnh. Ví dụ như khi merge hay revert một commit thì git sử dụng tiêu đề commit như sau
Merge branch 'myfeature'
Revert "Add the thing with the stuff"
This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.Hoặc khi thực hiện merge một `pull request` trên GitHub thì nội dung commit sẽ là như sau
Merge pull request #123 from someuser/somebranch6. Wrap nội dung chi tiết của commit ở vị trí 72 ký tự
Git không tự động wrap nội dung văn bản cho nội dung commit nên để có thể xem nội dung commit được dễ dàng thì chúng ta nên tự xuống dòng khi một dòng dài quá 72 ký tự. Một số IDE thì cung cấp sẵn công cụ để chúng ta có thể tự động xuống dòng khi biên tập hay hiển thị nội dung commit.
7. Sử dụng nội dung commit để mô tả chi tiết nội dung thay đổi (what, why, how,...)
Đối với những nội dung thay đổi lớn và khó hiểu thì chúng ta nên mô tả chi tiết trong nội dung commit để các thành viên trong dự án có thể dễ dàng nắm bắt được thông tin, đây là cũng là cách để có thể giao tiếp hiệu quả trong khi thực hiện dự án. Hoặc chúng ra có thể sử dụng cách tham chiếu đến tài liệu khác mô tả về nội dung thay đổi.
Dưới đây là một ví dụ về một nội dung commit chi tiết
commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date: Fri Aug 1 22:57:55 2014 +0200
Simplify serialize.h's exception handling
Remove the 'state' and 'exceptmask' from serialize.h's stream
implementations, as well as related methods.
As exceptmask always included 'failbit', and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).
As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().
fail(), clear(n) and exceptions() are just never called. Delete
them.
Bình luận