Conventional Commits

Kısaca: Sabit biçimli commit iletileri için bir kural: <tür>(<kapsam>): <kısa açıklama>, örneğin feat(shop): ... veya fix(chat): ....

Biraz daha ayrıntılı: Yaygın türler: feat (yeni özellik), fix (hata düzeltme), refactor (davranış değişikliği olmadan yeniden yapılandırma), chore (bağımlılık güncellemeleri gibi bakım), perf (performans). Commit geçmişini makine tarafından okunabilir kılar (örneğin otomatik değişiklik günlükleri için) ve insanlar için bir bakışta sınıflandırmayı kolaylaştırır.

Bizim bağlamımız: Emzett için özel bir kural kararlaştırıldı — her değişiklik “toplu işi” bu biçimde Almanca bir commit iletisi alır, ayrıca kararın arkasındaki gerekçeyi içeren ek bir “neden” bölümü.

Ayrıntılı

Tam yapı

Tek satırlık başlığın yanı sıra tam şartname isteğe bağlı bir gövdeyi (daha ayrıntılı bir açıklama, genellikle bir boş satırla ayrılır) ve yapılandırılmış ek bilgi için isteğe bağlı “altbilgileri” de bilir — örneğin kod tabanının mevcut kullanıcılarını etkileyen değişiklikler için BREAKING CHANGE: ... veya bir commit’i otomatik olarak bir sorunla (issue) ilişkilendirmek için Closes #123. Tür/kapsamın hemen ardından gelen bir ! (feat(api)!: ...) da ayrıntılı altbilginin kısaltması olarak uyumsuz bir değişikliği işaretler.

feat(shop)!: switch cart API to new response format
Old clients expecting the previous format break with this
update - only affects internal consumers of the API, no external ones.
BREAKING CHANGE: /api/cart now returns { items: [...] } instead of a
raw array.
Closes #142

Makine tarafından okunabilir yapı sayesinde otomasyon

Gerçek pratik yarar, bu yapıyı otomatik değerlendiren araçlarla ortaya çıkar: semantic-release ve benzeri araçlar, anlamsal sürümlemeye uygun bir sonraki sürüm numarasını doğrudan commit geçmişinden türetebilir — bir feat commit’i küçük sürümü artırır, BREAKING CHANGE içeren bir commit büyük sürümü, fix yalnızca yama sürümünü — ve bundan hemen okunabilir bir değişiklik günlüğü üretir; kimsenin hangi sürümde neyin değiştiğini elle not etmesine gerek kalmaz. Ancak bu, yalnızca depodaki GERÇEKTEN her commit kurala uyarsa güvenilir biçimde çalışır — doğru önek olmayan tek bir commit bile otomatik değerlendirmeyi bozabilir veya yanlış hesaplanmış bir sürüm numarasına yol açabilir.

Diğer yaygın türler

Çekirdek türlerin (feat, fix, refactor, chore, perf) yanı sıra, resmi şartnamenin parçası olmasalar da pratikte başka kurallar yerleşmiştir: docs (salt belgeleme değişiklikleri), test (üretim kodunu değiştirmeden testler ekleme/değiştirme), style (davranış değişikliği olmadan biçimlendirme gibi salt kozmetik değişiklikler) ve build/ci (derleme yapılandırması veya sürekli entegrasyon ardışık düzenlerindeki değişiklikler). Parantez içindeki kapsam isteğe bağlıdır ama tüm farkı (diff) okumadan kod tabanının hangi bölümünün etkilendiğini bir bakışta görmek için yararlıdır — net biçimde ayrılmış modüllere sahip büyük projelerde (örneğin shop, chat, auth) bu, commit geçmişini çok daha aranabilir kılar.

Kuralın sınırları

Conventional Commits yapıyı zorunlu kılar, kaliteyi değil — teknik olarak doğru biçimlendirilmiş bir commit (fix(shop): fixed bug) gerçek neden veya gerekçe eksikse yine de özsel hiçbir şey söylemeyebilir. Bu yüzden birçok ekip salt tür/kapsam yapısını, gövdede “neden”i kısaca açıklama yükümlülüğüyle tamamlar (yalnızca zaten farktan okunabilen “ne”yi değil) — uzun vadede commit iletileri çoğu zaman bir kararın ardındaki saikin belgelenmiş kaldığı tek yerdir.

Ayrıca bak: Next.js App Router, Git