Git Tamamlama İletileri: 50/72 Biçimlendirme

Tim Pope, blog gönderisinde belirli bir Git taahhüt mesajı stili olduğunu savunuyor: http://www.tpope.net/node/106 .

İşte size önerilerinin kısa bir özeti:

• İlk satır 50 karakter veya daha azdır.
• Sonra boş bir çizgi.
• Kalan metin 72 karakterle tamamlanmalıdır.

Blog yazısı bu öneriler için mantıklı (kısaca "50/72 biçimlendirme" diyeceğim):

• Uygulamada, bazı araçlar ilk satırı konu satırı, ikinci paragrafı da gövde (e-postaya benzer) olarak ele alır.
• git log sargıyı işlemez, bu nedenle satırların çok uzun olup olmadığını okumak zordur.
• git format-patch --stdout taahhütleri e-postaya dönüştürür - bu yüzden güzel oynamak, taahhütlerinizin zaten güzelce sarılmış olmasına yardımcı olur.

Eklemek istediğim bir nokta, Tim'in hemfikir olacağını düşünüyorum:

• Taahhüdünüzü özetleme eylemi, herhangi bir sürüm kontrol sisteminde doğal olarak iyi bir uygulamadır. Başkalarının (veya daha sonra) ilgili taahhütleri daha hızlı bulmasına yardımcı olur.

Yani, sorumun birkaç açısı var:

• Git'in “düşünce liderleri” veya “deneyimli kullanıcıları” ndan (kabaca) 50/72 biçimlendirme stilini benimsiyor? Bunu soruyorum çünkü bazen yeni kullanıcılar topluluk uygulamalarını bilmiyor veya umursamıyor.
• Bu biçimlendirmeyi kullanmayanlar için, farklı bir biçimlendirme stili kullanmanın temel bir nedeni var mı? (Lütfen daha önce hiç duymadım "veya" umrumda değil "değil, esaslarla ilgili bir argüman aradığımı unutmayın.)
• Ampirik olarak, Git depolarının yüzde kaçı bu stili benimsiyor? (Birinin GitHub depoları üzerinde bir analiz yapmak istemesi durumunda… ipucu, ipucu.)

Buradaki amacım 50/72 stilini tavsiye etmek veya diğer stilleri vurmak değil. (Bu konuda açık olmak için, bunu tercih ederim, ama diğer fikirlere açıkım.) Sadece insanların çeşitli Git taahhüt mesaj stillerini sevmesi veya buna karşı çıkmasının mantığını almak istiyorum. (Daha önce değinilmemiş noktaları da açabilirsiniz.)

“Özet” satırı (formülünüzdeki 50) ile ilgili olarak, Linux çekirdek belgelerinde şunlar bulunur :

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.

Bununla birlikte, çekirdek koruyucular gerçekten de 50 civarında şey tutmaya çalışıyor gibi görünüyor. İşte çekirdek için git günlüğünde özet satırlarının uzunluklarının bir histogramı:

( tam boyutlu görüntüle )

Özet satırları, ilginç bir parçayı tek bir satır gibi göstermeden, bu arsadan tutabileceğinden daha uzun (bazıları çok daha uzun) olan bir taahhütlerin dağılması vardır. (Muhtemelen bu verileri buraya dahil etmek için bazı süslü istatistiksel teknikler var ama oh iyi… :-)

Ham uzunlukları görmek istiyorsanız:

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

veya metin tabanlı bir histogram:

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

“Düşünce liderleri” ile ilgili: Linus , tam taahhüt mesajı için satır kaydırmayı kesin olarak savunur:

[…] Sözcük kaydırma için belirli bir çizgi biçimine sahip alıntılanmış malzeme hariç 72 karakterlik sütunlar kullanıyoruz.

İstisnalar temel olarak "nesir dışı" metne, yani bir insan tarafından taahhüt için yazılmamış metne, örneğin derleyici hata mesajlarına atıfta bulunur.

Sunum ve veri ayrımı, taahhüt mesajlarımı buraya yönlendirir.

İşleme mesajınız hiçbir karakter sayısında sıkı bir şekilde sarılmamalı ve bunun yerine sunumu değil verilerin bir parçası olarak düşünceleri, paragrafları vb. Ayırmak için satır sonları kullanılmalıdır. Bu durumda, "veri" karşılaşmaya çalıştığınız mesajdır ve "sunum" kullanıcının bunu nasıl gördüğünü gösterir.

Üstte tek bir özet satırı kullanıyorum ve kısa tutmaya çalışıyorum ama kendimi rasgele bir sayıyla sınırlamıyorum. Git aslında özet mesajları mesajdan ayrı bir varlık olarak saklamak için bir yol sağlamış olsaydı çok daha iyi olurdu ama bir tane kesmek zorunda olmadığım ve ilk satır sonunu ayırıcı olarak kullanıyorum (neyse ki, birçok araç desteği bu, verilerin parçalanması anlamına gelir).

Mesajın kendisi için yeni satırlar verilerde anlamlı bir şey olduğunu gösterir. Tek bir satırsonu, bir listedeki bir başlangıcı / sonu belirtir ve çift satırsonu yeni bir düşünce / fikri belirtir.

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.

Metni yumuşak bir şekilde saran bir görüntüleyicide şöyle görünür.

Bu özet bir satırdır, kısa tutmaya çalışın ve satır sonu ile bitirin.

Bu bir düşüncedir, belki de insan tarafından okunabilir biçimde yaptığımın bir açıklamasıdır. Çalışmamı makale formatında tanımlayan birkaç cümleden oluşan karmaşık ve uzun olabilir. Kullanıcının bu verileri nasıl kullanacağına şimdi (yazar zamanında) karar vermek bana bağlı değildir.

İki satır sonu bu iki düşünceyi birbirinden ayırır. Kullanıcı bunu bir telefonda veya geniş ekranlı bir monitörde okuyor olabilir. Sadece 60 karakter görüntüleyen bir cihazda 72 karakterle sarılmış metni okumaya çalıştınız mı? Gerçekten acı verici bir deneyim. Ayrıca, bu paragrafın açılış cümlesi (deneme stili biçimini varsayarak) paragrafa bir giriş olmalıdır, böylece bir araç seçerse otomatik olarak sarılmamasını ve her paragrafın başlangıcını görmenizi isteyebilir. Yine, belirli bir biçimlendirmeyi herkesin boğazını aşağıya doğru zorlamaya çalışmak, sunum aracının bana değil (tarihin bir noktasında rastgele bir yazar).

Örnek olarak, bir nokta listesi aşağıdadır:
* Nokta 1.
* Nokta 2.
* Nokta 3.

Benim şüphem Git bağlantı mesajı önerisinin yazarı, daha önce farklı cihazlarda (yani bir web sitesi) çok sayıda son kullanıcı tarafından tüketilecek bir yazılım yazmamış olduğundan, bu noktada yazılım / bilgi işlemin gelişiminde verilerinizin sabit kodlu sunum bilgileriyle birlikte depolanmasının kullanıcı deneyimi kadar kötü bir fikir olduğu iyi bilinmektedir.

Belirli bir çalışma tarzı önermenin ilginç olduğunu kabul ediyorum. Ancak, tarzı belirleme şansım olmadıkça, tutarlılık için yapılanları genellikle takip ederim.

İsterseniz git'e başlayan Linux Çekirdek Komisyonlarına bir göz attığınızda, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , 50/72 kuralına uymuyorlar. İlk satır 54 karakterdir.

Tutarlılığın önemli olduğunu söyleyebilirim. Taahhütlerde bulunan kullanıcıları tanımlamak için uygun araçları ayarlayın (kullanıcı adı, kullanıcı.eposta - özellikle dahili ağlarda. Kullanıcı @ OFFICE-1-PC-10293982811111, kullanışlı bir iletişim adresi değildir). Projeye bağlı olarak, taahhütte uygun ayrıntıyı hazırlayın. Bunun ne olması gerektiğini söylemek zor; bir geliştirme sürecinde tamamlanan görevler, daha sonra neyin değiştiğinin ayrıntıları olabilir.

Kullanıcıların git'i bir şekilde kullanması gerektiğine inanmıyorum çünkü git için belirli arayüzler taahhütleri belirli şekillerde ele alıyor.

Taahhütleri bulmanın başka yolları olduğunu da belirtmeliyim. Başlangıç ​​olarak, git diffneyin değiştiğini size söyleyecektir. git log --pretty=format:'%T %cN %ce'Seçeneklerini biçimlendirmek gibi şeyler de yapabilirsiniz git log.

Tavsiye edilen maksimum başlık uzunluğu gerçekten 50 mi?

Ben yıllardır buna inanmış, ama sadece farkına varmak gibi "git taahhüt" belgelerini aslında

$ 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

"50'den az" ifadesinin yalnızca "49'dan uzun olmayan" anlamına gelebileceği söylenebilir.