Konvensi changelog

Konvensi changelog

Halaman ini mendefinisikan kontrak yang diikuti setiap repositori publik NextPDF saat mencatat perubahan dan menerbitkan rilis. Ini adalah rujukan konvensi; halaman ini tidak mendefinisikan perilaku paket. Catatan rilis untuk tiap paket dan tiap versi berada di CHANGELOG.md milik repositori masing-masing. Aturan bersama ini menjaga ringkasan changelog lintas-repo tetap konsisten dan bebas kebocoran.

Conventional Commits 1.0.0

Setiap subjek commit menggunakan type(scope): description. type adalah salah satu dari:

Jenis	Makna	Berdampak ke pengguna	Dampak pada versi
feat	Kemampuan baru	ya	kenaikan minor
fix	Perilaku yang diperbaiki	ya	kenaikan patch
perf	Peningkatan performa tanpa perubahan perilaku	ya	kenaikan patch
refactor	Penataan ulang internal tanpa perubahan yang dapat diamati	tidak	tidak ada
docs	Hanya dokumentasi	tidak	tidak ada
test	Hanya pengujian	tidak	tidak ada
build / ci	Hanya build atau pipeline	tidak	tidak ada
chore	Pemeliharaan, dependensi, atau perkakas	tidak	tidak ada
revert	Pengembalian commit sebelumnya	bergantung	bergantung

Perubahan yang merusak (breaking change) menggunakan ! setelah type atau scope (feat(api)!: …) atau footer BREAKING CHANGE:. Penanda apa pun menaikkan versi major menurut Semantic Versioning. Catat perbaikan yang relevan dengan keamanan agar dapat muncul di kolom Security dalam ringkasan lintas-repo.

Semantic Versioning 2.0.0

Kenaikan versi bersifat mekanis. Rilis yang memuat perubahan merusak apa pun adalah rilis major. Jika tidak, rilis yang memuat feat apa pun adalah rilis minor. Jika tidak, rilis yang memuat fix atau perf apa pun adalah rilis patch. Paket pra-1.0 boleh menaikkan versi minor untuk perubahan merusak sesuai SemVer §4. Commit tersebut tetap membawa penanda perubahan merusak agar ringkasan tetap akurat.

Pengelompokan Keep a Changelog

Setiap repositori memiliki CHANGELOG.md yang mengikuti Keep a Changelog 1.1.0: entri dikelompokkan menurut versi yang dirilis di bawah Added, Changed, Deprecated, Removed, Fixed, dan Security. Bagian [Unreleased] boleh menampung catatan berjalan di dalam repositori, tetapi ringkasan lintas-repo hanya menghitung versi yang diberi tag dan dirilis. Pekerjaan yang belum dirilis tidak pernah muncul di indeks publik.

Cara ringkasan lintas-repo diturunkan (dan dijaga tetap bebas kebocoran)

Tabel ringkasan pada indeks changelog dihasilkan dengan membaca riwayat Conventional Commits setiap repositori pada tag rilis terbarunya secara hanya-baca, lalu menghitung kategorinya. Aturan penurunan ini sengaja dibuat sempit agar detail internal tidak bocor:

1. Jumlah, bukan isi. Hanya jumlah commit per jenis yang berdampak ke pengguna yang dilaporkan. Tidak ada subjek, isi, footer, atau hash commit yang ditampilkan.
2. Hanya jenis yang berdampak ke pengguna. docs, test, ci, chore, dan refactor dikecualikan karena tidak mengubah apa pun yang dapat diamati konsumen paket.
3. Hanya yang sudah dirilis. Commit hanya dihitung setelah menjadi bagian dari rilis bertag pada paket publik.
4. Tanpa pengenal. Rujukan internal seperti issue, tiket, cycle, wave, atau work-item yang mungkin muncul dalam scope commit privat tidak pernah ditampilkan, karena teks scope itu sendiri tidak pernah ditampilkan. Hanya jenisnya yang dibaca.
5. Tanpa atribusi otomatisasi. Trailer otomatisasi kontributor tidak dibaca atau ditampilkan.

Karena alasan itu, changelog publik merupakan ringkasan kategori dengan tautan ke CHANGELOG.md milik tiap paket, bukan feed commit teragregasi. Secara rancangan, ringkasan ini bebas dari kebocoran internal. Narasi rilis yang otoritatif tetap berada bersama paket yang memilikinya.

Lihat juga

• Changelog
• Konvensi resep integrasi
• Conventional Commits 1.0.0
• Semantic Versioning 2.0.0