Git Commit Mesajı: Kurallar, Örnekler ve Konvansiyonlar

Bir Git Commit Mesajı Neden Önemlidir

Bir commit mesajı, siz de dahil olmak üzere, kodu daha sonra okuyacak herkese yaptığınız değişiklikleri açıklar.

Üç ay sonra, neden o veri hattını yeniden düzenlediğinizi veya belirli bir işlem için neden pandas’dan polars’a geçtiğinizi hatırlamayacaksınız. Commit mesajınız, gerekçenizin tek kaydıdır. O olmadan, tahmin yürütmek ya da Slack başlıkları ve JIRA biletlerinde kazı yapmak zorunda kalırsınız.

İşte git commit mesajının neden önemli olduğuna dair birkaç somut neden daha.

Açık commit mesajlarıyla kod incelemeleri daha hızlı ilerler. İnceleyen kişi mesajı tarar, niyeti anlar ve uygulamanın buna uyup uymadığına odaklanır. Belirsiz mesajlar, inceleyicileri yalnızca diff üzerinden düşüncenizi tersine mühendislik yapmaya zorlar.

Hata ayıklama da kolaylaşır. Bir hata ortaya çıktığında, sorunlu kodun ne zaman dahil edildiğini izlemek için git log veya git blame kullanırsınız. "fix authentication bug" gibi bir mesaj size hiçbir şey söylemez. "fix token expiration check in auth middleware" gibi bir mesaj ise sizi doğrudan soruna götürür.

Ekip işbirliği okunabilir geçmişe bağlıdır. Birisi projenize katıldığında ya da bıraktığınız yerden devam ettiğinde, kod tabanının nasıl evrildiğini anlamak için commitleri okur. Net mesajlar, Git geçmişinizi gerçekten yardımcı olan bir dokümantasyona dönüştürür.

Özetle, açıklayıcı bir commit mesajı yazmak 15-30 saniyenizi alır ama ileride saatlerce sürecek kafa karışıklığını önler.

İyi Bir Git Commit Mesajının Temel İlkeleri

İyi commit mesajları birkaç basit ilkeyi izler — fazlası değildir.

Gelecekteki okurlar için yazın

Commit mesajınız şu anki sizin için değil — altı ay sonra onu okuyacak kişi içindir.

Bu kişi, kod tabanının neden belirli bir şekilde çalıştığını anlamaya çalışan yeni bir ekip üyesi olabilir. Ya da siz olabilirsiniz; belirli bir kararı neden verdiğinizi hatırlamaya çalışıyorsunuzdur. Her iki durumda da, bugün sahip olduğunuz bağlama sahip olmayacaklar.

Yalnızca neyin değiştiğine değil, niyete ve gerekçeye odaklanın. Diff neyin değiştiğini gösterir. Mesajınız neden değiştiğini ve hangi sorunu çözdüğünü açıklamalıdır.

Açık ve öz olun

Kısa, betimleyici mesajlar onlarca commit arasında gezinirken daha kolay taranır.

"add caching" gibi bir mesaj belirsizdir. "add Redis caching for API responses" ise size tam olarak ne olduğunu söyler. git log --oneline çıktısında okur ve commitin ne yaptığını anında bilirsiniz.

Konu satırınız şu soruyu yanıtlamalı: bu commit ne yapıyor? Bunu yanıtlamak için 50-60 karakterden fazlasına ihtiyaç duyuyorsanız, muhtemelen aynı anda çok fazla değişiklik commitliyorsunuzdur.

Tutarlı olun

Depo genelinde tutarlılık, geçmişi öngörülebilir ve ayrıştırması kolay hale getirir.

Her commit aynı formatı izlediğinde, geçmişi hızla tarayabilirsiniz. Değişiklik türüne, kapsama ve açıklamaya nereden bakacağınızı bilirsiniz. Tutarlı formatları uygulayan ekipler, değişiklik günlüğü üretme veya commitleri türe göre filtreleme gibi görevleri de otomatikleştirebilir.

Bir stil seçin ve ona sadık kalın. Ekibiniz geniş zaman kipinde emir kipi kullanıyorsa, rastgele geçmiş zamana geçmeyin.

Ne ve neden açıklayın (nasıl değil)

Kod, sorunu nasıl çözdüğünüzü gösterir. Commit mesajınız, sorunun ne olduğunu ve neden bu çözümü seçtiğinizi açıklamalıdır.

"load_data() fonksiyonunu for döngüsü yerine liste üreteci kullanacak şekilde yeniden düzenledim" yazmayın. "Büyük CSV dosyaları için veri yüklemeyi %40 hızlandır" yazın. İlk mesaj kod değişikliğini tarif eder. İkincisi etkisini açıklar.

Gelecekteki okurların kararınızı anlamasına yardımcı olacaksa bağlam ekleyin. Bu çözüme karar vermeden önce üç farklı yaklaşımı denediyseniz, bunu belirtin. İlgili bir hata raporu veya tasarım kararı varsa, ona referans verin.

Bir Git Commit Mesajının Yapısı

Çoğu Git commit mesajı standart üç parçalı bir yapıyı izler: konu satırı, gövde ve alt kısım.

Konu satırı

Konu satırı, git log --oneline ve çekme isteği listelerinde görünen tek satırlık bir özetidir.

Mümkünse 50 karakterin altında, en fazla 72 karakter tutun. Bu sınır, mesajın terminal çıktısında ve GitHub arayüzünde kesilmeden düzgün görüntülenmesini sağlar. Özetinizi 50 karaktere sığdıramıyorsanız, muhtemelen tek bir committe çok fazla değişikliği anlatmaya çalışıyorsunuzdur.

Emir kipini kullanın — "added feature" veya "adds feature" yerine "add feature" yazın. Bunu "Uygulanırsa, bu commit ... yapacaktır" cümlesini tamamlamak gibi düşünün. Örneğin, "Uygulanırsa, bu commit Redis önbellekleme ekler" doğal gelirken, "Uygulanırsa, bu commit adds Redis caching" doğal değildir.

Örnekler:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Gövde (gerektiğinde)

Basit değişikliklerde gövdeyi atlayın. Konu satırınız commit’i tamamen açıklıyorsa, işiniz bitmiştir.

Değişikliği neden yaptığınızı açıklamanız veya gelecekteki okurlara yardımcı olacak bağlam sağlamanız gerektiğinde bir gövde ekleyin. Konu ile gövde arasında boş bir satır bırakın — Git bu iki kısmı ayırmak için bunu kullanır.

Gövde şu soruları yanıtlamalıdır: Bu hangi sorunu çözüyor? Neden bu yaklaşımı seçtiniz? Yan etkiler veya sınırlamalar var mı? Başka çözümleri düşündünüz mü?

Satırları 72 karakterde kaydırın; bu, metni terminal çıktısında okunabilir tutar. Çoğu metin düzenleyici bunu otomatik yapabilir.

Örnek:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.Altyapı:

Alt kısım (opsiyonel)

Alt kısmı ilgili konulara, çekme isteklerine veya yıkıcı değişikliklere referans vermek için kullanın.

Commit’iniz bir GitHub konusunu düzeltirse, alt kısma Fixes #123 veya Closes #456 ekleyin. Commit birleştirildiğinde GitHub konuyu otomatik olarak kapatır. Yıkıcı değişiklikler için, BREAKING CHANGE: ifadesini ekleyip neyin bozulduğunu ve nasıl geçiş yapılacağını açıklayın.

Örnek:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789Altyapı:

Çoğu commit için alt kısma gerek yoktur — yalnızca harici referanslara bağlanırken veya yıkıcı değişiklikleri işaretlerken kullanın.

Yaygın Git Commit Mesajı Türleri ve Ne Zaman Kullanılacakları

Birçok proje, değişiklikleri bir bakışta kategorize etmek için commit türü önekleri kullanır.

Sıkı bir etiket listesi ezberlemeniz gerekmez. Amaç, okuyucuların tam diff’i okumadan ne tür bir değişiklik olduğunu hızla anlamasına yardımcı olmaktır.

Farkında olmanız gereken dört kategori şunlardır:

• Özellik değişiklikleri yeni işlevsellik getirir. Yeni bir şey inşa ederken — yeni bir API uç noktası, bir veri işleme fonksiyonu veya kullanıcıya dönük bir özellik — feat: veya add: gibi önekler kullanın. Örnek: feat: add CSV export for analysis results.

• Hata düzeltmeleri mevcut sorunları çözer. İstenen şekilde çalışmayan davranışı düzelttiğinizde fix: kullanın. Bu, null pointer hatasından modelinizdeki yanlış hesaplamalara kadar her şey olabilir. Örnek: fix: handle missing values in preprocessing pipeline.

• Dokümantasyon güncellemeleri kod yorumlarını, README dosyalarını veya satır içi dokümantasyonu iyileştirir. Kodun çalışma şeklini değiştirmiyor, sadece daha iyi açıklıyorsanız docs: kullanın. Örnek: docs: add usage examples for data loader class.

• Yeniden düzenleme ve bakım çalışmaları davranışı değiştirmeden kod yapısını iyileştirir. Kodu daha temiz veya sürdürülebilir hale getirmek için yeniden düzenliyorsanız refactor: kullanın. Bağımlılıkları güncellemek veya derleme yapılandırmalarını değiştirmek gibi rutin görevler için chore: kullanın. Örnekler: refactor: extract validation logic into separate module veya chore: update pandas to 3.0.0.

Değişikliğinizi en iyi tanımlayan türü seçin ve devam edin — "mükemmel" etiketi seçmekten ziyade tutarlılık daha önemlidir.

Daha İyi Bir Git Commit Mesajı Yazma Kuralları

Commit mesajlarınızı daha kullanışlı kılacak bir kontrol listesi burada.

• Konu satırını 50 karakterin altında tutun. Bu, git log --oneline, GitHub’ın commit listesi ve terminal çıktısında kesilmeden doğru görüntülenmesini garanti eder. Mesajınızı 50 karaktere sığdıramıyorsanız, en fazla 72’yi hedefleyin.

• Emir kipini kullanın. "added feature" veya "adds feature" yerine "add feature" yazın. Konu satırınız, "Uygulanırsa, bu commit ... yapacaktır" cümlesini tamamlamalıdır. Örneğin, "Uygulanırsa, bu commit önbellekleme ekler" doğru okunur.

• Konu ve gövdeyi boş bir satırla ayırın. Git, özeti ayrıntılı açıklamadan ayırmak için bu boş satırı kullanır. Bu olmadan, Git araçları mesajınızı yanlış görüntüleyebilir.

• Konu satırının sonuna nokta koymayın. Karakter tasarrufu sağlar ve konu satırı zaten tam bir cümle değildir. fix null pointer in loader yazın, fix null pointer in loader yerine.

• İlk kelimeyi büyük harfle yazın. Add caching for API calls yazın, add caching for API calls yerine. Bu, commit geçmişinizi tutarlı ve profesyonel gösterir.

• Gövdeyi neyi değil, nedeni açıklamak için kullanın. Diff neyin değiştiğini gösterir. Gövde, değişikliğin arkasındaki gerekçeyi, düşündüğünüz alternatif yaklaşımları ve yaptığınız ödünleri açıklamalıdır.

• Gövde metnini 72 karakterde kaydırın. Bu, terminal çıktısında satır kayma sorunlarını önler ve commit mesajlarınızı farklı araçlarda okunabilir kılar.

• Her commit atomik olsun. Her committe tek bir mantıksal değişiklik olsun. Hem bir hatayı düzeltip hem de yeniden düzenleme yapıyorsanız, ikisini ayrı commitlere bölün ve ayrı mesajlar yazın.

İyi Bir Git Commit Mesajı Örnekleri

Farklı senaryolar için iyi commit mesajlarının nasıl göründüğüne dair gerçek hayattan örnekler burada.

Basit bir düzeltme

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.Altyapı:

Bu, sorunu (NaN çakılmaları) tanımladığı, nerede meydana geldiğini (ön işleme hattı, age sütunu) açıkladığı ve çözümü (medyanla atama) tarif ettiği için işe yarar.

Yeni bir özellik

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.Altyapı:

İyi özellik commitleri ne inşa ettiğinizi, neden faydalı olduğunu ve kapsamı anlamaya yardımcı olacak ayrıntıları açıklar.

Bir refactor

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.Altyapı:

Refactor mesajları, işlevselliği değil, yalnızca yapıyı değiştirdiğinizi netleştirmelidir. "Tüm testler geçiyor" satırı inceleyenleri rahatlatır.

Bir dokümantasyon güncellemesi

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.Altyapı:

Dokümantasyon commitleri neyi belgelendirdiğinizi ve neden gerektiğini açıklamalıdır.

Bir konuya veya bilete referans verme

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247Altyapı:

Bir konuya referans verirken, birinin bilete tıklamadan düzeltmeyi anlayabilmesi için yeterli bağlam ekleyin. Alttaki Fixes #247 ifadesi, bu commit birleştirildiğinde GitHub’ın konuyu otomatik kapatmasını sağlar.

Tüm örnekler aynı deseni izler: neyin değiştiğiyle başlayın, nedenini açıklayın, gelecekteki okurlara yardımcı olacak bağlam ekleyin ve uygun olduğunda ilgili konulara referans verin.

Bir Git Commit Mesajı Standardı Olarak Conventional Commits

Conventional commits, basit bir önek deseniyle commit mesajlarına yapı kazandıran popüler bir formattır.

Temel format

Format şöyledir: type(scope): description.

Tür, yaptığınız değişikliğin türünü açıklar — özellikler için feat, hata düzeltmeleri için fix, dokümantasyon için docs, kod yeniden yapılandırma için refactor ve benzeri. Kapsam isteğe bağlıdır ve kod tabanının hangi kısmının değiştiğini belirtir — (auth) veya (api) gibi. Açıklama ne yaptığınızı açıklar.

Örnekler:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate moduleAltyapı:

Bunun bir konvansiyon olduğunu, zorunluluk olmadığını unutmayın. Git, bu formatı kullanıp kullanmadığınızla ilgilenmez. Esasen, tutarlılık ve araç desteği için mesajlarınızı nasıl yapılandıracağınıza dair bir ekip kararıdır.

Conventional commits ne zaman faydalıdır

Sürüm yayın süreçlerini otomatikleştiren ekipler, conventional commits’den en çok faydayı sağlar.

Araçlar commit geçmişinizi ayrıştırıp otomatik olarak değişiklik günlükleri üretebilir. Bir sürümü etiketlediğinizde, araç son sürümden bu yana commitleri tarar, türlerine göre gruplayıp (feat, fix, docs) biçimlendirilmiş bir değişiklik günlüğü oluşturur. Bu, sürümler arasındaki değişiklikleri takip etme işini el ile yapma ihtiyacını ortadan kaldırır.

Conventional commits ayrıca anlamsal sürümleme otomasyonunu destekler. Son sürümden bu yana tüm commitler düzeltmeyse, araç yama sürümünü artırır (1.2.3 → 1.2.4). Özellik eklediyseniz, minör sürümü artırır (1.2.3 → 1.3.0). Yıkıcı değişiklikler majör sürüm artışını tetikler (1.2.3 → 2.0.0).

Ancak ekibiniz otomatik sürümler veya değişiklik günlüğü üretimi kullanmıyorsa, conventional commits gereğinden fazla olabilir. Bu yapı, insanlardan çok makinelerin işine yarar; bunu aklınızda bulundurun.

Kaçınılması Gereken Yaygın Git Commit Mesajı Hataları

Deneyimli geliştiriciler bile commit mesajı yazarken bazen hata yapar; bu, bilgi eksikliğinden çok tembellikle ilgilidir.

İşte kaçınmanız gereken birkaç hata.

Belirsiz veya jenerik mesajlar

"fix bug" veya "update code" gibi mesajlar gelecekteki okurlara hiçbir şey söylemez.

Belirli bir değişikliği git log içinde ararken, düzinelerce commit arasında gezinirsiniz. "fix bug" diyen bir mesaj, neyin düzeltildiğini anlamak için diffi açıp kodu okumanızı zorlar. "fix null pointer in data preprocessing" diyen bir mesaj ise bunun aradığınız commit olup olmadığını anında söyler.

Jenerik mesajlar herkesin zamanını boşa harcar. Ne değiştirdiğinizi yeterince net hatırlamıyorsanız, muhtemelen henüz commit atmanız gerekmiyordur.

İlgisiz değişiklikleri karıştırmak

Bir commit, tek bir mantıksal değişiklik içermelidir.

Aynı committe bir hatayı düzeltip ilgisiz kodu yeniden düzenlediğinizde, kod incelemelerini zorlaştırır ve git bisect işe yaramaz hale gelir. Bu commit bir gerilemeye neden olursa, birisi değişikliğin hangi kısmının buna yol açtığını çözmek zorunda kalır. Sadece düzeltmeyi geri almak isterlerse, alamazlar — refactoru da geri almış olurlar.

Değişiklikleri her zaman ayrı commitlere bölmelisiniz. Hata düzeltmesini bir committe yapın, refactoru diğerinde. Her commit, kod tabanını bozmadan bağımsızca geri alabileceğiniz bir şey olmalıdır.

Zaten yerelde değişiklikleri karıştırdıysanız, dosyaların bölümlerini ayrı ayrı aşamalandırmak ve mantıklı parçalar halinde commitlemek için git add -p kullanın.

Devam eden çalışma (WIP) mesajları bırakmak

"WIP" veya "temp fix" gibi mesajlara sahip commitler yerelde sorun olmayabilir ancak ana dala girmemelidir.

Özellik dalınızı birleştirmeden önce commit geçmişinizi temizleyin. Squash ile WIP commitlerini anlamlı, düzgün mesajlı commitlere dönüştürün. "asdf" ve "bir şey deniyorum" mesajlarını, gerçekte ne yaptığınızı açıklayan ifadelere yeniden yazın.

Push etmeden önce commitleri birleştirmek, mesajları yeniden yazmak ve değişiklikleri yeniden sıralamak için git rebase -i kullanın. Ekibiniz, neyin neden değiştiğine dair temiz bir geçmiş görmeli; hata ayıklama sürecinizi okumamalı.

Git Commit Mesajları Kullanan Ekipler için En İyi Uygulamalar

Ekibiniz Git geçmişini gerçekten faydalı kılmak istiyorsa, tutarlılığa ihtiyacınız var. İşte izlenecek bazı en iyi uygulamalar.

Paylaşılan bir stile erken dönemde anlaşın. Conventional commits, özel bir format veya sadece temel kurallar kullanıp kullanmayacağınıza karar verin. Tek bir yaklaşım seçin ve tüm ekipte ona sadık kalın. Commitlerin yarısı "feat: add feature" derken diğer yarısı "Added new feature" diyorsa, geçmişinizin taranması zorlaşır ve otomasyon bozulabilir.

Stilin kendisi, herkesin onu takip etmesi kadar önemli değildir. Bazı ekipler geniş zaman emir kipini ("add feature") tercih ederken, bazıları geçmiş zamanı ("added feature") kullanır. Tutarlı uygulandığı sürece ikisi de gayet iyi çalışır.

Konvansiyonlarınızı erişilebilir bir yerde belgeleyin. Depoza bir CONTRIBUTING.md dosyası ekleyin ve commit mesajı formatınızı örneklerle açıklayın. Yeni ekip üyeleri için işe alım dokümanlarına dahil edin. Birisi "Bu commit nasıl formatlanmalı?" diye sorduğunda, tekrar anlatmak yerine dokümantasyona yönlendirin.

Dokümantasyonunuz, kullandığınız temel formatı, ne zaman gövde eklenmesi gerektiğini ve ne zaman yalnızca konu satırının yeterli olduğunu, konulara veya bilet numaralarına nasıl referans verileceğini ve deponuzdan birkaç gerçek örneği kapsamalıdır.

Kod incelemeleri sırasında commit mesajlarını kullanın. İyi commit mesajları, çekme isteği incelemelerini daha hızlı ve odaklı hale getirir. İnceleyenler, koda dalmadan önce değişikliklerin ilerleyişini anlamak için commit mesajlarını okuyabilir.

İncelerken, commit mesajlarını kodu incelediğiniz gibi kontrol edin. Bir mesaj belirsiz veya yanıltıcıysa, birleştirmeden önce yeniden yazılmasını isteyin. Net commitlere sahip bir PR, incelemesi daha kolaydır, gerekirse geri alınması daha kolaydır ve sonradan anlaşılması daha kolaydır.

Sonuç

Net bir commit mesajı yazmak 30 saniyenizi alır ama sonrasında saatlerce sürecek kafa karışıklığını önler.

Commit geçmişinizi kodunuzla birlikte yaşayan bir dokümantasyon olarak düşünün. "fix bug" yerine "fix null pointer in data preprocessing" yazdığınızda, o commit’i daha sonra okuyacak herkes için — kendiniz dahil — zaman kazandırırsınız.

Commit mesajlarınızı kod gibi ele alın. Nasıl ki özensiz, yorumsuz kodu üretime itmezseniz, özensiz commit mesajlarını da itmeyin. Emir kipini kullanın, konu satırlarını 50 karakterin altında tutun, gerektiğinde gövdede nedeni açıklayın ve her commit atomik olsun.

Artık anlamlı commit mesajları yazmayı biliyorsunuz. Yeteneklerinizi bir üst seviyeye taşımak için Intermediate Git kursumuza kaydolun.