Git Notes: Git'in En Havalı ve En Az Sevilen Özelliği (2022)

• Git notes, commit'lere ve benzeri nesnelere meta veri eklemeyi sağlayan güçlü bir araçtır
• Bu özellik, commit mesajı değiştirilemediğinde tamamlayıcı bilgileri saklamayı mümkün kılar
• Kod inceleme geçmişi veya test sonuçları gibi çeşitli bilgileri saklamak için kullanılabilir
• Dağıtık bir kod inceleme sistemi bile kurulabilir, ancak kullanılabilirliği ve bilinirliği düşüktür
• GitHub'da devre dışı bırakılması gibi yetersiz destek nedeniyle günlük kullanımda benimsenmesi düşüktür

---

Git notes nedir

• Git notes, Git tarafından izlenen herhangi bir nesneye (commit, blob, tree) meta veri eklemeyi sağlayan bir özelliktir
• Genellikle bir kez kaydedilen commit mesajı değiştirilemez, ancak git notes kullanıldığında commit gövdesini değiştirmeden yeni bilgi eklenebilir
• Örneğin aşağıdaki gibi bir commit'e notes eklenebilir
  • git notes add -m 'Acked-by: <이메일>'
• Notes, git log içinde ayrı bir bölüm olarak birlikte gösterilir

Gerçek kullanım örnekleri

• Git'in kendi projesinde de git notes kullanılarak commit'ler ile e-posta listesi içindeki tartışma başlıkları birbirine bağlanmaktadır
• Notes'un gerçek kullanım örnekleri arasında şunlar vardır
  • Commit veya branch bazında çalışma süresini takip etme
  • Kod inceleme ve test sonucu günlüklerini saklama
  • Tamamen dağıtık bir kod inceleme sistemi tasarlama

Kod inceleme ve test sonuçlarını saklama

• Kod forge'larının veya inceleme sistemlerinin, kod inceleme meta verilerini çevrimdışı olarak yani doğrudan Git içinde saklamayı desteklediği örnekler artıyor
• Gerrit'in reviewnotes eklentisi, git log içinde incelemeyi yapanları ve test çalıştırma kayıtlarını notes olarak birlikte gösterir
  • Kullanıcılar tarayıcıyı ayrıca açmadan kod inceleme geçmişini yerelde kontrol edebilir

Dağıtık kod inceleme sistemi

• Google tarafından geliştirilen git-appraise gibi, git notes kullanarak dağıtık kod incelemesini hayata geçiren örnekler vardır
• git-appraise; kod inceleme isteği, değişikliklere ilişkin yorumlar ve inceleme sonrası merge dahil tüm süreci git notes içine kaydeder ve çevrimiçi kod barındırma servislerinden bağımsız olarak çalışır
• Tüm iş birliği yerel ortamda mümkündür ve hatta bir web arayüzü de sunar

Düşük kullanılabilirlik ve bilinirlik

• Git notes, arayüzünün kullanışsız olması ve genel kullanıcı için sezgisel olmaması nedeniyle neredeyse hiç kullanılmamaktadır
• GitHub, 2014'ten sonra commit notes'larını göstermeyi bıraktığı için kullanım fırsatları daha da azalmıştır
• Yalnızca commit'lere yönelik notes yönetimi Git ayarlarıyla biraz daha kolaylaştırılabilir, ancak blob veya tree nesnelerine notes eklemek için Git'in iç yapısına (plumbing) dair ek anlayış gerekir
• Sonuç olarak git notes, hâlâ meraklılara hitap eden ve bilinirliği çok düşük bir özellik olarak kalmıştır

Açık forge bağımsızlığı

• Git'in kendisi dağıtık sürüm kontrolünü ve kod incelemeyi destekleyebilir, ancak inceleme geçmişi gibi birçok ek değer GitHub benzeri barındırma servislerine güçlü biçimde bağımlı olma eğilimindedir
• Git notes özelliği kullanılırsa yalnızca kodun değişim geçmişi değil, tüm projenin geçmişi de dağıtık biçimde saklanıp dağıtılabilir
• Bunun, tam anlamıyla dağıtık geliştirme ekosistemi ve kayıtların korunması açısından önemli bir anlamı vardır

[GN⁺]

Hacker News görüşleri

• Git trailer adlı, pek bilinmeyen bir özellik var; trailer’lar commit oluşturulurken anahtar-değer biçiminde metadata eklemeyi sağlıyor ve Gerrit’te Change-Id eklemek için kullanılıyor. İlgili yazı bağlantısı

  • PostgreSQL’de de COMMENT adlı benzer bir özellik var; COMMENT, veritabanı nesnelerine metin ekleyebiliyor. PostgreSQL’in anahtar-değer biçiminde yapılandırılmış metadata düzenleme özelliği de sunmasını isterdim. İlgili dokümantasyon bağlantısı

  • Açık kaynak upstream çalışırken, unit test’i tamamlanmış commit’leri işaretlemek için git notes kullandığım oldu; git rebase -i ile branch’i düzenlerken faydalıydı. Ama şu an trailer’lar daha iyi bir yöntem gibi görünüyor. Change-Id gibi bir özellik git’in kendisine dahil edilirse araçlar bunu daha iyi anlayabilir gibi geliyor. Commit’leri commit message ile ayırt etmek ince bir şekilde kırılgan; commit id benzersizlik açısından iyi ama aynı değişikliği başka bir commit’in üstüne taşıdığınızda tanımlayıcı olarak faydası azalıyor. Düzeltme: trailer’lar commit’in parçası olduğu için notes’un yerini tamamen alamaz

  • GitHub’ın yakın zamanda [skip ci] yerine ayrı bir trailer kullandığını öğrendim; muhtemelen commit message’dan kolayca ayrıştırmak için. GitHub’ın neden sadece son trailer’ı istediğinden emin değilim; herhalde regex işleme yüzündendir. İlgili dokümantasyon bağlantısı

  • Trailer özelliğini ilk kez duyuyorum. Conventional Commits hayranı olarak, bu tür metadata eklemeleri için trailer’lar daha iyi gibi görünüyor. Commit message’a elle eklemekle --trailer bayrağını kullanmak işlevsel olarak aynı mı, merak ediyorum

  • Doğal olarak issue tracking sistemiyle entegre etmek istiyorsunuz ama bunu trailer gibi bir yere koymak, issue tracker’dan fazla kopuk olduğu için verimsiz. Issue tracker’ların trendlerin peşinden gitmesi ve birçok özelliğin geç gelmesi gibi sorunları var. Ticket adından türetilen branch adını PR başlığı olarak zorunlu kullanma kuralı can sıkıcı; commit ile issue’yu başka metadata üzerinden bağlayıp PR başlığını daha anlamlı hale getirmek istiyorum. Kolay çözülebilecek bir mesele olmadığı için internette dert yanılan konulardan biri

• Forgejo, bu yıl ocakta çıkan v10 sürümünden itibaren trailer desteği sunmaya başladı. Sürüm notları Pull request

• git notes ile geçmişi yeniden yazma (amend, rebase vb.) özelliklerinin nasıl etkileştiğini merak ediyorum; notes commit/tree/blob ID’lerine bağlıysa, yeni commit ile değiştirildiğinde notes kopyalanıyor mu yoksa kayboluyor mu? interactive rebase ile birden fazla commit birleştirildiğinde ne oluyor? notes’un dosya/dizinlerin “içeriğine” bağlanması beklentimden farklı geldi. Örneğin "Hello world!" string blob’una note eklerseniz, aynı içeriğe sahip tüm dosyalarda o note görünür mü; dosya değişirse notes kaybolur mu?

  • git rebase gibi işlemlerde notes kopyalamak, varsayılan olarak kopyalanacak şekilde yapılandırılabiliyor; git-config(1) içindeki notes.rewrite seçeneğine bakın

• Şu anki iş yerimde git notes’u aktif olarak kullanıyoruz; amaç, commit message’ları karmaşıklaştırmadan veya her değişiklik için PR açmadan iç code review kaydını tutmak. Her commit’in hangi ticket’a karşılık geldiği, altyapı kısıtları ve düzeltmeler için incident thread bağlantıları gibi bağlamı branch’te bırakıyoruz. Bu bilgiyi repo içinde tutunca, Slack ya da Jira’da arama yapmadan bir satırın neden değiştiğini anlamak kolaylaşıyor. Büyük ölçekte kullanıldığında platform UI’larına olan ihtiyacı belirgin biçimde azaltabilir. Reproducibility’nin yalnızca build’ler için değil, “niyet” için de gerekli olduğunu düşünüyorum

  • Bu tür bilgilerin commit message’da bulunması daha iyi olmaz mı? Yoksa amaç “bu commit bug #123’e yol açtı” gibi geleceğe dönük bağlantılar da kurmak mı?

• git notes, gerçekten ancak commit sonrasında ek bilgi gerektiğinde faydalı. Acked-By, mailing list tartışma bağlantısı gibi örnekler zaten commit anında bilinen şeyler; bunları commit message’a eklemek yeterli. Bence git note’un asıl gücü, sonradan revert edilen commit’lere ek açıklama iliştirebilmekte

  • Sıklıkla commit message bir bug’ı düzelttiğini iddia ediyor ama aslında düzeltmemiş oluyor. Bu da birbirini tetikleyen bug’lara yol açıyor ve ekip arkadaşları ilk yazım amacını görmezden gelip üstünkörü geçebiliyor. Öfkeli müşteriler ve bug’ın yeniden ortaya çıkması gibi deneyimlerden sonra bug fix konusunda daha temkinli olmak gerektiğini hissettim. Bazen birden fazla bug tek seferde düzeltiliyor; bazen de bir refactor performans iyileştirmesi ya da yeni özellikler için kapı açıyor

  • Acked-By, review ve tartışmalar genelde commit’ten sonra devam eder; commit edildiği anda bunları bilmezsiniz. Revert edilen commit örnekleri ise aslında commit message’a eklenirse daha faydalı olur; çünkü blame zaten en son değişikliği gösterdiğinden revert edilen commit’leri doğal olarak izleme imkânı verir

  • Çoğu zaman tartışma commit sonrasında da sürer

• Kod ajanlarına ek bağlam sağlama amacıyla notes özelliğini araştırmak ilginç olabilir diye düşünüyorum

• Bu bir bilgi eksikliği değil, UI sorunu. GitHub UI notes’u iyi gösterse insanlar hemen daha fazla kullanırdı

  • GitHub’ın notes desteği sunmasını isterdim

• git’te bisect, pickaxe, reflog, range-diff, archive, annotated tags gibi “en havalı ama en az sevilen” birçok özellik var; ama çoğu insan onu yalnızca Google Drive gibi gördüğü için kullanmıyor

  • git notes zaten ayrı bir proje yönetim aracıyla (ör. Jira) feature, roadmap gibi teknik olmayan bağlamı takip ettiğiniz için biraz mükerrer kalıyor; Unix felsefesine göre herkes kendi işine odaklanmalı

  • pickaxe’i ilk kez duyuyorum; fazla kendimden emin olmamam gerekiyormuş

  • Bu tür süslü özellikler pratikte çoğu zaman o kadar da faydalı olmuyor; özün etrafındaki yardımcı numaralar gibi geliyor

• git notes’un gerçekten “havalı” ama sevilmeyen bir özellik değil, sadece çok sınırlı ve özel durumlarda işe yaradığı görüşündeyim. Gerçekten gerekli bilgi varsa hepsini commit message’a koyup başka sistemlerden (ör. JIRA) referans vermek aslında avantaj. JIRA gibi sistemler, geliştirici olmayan business analyst’ler veya support ekipleriyle iletişim kanalı işlevi görüyor. Geliştirici olmayan kişilerin repo’ya ve koda erişiminin olmaması da makul. Birden fazla servis ve repo ile aynı anda uğraşıyorsanız, feature referanslarını notes gibi bir şeyle takip etmek pratikte mümkün değil; dış sistemlerle entegrasyon gerekiyor

  • Business analyst’lerin koda veya repo’ya erişememesinin verimsiz olduğunu söyleyenler de var; aslında tek satır koda bakınca anlaşılabilecek şeyler için sürekli soru geliyor. Teknik yetkinliği olan analyst’ler de var ama kültürün kolay değişmemesi gerçek bir sınır

• man sayfası sayesinde notes’u ilk kez 2020 civarında öğrendim. Varsayılan olarak notes yerel repo’da kaldığı için pratikte hiç kullanmadım; push/fetch ayarlarını ayrıca yapıp takım olarak kullanım kararı vermek gerekiyor ve benim ekibim bunu benimsemedi