Conventional commits'ten bir changelog'a

Conventional commits bir changelog’a ücretsiz üç şey verir: her değişikliğin türü, dokunduğu sistem parçası, ve bir şeyi bozup bozmadığı. Başka bir şey vermezler. Changelog olan ifade, gruplandırma ve seçim tamamen açık kalır, ve aksini iddia eden bir pipeline biçimlendirilmiş bir git log gönderir.

feat(exports): add CSV column selection
fix(auth): reject expired refresh tokens
chore(deps): bump node-pg to 8.11

Conventional Commits formatında üç commit. Bunlardan, bir makine size birinin özellik, birinin düzeltme, birinin ev işi olduğunu, ve her birinin sistemin hangi parçasına dokunduğunu söyleyebilir. Bu gerçekten faydalıdır, ve konvansiyonun tüm sözü budur: bir insandan başka bir şey tarafından okunabilen bir commit geçmişi. Hata, bunun size bir changelog verdiğini düşünmektir. Size ham malzemeyi verir.

Konvansiyon neyi belirtir?

Bir tür, isteğe bağlı bir scope, ve bir açıklama: type(scope): description. Türler geleneksel olarak feat, fix, chore, docs, refactor, test, perf, build, ci’dir. İki şey bir breaking change’i işaretler: iki nokta üst üsteden önce bir !, veya bir BREAKING CHANGE: footer’ı. Araçlar minor ve patch sürüm artışları için feat ve fix’e, major için breaking belirtecine göre hareket eder.

Belirteç bunu araca söyler; çağırana söylemez, ki bu bir API nasıl deprecate edilir ve breaking change nedir’in konusudur. Bu küçük bir spesifikasyondur ve ondan hiçbir şey üretmeseniz bile takip etmeye değer, çünkü commit başına bir karar zorlar: bu kullanıcıların gördüğü bir değişiklik mi, değil mi.

Conventional commits nerede durur?

Cümlede dururlar. Konvansiyonun yakaladığı her şey bir değişiklik hakkında metadata’dır; değişimin kendisi hâlâ bir gözden geçirenin kelime dağarcığında tarif edilir.

Commit mesajları gözden geçirenler için yazılır. fix(auth): reject expired refresh tokens doğrudur ve bir müşteriye hiçbir şey söylemez. Bir changelog’un okuyucusu “bir oturum gerçekten süresi dolduğunda çıkış yapacaksınız, ara sıra 401 görmek yerine” ister.

Scope’lar dahilidir. exports, auth, ingest modül isimleridir. Kararlıdırlar, ki bu onları gruplamak için iyi yapar, ve kod tabanının dışındaki herkes için anlamsızdırlar.

Bir değişiklik genellikle birden çok commit’tir. On bir commit’te merge edilen bir özellik on bir girdi üretir, onu gürültü olan, ve bunu gizlemek için squash yapmak inceleme geçmişini kaybettirir.

chore bir kategori değil bir çöp kutusudur. Bağımlılık güncellemeleri, CI değişiklikleri ve yeniden adlandırmaların hepsi oraya iner, ve bazıları kullanıcılar için önemliyken çoğu değildir.

Yani: konvansiyon size tür, scope ve breaking durumunu ücretsiz verir, ve ifadeyi, gruplandırmayı ve seçimi tamamen açık bırakır. Bu üçü changelog’dur. Bir changelog kaydının sahibi gerçekte kimdir o ifadeyi, gruplandırmayı ve seçimi kimin üstlenmesi gerektiğini ele alır, çünkü konvansiyonun kendisinin bu konuda hiçbir görüşü yoktur.

Conventional commits’ten bir changelog nasıl üretilir?

İki katmanda, ve ikincisi zorunlu olmalı.

Katman bir, otomatik. Merge’de, commit’ten bir taslak girdi türetin: bir changelog türüne eşlenmiş tür (feat Added’a, fix Fixed’e, bir flag ile Changed’e bir breaking belirteci), metin yerine metadata olarak tutulan scope, PR’a bağlantı. Keep a Changelog’un istediği Unreleased bölümüne yerleştirin.

Katman iki, insan, ve gerekli. Bir sürüm çıkmadan önce, her taslak girdi ya kullanıcının kelime dağarcığında bir satırlık yeniden yazım alır, ya da dahili olarak işaretlenir ve genel görünümden çıkarılır. Bu, insanların atlamaya çalıştığı adımdır, ve atlamak diff gibi okunan changelog’lar üretir.

Önemli tasarım detayı, katman ikinin pipeline’da isteğe bağlı olmamasıdır. Bir sürüm düzenlenmemiş taslaklarla kesilebiliyorsa, herkesin meşgul olduğu haftada kesilecektir. Hangi adımların makineye, hangilerinin kişiye ait olduğu changelog otomasyonu’nun tamamıdır.

Sürümü kesmek aynı zamanda bir git etiketi, bir sürüm ve bu changelog girişinin ya uyuştuğu ya da senkronizasyondan çıkmaya başladığı andır; git etiketleri, sürümler ve changelog’unuz üçünü senkronize tutmayı ele alır.

Üç tuzak

Squash merge’ler footer’ları yer. Platformunuz PR başlığını mesaj olarak sıkıştırıyorsa, o branch içindeki bir commit’in BREAKING CHANGE: footer’ı kaybolur, ve araçlarınız sessizce breaking change’i görmeyi bırakır. Squash şablonunuzun gerçekte neyi koruduğunu kontrol edin.

Revert commit’leri hayalet girdiler üretir. Ertesi gün geri alınan bir fix, türetim revert’leri uzlaştırmadıkça hiç gönderilmemiş bir şey için bir girdi üretir. Çoğu araç bunu yapmaz.

Sürüm artışı ve changelog düzensizleşir. Sürüm commit’lerden hesaplanıyorsa ve changelog sonradan elle yazılıyorsa, yaklaşık iki sürümde birbirinden ayrılırlar. İkisini de aynı geçişte hesaplayın veya birinin yanlış olduğunu kabul edin.

Pipeline olmadan mekanik kısmı istiyorsanız

Changelog üreticimiz türetim adımını tarayıcıda yapar: commit’leri yapıştırın, gruplandırılmış, türlendirilmiş girdiler alın. Kasıtlı olarak deterministik ve tamamen client-side’dır, bu yüzden yapıştırdığınız commit’ler makinenizi hiç terk etmez, ki bu mesajlar özel bir repodan geldiğinde önemlidir. Toplama yarısını dürüstçe yapar ve katman ikiyi denemez, çünkü katman iki bir yargıdır ve onu taklit eden bir araç tam olarak bu makalenin karşı çıktığı changelog’u üretir.

Pipeline versiyonu için changelog araçları var olanı kapsar.

Özet

Conventional commits “bu ne tür bir değişiklik” sorusunu güvenilir ve ucuz bir şekilde cevaplar. “İnsanlara ne söylemeliyiz” sorusunu cevaplamazlar, ve commit mesajının üzerine ne kadar araç eklerseniz ekleyin bu yapmayacaktır, çünkü bilgi hiçbir zaman commit mesajında değildi. Yeniden yazım için bütçe ayırın.

FAQ

Conventional commits otomatik olarak bir changelog üretir mi? Otomatik olarak bir taslak üretirler: türlendirilmiş, scope’lu, bağlantılı girdiler. Bir müşteri için ifade, gruplandırma ve neyin dışarıda bırakılacağı kararı hâlâ bir insana ihtiyaç duyar, ve o adımı atlayan bir pipeline commit mesajları yayımlar.

Hangi conventional commit türleri bir changelog’da görünür? feat ve fix her zaman, Added ve Fixed olarak. perf genellikle, Changed olarak. chore, docs, refactor, test, build ve ci varsayılan olarak dahilidir ve sadece bir kişi birini terfi ettirirse görünürler.

Conventional commits bir breaking change’i nasıl işaretler? Türden veya scope’tan sonra bir ! (feat(api)!: ...), veya commit gövdesinde bir BREAKING CHANGE: footer’ı. Bir squash merge sadece PR başlığını tutarsa ikisi de kaybolur.

Bir changelog’u otomatikleştirmek için conventional commits gerekli mi? Hayır. PR etiketleri, PR şablonları ve issue bağlantıları, pull request ile merge eden ekipler için aynı metadata’yı taşır. Conventional commits, değişim birimi commit olduğunda en ucuz seçenektir.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Changelog oluşturucu, Changelog araçları karşılaştırması