Làm thế nào để viết một Git Commit đẹp

Làm thế nào để viết một Git Commit đẹp

Đây là bài dịch lại từ blog của Chris Beams nói về cách viết Git Commit Message, bản gốc tiếng Anh: https://chris.beams.io/posts/git-commit/

Giới thiệu: Tại sao cần commit đẹp

Nếu duyệt qua log của một Git repository bất kì, bạn có thể sẽ thấy các commit message với đủ kiểu dài ngắn khác nhau. Ví dụ, đây là những commit đầu tiên vào dự án Spring của C. Beams

$ 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 polishing

Còn đây là các commit khác thuộc cùng repository

$ 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

Bạn thích cái nào hơn?
Cái trên dài ngắn lung tung, là cách viết thường thấy của đa số anh em; cái dưới gọn gàng và nhất quán nhưng không phải ngẫu nhiên mà họ viết như thế.
Hầu như các repositories’ log đều trông như cái bên trên, nhưng vẫn có ngoại lệ. Ví dụ như Linux kernel và chính dự án Git. Thử nhìn vào Spring Boot hoặc bất kì repository nào do Tim Pope quản lý. Contributors của những repos này hiểu rằng viết một commit message “đẹp” là cách tốt nhất để thể hiện sự thay đổi trong mã nguồn với đồng nghiệp (và với chính bản thân contributor về sau). Một diff sẽ cho bạn biết cái gì đã thay đổi, nhưng chỉ có commit massage mới có thể cho biết tại sao có thay đổi đó. Peter Hutterer (không biết ông này là ai) cho rằng:

Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

Bỏ qua đoạn đầu, chỉ cần quan tâm: commit message cho biết một developer có phải là một collaborator giỏi hay không.

Nếu bạn chưa từng nghĩ đến việc tạo ra một commit đẹp có thể là vì bạn chưa dành nhiều thời gian dùng lệnh git log hay các công cụ tương tự. Luẩn quẩn là ở chỗ: Khi commit history không có cấu trúc và thiếu nhất quán, người ta sẽ không bỏ thời gian quan tâm đến nó; Và vì không quan tâm nên nó vẫn cứ phi cấu trúc và thiếu nhất quán.
Nhưng nếu nếu được quan tâm đúng mực thì log sẽ trở nên đẹp đẽ và rất hữu dụng. Những câu lệnh git blame, revert, rebase, log, shortlog… sẽ trở nên thú vị. Khi đó, việc duyệt commit và pull request của người khác sẽ rất có giá trị và có thể thực hiện độc lập. Việc hiểu được lí do của những thứ đã xảy ra từ vài tháng hoặc vài năm trước không chỉ dễ dàng mà còn hiệu quả.
Khi một dự án dài hơi kết thúc thành công và chuyển qua giai đoạn bảo trì thì đối với maintainer, không có gì đáng giá hơn log, log mà lởm khởm thì developer ăn chửi! Nên làm code thì hãy quan tâm đến cảm xúc của thằng khác, việc này có thể gây rắc rối và mất thời gian. Nhưng khi đã thành thói quen thì sẽ giúp cải thiện năng suất cho cả những người liên quan.

Trong bài này, người viết chỉ đề cập đến yếu tố cơ bản nhất của việc giữ cho commit history sạch sẽ: Làm sao để viết commit message cá nhân. Còn có những thứ quan trọng khác như commit squashing nhưng không được đề cập ở đây. Tác giả nói có thể sẽ viết trong một bài khác.

Hầu hết các ngôn ngữ lập trình đều có những quy ước nhất định để tạo nên phong cách của riêng nó như cách đặt tên, định dạng mã nguồn… Tất nhiên các qui tắc cũng có nhiều biến thể khác nhau, nhưng hầu như các developer đều đồng ý rằng chọn và gắn bó với một thứ sẽ tốt hơn để mỗi người là một kiểu, như vậy sẽ rất hỗn loạn.
Tiếp cận commit log của một team cũng không khác biệt gì. Để tạo ra được revision history “tử tế”, cả team cần phải thống nhất qui ước về nội dung commit (commit message convention), qui ước này ít nhất phải xác định được 3 điều sau:

• Style. Cú pháp, canh lề, ngữ pháp, cách viết hoa, chấm câu. Làm sao để mọi thứ trở nên đơn giản nhất có thể, để tạo ra dòng log dễ đọc dễ hiểu có thể xem xét ở mọi lúc mọi nơi.
• Content. Loại thông tin nào nên được đưa vào phần thân của commit message, loại nào không?
• Metadata. Làm sao để quản lí và tham chiếu tracking ID, pull request number…?

Hên là những qui ước này đã có sẵn đầy ra rồi, không có gì cần làm lại cả. Chỉ cần theo 7 qui tắc dưới đây, bạn sẽ commit như một chuyên gia.

Bảy qui tắc của một Git commit đẹp

1. Tách Tiêu đề khỏi phần Nội dung bằng một dòng trống
2. Giới hạn dòng Tiêu đề không quá 50 kí tự
3. Viết hoa chữ cái đầu Tiêu đề
4. Không kết thúc Tiêu đề bằng dấu chấm
5. Sử dụng câu mang tính bắt buộc trong Tiêu đề
6. Gói mỗi dòng của Nội dung trong 72 kí tự
7. Phần nội dung sẽ giải thích: Cái gì, Tại sao, Làm thế nào?

Ví dụ

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

1. Tách Tiêu đề khỏi phần Nội dung bằng một dòng trống

Trích từ git commit manpage:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.