İyi Bir Commit Mesajı Nasıl Yazılır ve Neden Önemlidir?

İyi bir commit mesajı yazmak, ekiplerin en çok ihmal ettiği ama en uzun ömürlü faydayı üreten alışkanlıklardan biridir. Kod zamanla değişir, yorumlar silinir, wiki sayfaları eskir; ancak commit geçmişi kalıcıdır ve o satırın neden yazıldığını öğrenmenin çoğu zaman tek yoludur. "düzeltme", "son hali", "olmadı yine denedim" gibi mesajlarla dolu bir geçmiş, aslında hiç tutulmamış bir kayıttır.

Commit geçmişini gerçekten kim okur?

Bu soruya "kimse" cevabı verilir, ama gerçekte üç durumda mutlaka okunur:

• Bir hatanın kaynağını ararken. Bir satırın neden böyle yazıldığını anlamak için git blame çalıştırıldığında, karşınıza çıkan mesaj ya bağlam verir ya vermez. "düzeltme" yazan bir commit, sizi yeniden aynı kararı almak zorunda bırakır.
• Bir değişikliği geri alırken. Hangi commit'in neyi kapsadığı belli değilse, geri alma işlemi tahmine dönüşür.
• Sürüm notları hazırlarken. Düzgün yazılmış bir geçmişten sürüm notu çıkarmak dakikalar sürer; dağınık bir geçmişten çıkarmak günler alır.

Bu üç durumun ortak noktası, mesajı yazan kişinin değil, aylar sonra başka birinin (çoğu zaman yine sizin) ihtiyaç duymasıdır.

En önemli kural: NE değil NEDEN

Mesajın gövdesinde ne yapıldığını anlatmak gereksizdir — bunu değişikliğin kendisi zaten gösterir. Değerli olan, koda bakarak öğrenilemeyecek bilgidir: neden bu yol seçildi, hangi alternatif denendi ve neden vazgeçildi, hangi kısıt bu çözümü zorunlu kıldı.

Zayıf bir örnek:

Önbellek süresi değiştirildi

Faydalı bir örnek:

Ürün listesi önbelleğini 5 dakikaya indir

Kampanya başlangıçlarında fiyatlar 1 saat boyunca eski
haliyle görünüyordu (HATA-2841). Önbelleği tamamen
kaldırmak liste sorgusunu 900 ms'ye çıkardığı için
süre kısaltıldı.

Kalıcı çözüm, fiyat güncellendiğinde önbelleği hedefli
temizlemek; ayrı bir iş olarak açıldı (ISTEK-2903).

İkinci mesaj, altı ay sonra o satıra bakan kişiye üç ayrı bilgi verir: sorunun ne olduğu, neden bu çözümün seçildiği ve kalıcı çözümün ne olacağı.

Biçim kuralları

Yaygın kabul gören yapı basittir ve araçlarla uyumludur:

1. Konu satırı 50 karakteri geçmesin. Bu sınır keyfi değildir; birçok arayüz uzun satırları keser.
2. Emir kipi kullanın: "Eklendi" veya "ekliyorum" değil, "Ekle". Git'in kendi ürettiği mesajlar da bu kipi kullanır, tutarlılık sağlar.
3. Konu satırının sonuna nokta koymayın. Bir başlıktır, cümle değil.
4. Konu ile gövde arasında boş satır bırakın. Bu boş satır olmadan araçlar gövdeyi konu satırının devamı sayar.
5. Gövde satırlarını 72 karakterde sarın. Terminal çıktısında okunabilirlik için.

Atomik commit: mesajdan önce gelen kural

İyi bir mesaj yazamıyorsanız, sorun genellikle yazma becerisinde değil, commit'in kapsamındadır. "Kullanıcı formu düzeltildi, ayrıca log eklendi ve bir de kütüphane güncellendi" cümlesi, aslında üç ayrı commit olması gerektiğini söyler.

Bir commit tek bir mantıksal değişiklik içermelidir. Bunun pratik faydası büyüktür: bir değişikliği geri almak gerektiğinde yanlarındaki alakasız değişiklikleri de geri almak zorunda kalmazsınız, ve hata arama komutları (git bisect gibi) anlamlı sonuç üretir. Çalışırken karışan değişiklikleri ayırmak için git add -p ile parça parça hazırlama yapılabilir. Günlük git akışı ve zor durumlardan çıkış için git çalışma rehberimize bakabilirsiniz.

Conventional Commits: yapılandırılmış geçmiş

Ekipler büyüdükçe mesajlara hafif bir yapı eklemek işe yarar. Yaygın biçim tip(kapsam): açıklama şeklindedir: fix(sepet): kupon indirimi iki kez uygulanıyordu. Tipler genellikle feat, fix, docs, refactor, test, chore olarak belirlenir.

Bu yapının asıl faydası estetik değil otomasyondur: sürüm notları otomatik üretilebilir, sürüm numarası kırıcı değişikliklere göre otomatik artırılabilir. Ancak zorunlu kılmadan önce ekibin gerçekten kullanacağından emin olun; uygulanmayan bir standart, hiç standardı olmamaktan daha çok tartışma üretir.

Ekipte nasıl yerleşir?

Kural koymak yeterli değildir; birkaç pratik destek gerekir. Depoda bir commit mesajı şablonu tanımlamak, yazarken hatırlatıcı görevi görür. Kod incelemesinde yalnızca koda değil commit mesajlarına da bakmak, standardı canlı tutar — bu, kod incelemesi yazımızda ele aldığımız geri bildirim kültürünün bir parçasıdır. Dal birleştirme stratejisinin de mesaj kalitesine etkisi vardır; sıkıştırarak birleştirme (squash) kullanılıyorsa asıl özen birleştirme mesajına gösterilmelidir, bu konudaki tercihler için rebase mi merge mi yazımıza bakın. Resmî öneriler için Git dokümantasyonu başvurulabilir.

Sonuç

Commit mesajı, yazması otuz saniye süren ama yıllarca okunan bir dokümantasyon parçasıdır. Kaliteyi belirleyen iki şey vardır: commit'in tek bir mantıksal değişikliği kapsaması ve mesajın ne yapıldığını değil neden yapıldığını anlatması. Bu ikisi sağlandığında biçim kuralları zaten kendiliğinden yerine oturur. Bugün küçük bir deneme yapın: en son dokunduğunuz karmaşık dosyada git blame çalıştırın ve çıkan mesajların size gerçekten bir şey anlatıp anlatmadığına bakın. Cevap hayırsa, bir sonraki commit'inizde değiştirebileceğiniz ilk şey bellidir.