Tin nhắn Git Cam kết: 50/72 Định dạng

Tim Pope lập luận cho một kiểu thông điệp cam kết Git cụ thể trong bài đăng trên blog của mình: http://www.tpope.net/node/106 .

Dưới đây là một bản tóm tắt nhanh chóng về những gì ông đề nghị:

• Dòng đầu tiên là 50 ký tự hoặc ít hơn.
• Sau đó, một dòng trống.
• Văn bản còn lại nên được bọc ở 72 ký tự.

Bài đăng trên blog của anh ấy đưa ra lý do cho những khuyến nghị này (mà tôi sẽ gọi là Định dạng 50/72 định dạng cho sự ngắn gọn):

• Trong thực tế, một số công cụ coi dòng đầu tiên là dòng chủ đề và đoạn thứ hai là phần thân (tương tự như email).
• git log không xử lý gói, vì vậy rất khó đọc nếu các dòng quá dài.
• git format-patch --stdout chuyển đổi cam kết thành email - vì vậy để chơi tốt, nó sẽ giúp ích nếu các cam kết của bạn đã được bao bọc tốt đẹp.

Một điểm tôi muốn nói thêm rằng tôi nghĩ Tim sẽ đồng ý với:

• Hành động tóm tắt cam kết của bạn là một cách thực hành tốt trong bất kỳ hệ thống kiểm soát phiên bản nào. Nó giúp những người khác (hoặc sau này bạn) tìm thấy các cam kết có liên quan nhanh hơn.

Vì vậy, tôi có một vài góc độ cho câu hỏi của tôi:

• Đoạn nào (đại khái) của các nhà lãnh đạo tư tưởng của người Hồi giáo hay người dùng có kinh nghiệm, người dùng của Google có thể theo phong cách định dạng 50/72? Tôi hỏi điều này bởi vì đôi khi người dùng mới hơn không biết hoặc không quan tâm đến các hoạt động cộng đồng.
• Đối với những người không sử dụng định dạng này, có lý do nguyên tắc nào cho việc sử dụng một kiểu định dạng khác không? (Xin lưu ý rằng tôi đang tìm kiếm một cuộc tranh luận về công trạng, chứ không phải là tôi chưa bao giờ nghe nói về nó, hay tôi không quan tâm.
• Nói theo kinh nghiệm, bao nhiêu phần trăm kho Git nắm lấy phong cách này? (Trong trường hợp ai đó muốn thực hiện phân tích về kho GitHub, gợi ý, gợi ý.)

Quan điểm của tôi ở đây là không đề xuất kiểu 50/72 hoặc bắn hạ các kiểu khác. (Để cởi mở về nó, tôi thích nó hơn, nhưng tôi cởi mở với những ý tưởng khác.) Tôi chỉ muốn có được lý do tại sao mọi người thích hoặc phản đối các kiểu thông báo cam kết Git khác nhau. (Hãy thoải mái đưa ra những điểm chưa được đề cập.)

Liên quan đến dòng tóm tắt trên mạng (50 trong công thức của bạn), tài liệu nhân Linux có điều này để nói :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Điều đó nói rằng, có vẻ như những người duy trì hạt nhân thực sự cố gắng giữ mọi thứ ở khoảng 50. Đây là một biểu đồ về độ dài của các dòng tóm tắt trong nhật ký git cho kernel:

( xem kích thước đầy đủ )

Có một số ít các cam kết có các dòng tóm tắt dài hơn (một số lâu hơn) so với cốt truyện này có thể giữ mà không làm cho phần thú vị trông giống như một dòng duy nhất. (Có lẽ có một số kỹ thuật thống kê ưa thích để kết hợp dữ liệu đó ở đây nhưng ồ cũng vậy :-)

Nếu bạn muốn xem độ dài thô:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

hoặc một biểu đồ dựa trên văn bản:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Về các nhà lãnh đạo tư tưởng của người Hồi giáo: Linus chủ trương ủng hộ việc gói hàng cho thông điệp cam kết đầy đủ:

[V]] chúng tôi sử dụng các cột gồm 72 ký tự để đóng gói từ, ngoại trừ tài liệu được trích dẫn có định dạng dòng cụ thể.

Các trường hợp ngoại lệ chủ yếu đề cập đến văn bản không văn xuôi, nghĩa là văn bản không được gõ bởi con người cho cam kết - ví dụ: thông báo lỗi trình biên dịch.

Phân tách trình bày và dữ liệu ổ đĩa thông điệp cam kết của tôi ở đây.

Thông điệp cam kết của bạn không nên được gói cứng ở bất kỳ số lượng ký tự nào và thay vào đó nên sử dụng ngắt dòng để phân tách suy nghĩ, đoạn văn, v.v. như một phần của dữ liệu, không phải là bản trình bày. Trong trường hợp này, "dữ liệu" là thông điệp bạn đang cố gắng vượt qua và "bản trình bày" là cách người dùng nhìn thấy điều đó.

Tôi sử dụng một dòng tóm tắt duy nhất ở trên cùng và tôi cố gắng giữ nó ngắn gọn nhưng tôi không giới hạn bản thân ở một số tùy ý. Sẽ tốt hơn nhiều nếu Git thực sự cung cấp một cách để lưu trữ các tin nhắn tóm tắt dưới dạng một thực thể riêng biệt với tin nhắn nhưng vì tôi không phải hack một trong và tôi sử dụng ngắt dòng đầu tiên làm dấu phân cách (may mắn thay, nhiều công cụ hỗ trợ điều này có nghĩa là phá vỡ dữ liệu).

Đối với chính thông điệp, dòng mới chỉ ra một cái gì đó có ý nghĩa trong dữ liệu. Một dòng mới chỉ ra một sự khởi đầu / phá vỡ trong một danh sách và một dòng mới đôi cho thấy một ý nghĩ / ý tưởng mới.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Đây là những gì nó trông giống như trong một trình xem mềm mại bao bọc văn bản.

Đây là một dòng tóm tắt, cố gắng giữ cho nó ngắn và kết thúc bằng một ngắt dòng.

Đây là một suy nghĩ, có lẽ là một lời giải thích về những gì tôi đã làm trong định dạng có thể đọc được của con người. Nó có thể phức tạp và dài bao gồm một số câu mô tả công việc của tôi ở định dạng bài tiểu luận. Bây giờ tôi không quyết định (tại thời điểm tác giả) người dùng sẽ sử dụng dữ liệu này như thế nào.

Hai dòng ngắt tách hai suy nghĩ này. Người dùng có thể đang đọc cái này trên điện thoại hoặc màn hình rộng. Bạn đã bao giờ thử đọc văn bản được bọc 72 ký tự trên một thiết bị chỉ hiển thị 60 ký tự trên chưa? Đó là một kinh nghiệm thực sự đau đớn. Ngoài ra, câu mở đầu của đoạn này (giả sử định dạng kiểu bài tiểu luận) nên là phần giới thiệu trong đoạn văn, vì vậy nếu một công cụ chọn nó có thể không muốn tự động ngắt và cho phép bạn chỉ nhìn thấy phần đầu của mỗi đoạn. Một lần nữa, công cụ thuyết trình không phải là tôi (một tác giả ngẫu nhiên tại một thời điểm nào đó trong lịch sử) cố gắng ép định dạng cụ thể của tôi xuống cổ họng của mọi người khác.

Chỉ là một ví dụ, đây là danh sách các điểm:
* Điểm 1.
* Điểm 2.
* Điểm 3.

Sự nghi ngờ của tôi là tác giả của Git cam kết thông báo tin nhắn mà bạn đã liên kết chưa bao giờ viết phần mềm sẽ được sử dụng bởi một loạt người dùng cuối trên các thiết bị khác nhau trước đó (ví dụ: một trang web) kể từ thời điểm này trong quá trình phát triển phần mềm / điện toán ai cũng biết rằng việc lưu trữ dữ liệu của bạn với thông tin trình bày được mã hóa cứng là một ý tưởng tồi đối với trải nghiệm người dùng.

Tôi đồng ý rằng thật thú vị khi đề xuất một phong cách làm việc cụ thể. Tuy nhiên, trừ khi tôi có cơ hội để thiết lập phong cách, tôi thường làm theo những gì đã được thực hiện cho thống nhất.

Hãy xem Cam kết hạt nhân Linux, dự án bắt đầu git nếu bạn thích, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , họ không tuân theo quy tắc 50/72. Dòng đầu tiên là 54 ký tự.

Tôi sẽ nói vấn đề nhất quán. Thiết lập các phương tiện thích hợp để xác định người dùng đã thực hiện các cam kết (user.name, user.email - đặc biệt là trên các mạng nội bộ. Người dùng @ OFFICE-1-PC-10293982811111 không phải là địa chỉ liên hệ hữu ích). Tùy thuộc vào dự án, làm cho các chi tiết thích hợp có sẵn trong cam kết. Thật khó để nói những gì nên được; nó có thể là những nhiệm vụ được hoàn thành trong một quá trình phát triển, sau đó là chi tiết về những gì đã thay đổi.

Tôi không tin người dùng nên sử dụng git một cách vì các giao diện nhất định để git xử lý các cam kết theo một số cách nhất định.

Tôi cũng cần lưu ý rằng có những cách khác để tìm cam kết. Để bắt đầu, git diffsẽ cho bạn biết những gì đã thay đổi. Bạn cũng có thể làm những việc như git log --pretty=format:'%T %cN %ce'định dạng các tùy chọn git log.

Là độ dài tiêu đề tối đa được đề nghị thực sự là 50?

Tôi đã tin điều này trong nhiều năm, nhưng khi tôi nhận thấy tài liệu của "git commit" thực sự nêu rõ

$ git help commit | grep -C 1 50
      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

$  git version
git version 2.11.0

Người ta có thể lập luận rằng "ít hơn 50" chỉ có nghĩa là "không dài hơn 49".