Changelog monorepo: satu saja, atau satu per paket?

Monorepo menampung beberapa hal yang di-deploy terpisah dalam satu repositori, dan sebuah changelog harus menjawab satu pertanyaan dulu: apakah pembaca peduli pada repo, atau peduli pada satu paket tertentu di dalamnya? Kebanyakan tim tidak pernah memutuskan ini dengan sengaja. Mereka mulai dengan satu changelog karena ada satu repo, menambahkan paket seiring waktu, dan berakhir dengan log di mana pengguna CLI harus menggulir melewati empat puluh entri backend yang tidak relevan untuk menemukan entri yang merilis perbaikannya. Yang menentukan bentuk yang tepat bukan struktur repositori, tapi siapa yang membaca log dan apa yang sudah mereka tahu untuk dicari.

Apa yang membuat changelog monorepo berbeda dari repo tunggal?

Changelog repo tunggal punya audiens tersirat: semua orang yang memakai satu-satunya hal yang dibangun repo itu. Audiens monorepo terbagi per paket, dan paket-paket dalam repo yang sama sering dirilis dengan jadwal berbeda, ke konsumen berbeda, pada tingkat stabilitas berbeda. Pustaka yang dipublikasikan di registri dan alat administrasi internal bisa hidup di monorepo yang sama dan hampir tidak punya kesamaan bagi pembaca changelog.

Apakah setiap paket butuh changelog sendiri?

Hanya yang punya audiens independen. Paket yang dipublikasikan di registri butuh log sendiri, karena orang yang menginstalnya tidak punya alasan membaca hal lain di repo, dan alat rilis monorepo seperti Lerna dan Changesets menulis CHANGELOG.md per paket, di sebelah package.json-nya. Utilitas internal dengan satu konsumen, aplikasi yang sudah hidup di repo yang sama, tidak butuh log terpisah; memasukkan perubahannya ke entri aplikasi itu lebih berguna daripada file kedua yang tidak dibuka siapa pun di luar tim.

Ujinya sama dengan yang menentukan apakah suatu entri layak masuk changelog: apakah pembaca akan memperhatikan atau peduli, dan bisakah mereka bertindak dengan mengetahuinya. Terapkan per paket, bukan per folder, dan repo dengan dua belas paket bisa berakhir dengan dua changelog sungguhan dan sepuluh paket yang memang tidak membutuhkannya.

Bagaimana cara tahu paket mana yang menyebabkan entri changelog mana?

Beri label setiap entri dengan paketnya pada saat entri itu ditulis, bukan belakangan dengan memeriksa file mana yang tersentuh sebuah commit. Commit yang memperbaiki pustaka internal bersama bisa menghasilkan entri changelog di setiap paket yang bergantung padanya, dan jalur file saja tidak bisa mengatakan entri hilir mana yang benar-benar perlu dilihat pembaca; hanya orang yang memutuskan “ini terlihat bagi pengguna paket A dan tidak bagi pengguna paket B” yang bisa. Conventional commits membantu di sini secara mekanis, dengan menyebutkan paket di setiap commit, tapi scope tetap hanya menghasilkan draf. Aturan dua lapis yang sama dari artikel itu berlaku per paket: draf dengan scope yang benar tetap butuh sentuhan manusia sebelum diformulasikan untuk pembaca sesungguhnya paket itu.

Apa yang dibutuhkan changelog bersama yang tidak dibutuhkan changelog repo tunggal?

Label paket di setiap entri, paling depan, sebelum deskripsi, agar pembaca yang menyusuri log bisa melewatkan semua yang bukan miliknya dalam satu kali baca. Tanpa label itu, log bersama terbaca seperti feed acak, dan pembaca yang tertarik pada satu paket tidak punya cara menyaringnya selain menghafal baris mana yang penting, yang tidak dilakukan siapa pun setelah minggu pertama.

## 2026-09-07

### [cli] Ditambahkan
- `acme push --dry-run` menampilkan apa yang akan dikirim
  tanpa benar-benar mengirimnya.

### [core] Diperbaiki
- Backoff percobaan ulang tidak lagi direset pada permintaan
  berhasil yang mengembalikan body kosong.

Dua entri, dua audiens, sekali lihat untuk membedakannya. Alur kerja bergaya Changesets membangun pelabelan ini langsung ke proses rilis: kontributor menulis catatan singkat, dengan scope paket, di samping perubahannya, dan alat itu merakit changelog per paket dan lonjakan versi dari catatan itu saat rilis, alih-alih mencoba merekonstruksi batas paket belakangan dari riwayat commit yang sudah digabung.

Bagaimana versioning berkaitan dengan changelog monorepo?

Paket yang diversi secara independen butuh changelog sendiri karena punya nomor versi sendiri, dan changelog bersama tidak bisa menyatakan “paket A naik dari 2.1 ke 2.2 sementara paket B tetap di 1.4” tanpa menjadi dua log dalam satu file. Semantic versioning dan changelog Anda membahas bagaimana nomor versi seharusnya dipetakan ke kategori changelog; dalam monorepo, pemetaan itu harus diterapkan per paket, karena breaking change di satu paket bukan breaking change bagi paket saudara yang tidak bergantung padanya.

Repo yang merilis satu produk sebagai satu unit yang di-deploy, meski dibangun dari banyak paket internal, tidak punya masalah ini: paket-paket berbagi versi karena selalu dirilis bersama, dan satu changelog sudah tepat.

Bagaimana tag git cocok dalam monorepo?

Aturan yang sama dari tag git, rilis, dan changelog Anda berlaku, diterapkan per paket: paket dengan versi sendiri butuh prefiks tag sendiri, biasanya nama-paket@1.4.0 alih-alih v1.4.0 polos yang tidak bisa menyebutkan paket mana yang dimilikinya. Monorepo yang hanya diberi tag dengan nomor versi polos tidak bisa menjawab belakangan “apa yang ada di core saat cli merilis 2.2”, karena tidak ada yang tercatat di disk tentang paket mana yang sebenarnya dimiliki tag itu.

FAQ

Apakah saya butuh changelog terpisah untuk setiap paket dalam monorepo? Hanya untuk paket dengan audiens independen, biasanya apa pun yang dipublikasikan di registri. Paket dengan satu konsumen internal yang sudah hidup di repo yang sama bisa masuk ke log konsumen itu alih-alih memelihara log sendiri.

Apa yang melabeli entri changelog dengan paket yang benar? Orang yang menulis entri itu, pada saat menulisnya, bukan pemindaian otomatis jalur file yang berubah. Perubahan pada pustaka bersama bisa menghasilkan entri berbeda di setiap paket yang bergantung padanya, dan hanya manusia yang bisa memutuskan apa yang sebenarnya harus dikatakan setiap entri hilir itu.

Haruskah monorepo memakai satu nomor versi untuk semuanya? Hanya jika setiap paket selalu dirilis bersama yang lain. Jika paket pernah dipublikasikan secara independen, mereka butuh versi independen, dan versi independen butuh changelog independen agar masuk akal.

Apakah alat changelog monorepo menggantikan langkah penyuntingan manusia? Tidak. Alat seperti Changesets mengotomatiskan pengumpulan dan perakitan catatan per paket saat rilis; catatan itu sendiri, ditulis dalam bahasa pembaca alih-alih bahasa kontributor, tetap menjadi kerja seseorang, sama seperti pipeline changelog lainnya.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Generator changelog, Dokumentasi developer