13 Ocak 2012 Cuma

Daha iyi gönderim (commit) mesajı yazmak

Uzun süredir svn kullanan bir ekip olarak git kullanmaya geçince bazı alışkanlıklarımızı değiştirmemiz gerekti. Bundan sonra aramıza katılacak arkadaşlar için de link verebilelim diyerek burada bir kaç noktaya dikkat çekmek istiyorum.

Aslında hangi sürüm takip sistemini kullanırsak kullanalım gönderim (commit) mesajları büyük önem taşıyor. Kullandığımız sistem izin veriyor olsa bile boş mesajla gönderim yapmamak lazım. Yaptığımız işi tanımlayan ama kodu da tekrar etmeyen mesajlar yazmak kolayca alışkanlık haline getirebileceğimiz bir şey. İyi gönderim mesajları gözden geçirme sürecini kolaylaştıracağı gibi sürüm notları hazırlarken de en iyi yardımcınız olacaktır. Yazdığınız kodu ileride sürdürmesi gerekecek biri olacaksa ondan (belki de siz olacaksınız bu kişi) alacağınız dualar yazdığınız gönderim mesajları doğrultusunda olacaktır ;)

Hakkında konuştuğumuz mesajlar temelde iki bölümden oluşuyor:

  • Yapılan işin özeti
Bunun gerçekten bir özet olması lazım. 50 veya daha az karakterden oluşan bir mesaj yazamıyorsanız büyük ihtimalle atomik bir gönderim yapmıyorsunuz demektir. Bu gönderim mesajının değil bir sürüm takip sistemi kullanmanın bir konusu olduğundan üzerinde çok durmak istemiyorum ama 'geri alındığında sadece bir yeniliğin/özelliğin/düzeltmenin dışında hiç bir şeyin değişmeyeceği' gönderimler yapmanın önemini de vurgulamadan geçmeyeyim.

Eğer yazdığınız gönderim mesajı bir hata takip sistemiyle bağlantılıysa yaptığınız değişikliğin hangi hatayı kapattığını, iyileştirdiğini de belirtmeniz gerekir.

Özet kısa olacak diye sadece 'bir hata düzeltildi', 'yapılandırma düzeltildi', 'yeni özellik eklendi' gibi anlamsız ve boş mesajla aynı anlama gelen metinler girilmemeli. Bunu insan okuyacak diye düşünüp ona göre 'parola kontrolü hatası düzeltildi', 'yapılandırmada kullanılmayan secenekler temizlendi', 'kaydetmeden cikma ozelligi eklendi' gibi okuyana birşey ifade eden mesajlar yazılmalı.

Mümkün olduğunca kızgın gönderim mesajları yazmamalı. 'Lanet olası hata, lanet olası bir şekilde çözüldü' gibi ifadeleri alt yazı çevirilerinde bırakmak en iyisidir.
  • Bunun neden yaptığınızın açıklaması
Bu ikisi arasında bir satır boşluk olması ve her satırın en fazla 72 karakter uzunluğunda olması uygun olacaktır. 

Yukarıda bir cümle ile özetlediğiniz değişikliği neden yaptığınızın açıklamasını buraya yazmalısınız. Buraya yazdığınız mesajların birlikte çalıştığınız ekibin geri kalanıyla bir iletişim yöntemi (hem de kalıcı) olduğunu aklınızdan çıkarmamalısınız. Hatta ekibin önemli bir kısmının (eğer imkanı varsa) yazdıklarınızı RSS ile bazılarının sadece eposta ile okuduğunu, yazdığınız koddan önce buraya yazdıklarınızı göreceklerini düşünerek yazmalısınız.

Elbette yapılan işin açıklaması olacak diye yazdığınız kodu okuyan birinin açıkça anlayacağı şeyleri (iki değişkenin değerleri birbirine aktarıldı gibi) yazmamak gerekir.

Biraz özen gösterildiğinde çok daha iyi gönderim mesajları yazmak zor olmayacaktır.

1 yorum:

  1. tesekkurler.
    iyi, kotu commit mesajlarini orneklendirmis soyle bir kaynak var konuyla ilgili;
    http://lbrandy.com/blog/2009/03/writing-better-commit-messages/

    yine konuyla ilgili orcunun bana gonderdigi e-postasi soyleydi;
    '
    commit mesajının ilk cümlesi kısa bir cümle olmalı. Bu bizim hızlı bir ilk bakışta commit'in ne yaptığını anlamamıza yardımcı olur. Daha ayrıntılı bir mesaj ekleyeceksen ki bence mümkün olduğunca bunu da yapmalıyız, commit mesajı içinde kısa tanımdan sonra iki satır atlayıp istediğin kadar uzun bir ayrıntılı açıklama yapabilirsin.
    http://spheredev.org/wiki/Git_for_the_lazy#Writing_good_commit_messages
    '

    YanıtlaSil

Ayı Dağı - Andrew Krivak

Duvar'da dünyada tek sağ kalan kadının hikayesini okuduktan sonra Ayı Dağı'nda (dünyaya her ne olduysa artık) hayatta kalan iki kişi...