En Sevdiğim Git Commit’im (2019)

En Sevdiğim Git Commit’im

• Git commit mesajlarının önemini vurguluyor ve bunların bir kod tabanını belgelemede en güçlü araçlardan biri olduğunu düşünüyor.
• Bunun nedenini açıklamak için geliştirici Dan Carley’nin yazdığı "Convert template to US-ASCII to fix error" commit’ini örnek veriyor.
• GDS’de (Government Digital Service) edindiği deneyime dayanarak, açık şekilde kod yazmanın avantajlarından birinin bu tür örneklerin kurum dışıyla da paylaşılabilmesi olduğunu söylüyor.

Bu commit neden iyi?

• Commit mesajı ile kod değişikliklerinin oranı eğlenceli olsa da, bunu paylaşmaya değer kılan neden bu değil.
• Başka bir kurumda ya da başka bir geliştiricide olsaydı, bu commit mesajı muhtemelen sadece change whitespace veya fix bug diye özetlenebilirdi.
• Bunun yerine Dan, çevresindeki insanlar için gerçekten faydalı bir commit mesajı hazırlamaya zaman ayırmış.

Değişiklik nedenini açıklıyor

• En iyi commit mesajları yalnızca neyin değiştiğini değil, neden değiştiğini de açıklar.
• Bu commit’te, /etc/nginx/router_routes.conf içeriğini eşleştirmek için eklenen testin bundle exec rake ile çalıştırıldığında neden ArgumentError: invalid byte sequence in US-ASCII hatasıyla başarısız olduğunu ayrıntılı biçimde açıklıyor.
• Bu tür bilgiler belgelenmeye çok değerlidir; insanlar ilk bağlamı unuttukça ya da başka ekiplere geçip kurumdan ayrıldıkça kolayca kaybolabilir.

Aranabilir

• Commit mesajının ilk bölümünde değişikliği tetikleyen hata mesajı yer alıyor; böylece herkes kod tabanında git log --grep "invalid byte sequence" çalıştırarak veya GitHub’daki commit aramasını kullanarak bu hatayı arayabilir.
• Gerçekten de birçok kişi bu sorunu arayıp daha önce kimin fark ettiğini ve bununla nasıl başa çıktığını öğrenebilmiş.

Bir hikâye anlatıyor

• Commit mesajı, sorunun nasıl göründüğüne, inceleme sürecinin nasıl ilerlediğine ve çözümün nasıl bulunduğuna dair ayrıntılar içeriyor.
• Commit mesajları, belirli bir dosyayı, fonksiyonu ya da kod satırını belgelemekten çok, kod tabanının geçirdiği yolculuğa dair ek bilgileri belgelemek için son derece uygundur.

Herkesi biraz daha akıllı yapıyor

• Dan’in her adımda çalıştırdığı komutları belgelemesi, ekip içinde bilgiyi paylaşmanın hafif ama etkili bir yolu olabilir.
• Bu commit mesajını okuyan biri, Unix araç seti hakkında birkaç faydalı ipucu öğrenebilir.
• Bu değişikliği inceleyenler de, daha sonra bu commit’i bulanlar da bunları öğrenebilir.

Empati ve güven inşa ediyor

• Son paragraf insani bir bağlam ekliyor.
• Bunu okuduğunuzda, Dan’in sinsi bir bug’ın izini sürmek için bir saat harcarken yaşadığı hayal kırıklığını ve sonunda çözdüğünde duyduğu tatmini hissedebiliyorsunuz.
• Bu tür commit mesajları, her değişikliğin arkasında elinden gelen en iyi kararı vermeye çalışan bir insan olduğunu hatırlamaya yardımcı olur.

İyi commit’lerin önemi

• Bu örnek uç bir durum ve her commit’in bu kadar ayrıntılı olmasını beklemiyor.
• Ancak bu, bir değişikliğin arkasındaki bağlamı açıklamanın, başkalarının bir şeyler öğrenmesine yardımcı olmanın ve kod tabanına dair ekibin kolektif zihinsel modeline katkıda bulunmanın harika bir örneği.
• İyi commit mesajlarının faydaları ve bunları daha kolay yapılandırmaya yardımcı olan araçlar hakkında daha fazla bilgi edinmek isterseniz, Joel Chippindale’ın "Telling stories through your commits" ve Tekin Süleyman’ın "A branch in time" yazılarını öneriyor.

GN⁺ görüşü

• Bu yazı, Git commit mesajlarının önemini vurgulayarak commit mesajlarının kod tabanının geçmişini belgelemek ve bilgiyi paylaşmak için ne kadar güçlü bir araç olabileceğini gösteriyor.
• Dan Carley’nin commit mesajı; değişiklik nedeni, aranabilirlik, hikâye anlatımı, bilgi paylaşımı, empati ve güven inşası gibi birçok açıdan örnek bir vaka sunuyor.
• İyi commit mesajları yazmanın önemini anlayıp bunu uygulayan geliştiriciler, daha iyi iş birliği ve kod bakım deneyimi yaşayabilir; bu da ekibin genel üretkenliğini ve verimliliğini artırmaya katkı sağlayabilir.

[GN⁺]

Hacker News görüşü

• GitHub kurucu ortağının görüşü:

  • Git commit mesajları kodu belgelemenin benzersiz bir yolu, ancak iyi optimize edilmemiş.
  • Araçların çoğu commit mesajının yalnızca ilk satırını gösteriyor.
  • Git, commit mesajlarını e-posta gövdesi gibi projedeki herkesin okuyabilmesi için tasarladı, ancak pratikte bunlar neredeyse hiç görülmüyor.
  • git blame kullanarak ilgili commit mesajını bulmak da zor.
  • Git projesinin commit mesajları çok ayrıntılı, ama gerçekte neredeyse hiç kullanılmıyor.
  • Git üzerinden mükemmel dokümantasyon yazmak, çoğu toplulukta neredeyse zaman kaybına yakın.

• Belirli sorunlar için commit mesajlarının önemi:

  • Sorunu açıkça anlatan commit mesajı ilk satırı önemli.
  • Gerekirse ek bilgi sağlayan geri kalan kısım okunabilir.

• Commit mesajlarına dair kişisel hisler:

  • Harika commit mesajları yazmaktan gurur duyulsa da, bunun başkaları için gerçekten değerli olup olmadığından emin olunmuyor.
  • Çoğu insan commit mesajlarında neredeyse hiç arama yapmıyor.
  • Güzel commit mesajları programcının kibri olabilir ve somut bir değeri olmayabilir.

• Commit mesajının ilk satırını yazma stratejisi:

  • git log kullanılırken en önemli kısım ilk satır.
  • İlk satırda ne yapıldığı değil, neden yapıldığı belirtilmeli.
  • Bir haber yazısında olduğu gibi, en önemli bilgiden ayrıntılara doğru ilerlemek iyi olur.

• Commit mesajlarını düzeltmenin zorluğu:

  • Commit mesajlarını yazdıktan sonra düzeltmek zor.
  • .md dosyaları ya da wiki, Confluence gibi belgeler kolayca düzenlenebilir.
  • Bileşenin tasarımını açıklama cazibesinden kaçınıp, gerekirse dokümantasyonu iyileştirmek daha iyi.

• Küçük commit’lerde ayrıntılı açıklamanın önemi:

  • Commit ne kadar küçükse, görece o kadar uzun bir açıklama gerekebilir.
  • Küçük değişikliklerin nedenini ayrıntılı biçimde açıklamak önemli.

• Commit mesajlarının sınırları ve araçların sorunları:

  • Commit mesajının ilk satırını daha somut yazmak gerekiyor.
  • Geri kalan uzun açıklama çok büyük bir değer taşımayabilir.
  • Geliştirme araçlarındaki sorunlara dikkat çekilirken, hata mesajlarının daha açık olması gerektiği söyleniyor.
  • Kod düzenleme araçlarının neden standart dışı boşluk karakterlerine izin verdiği sorgulanıyor.

• Commit mesajlarından çok commit hijyeninin önemi:

  • Commit mesajlarının ayrıntısından ziyade iyi commit hijyeni daha önemli.
  • Temiz ve bağımsız commit’ler, kod işlevlerini kolayca ayıklayıp yeniden kullanmayı sağlar.

• Auto-squash ve rebase eleştirisi:

  • Auto-squash, anlamlı commit mesajları yazmayı zorlaştırır.
  • Rebase, geliştiricinin bilinçli biçimde düzenleme yapması içindir; merge sırasında varsayılan kalıp hâline gelmemelidir.