changeloop blog

Release notes perbaikan bug: cara menulis entri yang berguna

Fri, 02 Oct 2026 00:00:00 GMT

Release notes perbaikan bug yang baik menjelaskan apa yang dilihat pengguna salah, bukan apa yang salah di kode. Setiap entri menyebut siapa yang terdampak, sejak kapan, apakah perbaikannya tuntas, dan apakah pembaca perlu melakukan sesuatu, meskipun itu hanya "tidak ada tindakan yang diperlukan".

Kebanyakan tim menyalin satu baris dari pesan commit. Tabel di bawah menunjukkan enam penulisan ulang, dan bagian sesudahnya menjelaskan aturannya.

Sebelum (pesan commit)	Sesudah (gejala)
Fixed null pointer in export handler	Ekspor tidak lagi gagal dengan "Terjadi kesalahan" ketika proyek tidak punya tag. Jalankan ulang ekspor yang gagal sejak 3 September.
Resolved race condition in sync worker	Edit di dua perangkat dalam selang beberapa detik tidak lagi saling menimpa. Tidak ada yang perlu dilakukan.
Fix timezone bug	Laporan terjadwal kini berjalan pada waktu yang Anda atur. Akun di timur UTC melihat laporan datang hingga sehari lebih awal sejak 12 Agustus. Tidak perlu perubahan.
Patched XSS in comment renderer	Perbaikan keamanan: komentar yang dirancang khusus bisa menjalankan skrip di browser pengguna lain. Upgrade ke 4.2.1 hari ini. Kami tidak melihat eksploitasi di log kami.
Fixed regression from 4.1.0	Pencarian berfungsi lagi untuk kueri yang mengandung tanda hubung. Rusak di 4.1.0 dan diperbaiki di 4.1.1.
Bug fixes and performance improvements	Sebutkan yang mana. Lihat bagian terakhir.

Bagaimana menulis entri perbaikan bug di release notes?

Mulai dengan gejala dalam kata-kata pengguna, lalu siapa yang terdampak dan sejak kapan, lalu status perbaikannya, lalu tindakannya. Satu atau dua kalimat biasanya cukup. Penyebab di kode milik pull request, tempat engineer akan mencarinya.

Pembaca memindai satu hal: "apakah ini saya?" Empat bagian mencakup hampir setiap entri:

Gejalanya. Apa yang muncul di layar, di respons API, atau di invoice. Kutip teks error jika ada, karena orang mencarinya.
Cakupannya. Paket, platform, versi API, atau bentuk data mana. "Akun dengan lebih dari 50.000 baris" bisa dicek. "Sebagian pengguna" tidak.
Rentang waktunya. Sejak rilis atau tanggal berapa, agar pembaca bisa menilai apakah hasil aneh kemarin adalah bug itu.
Tindakannya. Jalankan ulang, sinkronkan ulang, upgrade, hapus workaround, atau tidak sama sekali.

Jika pengguna membuat workaround, baris tindakan adalah tempat Anda memberi tahu bahwa mereka bisa menghapusnya.

Apa perbedaan antara release note dan changelog?

Changelog adalah catatan lengkap dan berkelanjutan tentang perubahan. Release notes adalah pesan terpilih yang ditulis ulang tentang satu rilis untuk orang yang sedang menentukan apakah mereka peduli. Untuk perbaikan bug, changelog mendaftar setiap perbaikan dan catatan memimpin dengan yang mungkin disadari pembaca.

Salah ketik di tooltip hanya masuk changelog. Tarif pajak yang salah di invoice masuk keduanya. Pembagian lengkapnya ada di changelog vs release notes, dan bentuk catatan yang baik ada di cara menulis release notes.

Keep a Changelog adalah konvensi yang praktis untuk sisi pencatatan. Ia menyediakan "Fixed" untuk perbaikan bug dan judul "Security" tersendiri untuk kerentanan, pembagian yang sama dengan yang dibuat artikel ini untuk pembaca.

Apakah perbaikan bug termasuk update?

Ya. Perbaikan bug mengubah produk, jadi merilisnya adalah sebuah update. Menurut semantic versioning, perbaikan yang kompatibel ke belakang adalah rilis patch, misalnya 4.2.0 ke 4.2.1.

Apakah pembaca harus melakukan sesuatu adalah pertanyaan terpisah, dan catatan harus menjawabnya. Perbaikan yang mengubah apa yang diamati pemanggil yang benar sudah mendekati breaking change, dan breaking changes menjelaskan di mana batasnya.

Kapan perbaikan mendapat entri sendiri, dan kapan menjadi perbaikan kecil?

Beri perbaikan entri sendiri ketika pengguna bisa saja menyadari bug itu, kehilangan waktu atau data karenanya, atau membuat workaround. Kelompokkan di bawah daftar singkat "Perbaikan kecil" ketika tidak ada orang di luar tim Anda yang bisa melihatnya. Nilai dari pengalaman pembaca, bukan ukuran diff.

Mendapat entri sendiri	Masuk daftar perbaikan kecil
Dilaporkan pelanggan atau dialami banyak orang	Cacat kosmetik di layar yang jarang dibuka
Menyebabkan output salah, job gagal, atau pekerjaan hilang	Salah ketik, spasi, ikon yang tidak sejajar
Butuh tindakan dari pembaca	Perbaikan di alat internal atau halaman admin
Regresi dari rilis terbaru	Kegagalan yang hanya terlihat di lingkungan tes
Menyentuh penagihan, izin, atau data	Teks log, bump dependensi tanpa efek bagi pengguna

Setiap baris dalam kelompok itu tetap harus mengatakan sesuatu: "Memperbaiki beberapa masalah UI" hanyalah placeholder.

Bagaimana menulis tentang regresi?

Sebutkan rilis yang memperkenalkannya, sebut itu regresi, dan beri rilis yang memperbaikinya. Orang yang terkena bug itu sudah tahu ada yang rusak, jadi pengakuan singkat dan langsung lebih berguna bagi mereka daripada kata-kata yang samar.

Misalnya: "Hasil pencarian untuk kueri yang mengandung tanda hubung kosong di 4.1.0. Ini sudah diperbaiki di 4.1.1. Jika Anda mengubah kueri untuk menghindari tanda hubung, Anda bisa mengembalikannya."

"Meningkatkan keandalan pencarian" terbaca sebagai berkelit bagi siapa pun yang kehilangan satu sore karena bug itu. Jika penyebabnya masih dikonfirmasi, katakan, seperti yang dinyatakan panduan release notes darurat: jangan biarkan catatan terdengar lebih yakin daripada tim.

Bagaimana mengumumkan perbaikan keamanan?

Nyatakan tingkat keparahan dengan jelas, sebut versi yang terdampak dan versi yang memperbaikinya, katakan seberapa mendesak upgrade-nya, dan sertakan pengenal CVE jika ada. Terbitkan detail hanya setelah pengguna bisa bertindak atas perbaikan, mengikuti proses pengungkapan terkoordinasi ketika ada pelapor.

Urutannya penting: pelapor memberi tahu Anda secara privat, Anda merilis perbaikan, dan catatan publik terbit ketika pengguna bisa melindungi diri. Proses pengungkapan kerentanan terkoordinasi CISA mengoordinasikan pelaporan, analisis, dan pengungkapan publik kerentanan. Aturan CVE Numbering Authority mengatur bagaimana catatan CVE diberikan dan diterbitkan, dan di GitHub repository security advisory memungkinkan Anda menyusun advisory secara privat dan meminta pengenal.

Entri keamanan biasanya memuat empat fakta:

Apa yang bisa dilakukan penyerang, dalam satu kalimat dan tanpa proof of concept.
Versi yang terdampak, dan versi yang memperbaikinya.
Seberapa mendesak: "upgrade hari ini" atau "upgrade pada rilis Anda berikutnya".
Apakah Anda pernah melihat eksploitasi, dan kredit untuk pelapor jika mereka setuju.

Jangan sertakan langkah eksploit.

Apa yang harus dikatakan catatan tentang perbaikan kehilangan data?

Sebutkan data apa yang terdampak, cara mengetahui apakah data Anda terkena, dan apakah bisa dipulihkan. "Tidak ada tindakan yang diperlukan" jarang benar di sini, dan pertanyaan pertama pembaca adalah "apakah data saya hilang".

Entri yang berguna memberi kondisi yang menghilangkan data ("menghapus folder saat sinkronisasi berjalan"), rentang waktu saat itu mungkin terjadi, cara memeriksa ("buka Sampah dan cari item bertanggal 3 sampai 9 September"), dan jalur pemulihan. Jika data tidak bisa dipulihkan, katakan. Hubungi pelanggan yang terdampak secara langsung juga, karena release note tidak boleh menjadi satu-satunya tempat seseorang mengetahui datanya terkena.

Mengapa "Perbaikan bug dan peningkatan performa" adalah catatan yang buruk?

Kalimat itu tidak memberi pembaca apa pun untuk ditindaklanjuti dan menyembunyikan perbaikan yang sedang ditunggu seseorang. Pelanggan yang melaporkan crash tidak tahu apakah sudah diperbaiki, dan pelanggan dengan workaround tidak tahu apakah harus menghapusnya.

Ada dua alternatif yang jujur. Jika sebuah rilis tidak punya apa pun yang bisa disadari pembaca, jangan terbitkan catatan dan biarkan changelog menyimpan catatannya. Jika ada perbaikan, daftarkan dengan bahasa pembaca:

Sebelum:
  Perbaikan bug dan peningkatan performa.

Sesudah:
  Diperbaiki: ekspor CSV gagal untuk proyek tanpa tag.
  Diperbaiki: mode gelap menyembunyikan kursor di kotak komentar.
  Lebih cepat: dasbor terbuka lebih cepat untuk workspace
  dengan lebih dari 100 proyek.

Dari mana asal catatan perbaikan bug?

Asalnya dari pull request yang memperbaiki bug dan laporan yang memicunya. Jika kata-kata pelapor ikut bersama perbaikannya, separuh gejalanya sudah tertulis.

Permintaan fitur vs bug menjelaskan mengapa melabeli laporan dengan benar menentukan siapa pemiliknya. Di Changeloop, bug yang dilaporkan lewat widget menjadi GitHub issue berlabel bug, dan entri changelog disusun dari pull request yang di-merge lalu ditahan agar seseorang menyetujuinya sebelum terbit. Template release notes memberi bentuk entri yang sama untuk menulis manual: gejala, cakupan, rentang waktu, tindakan.

FAQ

Apa yang harus dimuat release notes perbaikan bug? Setiap entri harus menyebut gejala yang dilihat pengguna, siapa yang terdampak, sejak rilis atau tanggal berapa, apakah perbaikannya tuntas, dan apa yang perlu dilakukan pembaca, termasuk "tidak ada".

Haruskah setiap perbaikan bug dicantumkan di release notes? Tidak. Cantumkan yang bisa disadari pengguna, yang membuang waktu mereka, atau yang mereka akali, dan kelompokkan perbaikan kosmetik atau internal di bawah daftar singkat "Perbaikan kecil". Changelog menyimpan setiap perbaikan untuk siapa pun yang perlu mencarinya.

Bagaimana menulis release notes untuk bug yang Anda perkenalkan sendiri? Katakan itu regresi, sebut rilis yang memperkenalkannya dan rilis yang memperbaikinya, dan beri tahu pembaca apakah mereka boleh menghapus workaround. Pernyataan yang lugas terbaca lebih baik daripada kata-kata yang dihaluskan.

Bagaimana memeriksa release notes produk yang Anda pakai? Cari halaman changelog atau release notes yang ditautkan dari menu bantuan, footer, atau dokumentasi produk, atau di tab releases repositori untuk proyek open source.

Cara meminta umpan balik pelanggan di produk software

Fri, 02 Oct 2026 00:00:00 GMT

Untuk meminta umpan balik pelanggan di produk software, ajukan satu pertanyaan spesifik tentang sesuatu yang baru saja dilakukan pengguna, di tempat mereka melakukannya. "Bagaimana hasil mengekspor laporan tadi?" tepat setelah ekspor akan dijawab. "Beri tahu kami pendapat Anda tentang produk kami" di footer hanya mendapat kesunyian. Sisa halaman ini berisi momen, kanal, dan kalimat persisnya.

Kebanyakan saran soal topik ini ditulis untuk toko dan meja layanan. Tim software tahu persis apa yang dilakukan pengguna sedetik lalu, jadi pertanyaannya bisa tentang hal itu.

Momen	Tempat bertanya	Kalimat siap pakai
Tepat setelah tugas selesai	Di aplikasi, di samping hasilnya	"Apakah ekspor itu sesuai kebutuhan Anda?"
Setelah pemakaian pertama fitur baru	Di aplikasi, sekali saja	"Apa yang ingin Anda capai dengan Bulk Edit?"
Setelah tiket support selesai	Di thread support	"Apakah itu menyelesaikannya, atau masih ada yang janggal?"
Setelah pengguna berhenti atau keluar dari sebuah alur	Email, sehari kemudian	"Anda berhenti di langkah 3 setup. Apa yang menghalangi?"
Setelah 30 hari pemakaian rutin	Email dari orang yang disebut namanya	"Satu hal apa yang akan Anda ubah?"
Saat pengguna berhenti berlangganan	Di alur pembatalan	"Apa yang membuat Anda memutuskan pergi hari ini?"
Setelah Anda merilis sesuatu yang mereka minta	Di tempat mereka memintanya	"Anda meminta impor CSV. Sudah live. Apakah cocok dengan kasus Anda?"

Kapan waktu yang tepat untuk meminta umpan balik?

Waktu yang tepat adalah tepat setelah pengguna menyelesaikan sesuatu, selagi detailnya masih ada di kepala mereka. Pertanyaan yang mengikuti sebuah tindakan mendapat jawaban tentang tindakan itu. Pertanyaan yang muncul tiba-tiba mendapat jawaban tentang suasana hati orang itu saat itu, atau tidak dijawab sama sekali.

Jangan bertanya saat pendaftaran, karena belum ada yang dipakai. Jangan bertanya di tengah tugas, karena Anda mengganggu hal yang ingin Anda pelajari. Setelah seseorang menjawab, biarkan mereka sampai Anda punya sesuatu untuk dilaporkan kembali.

Di mana sebaiknya Anda meminta umpan balik pelanggan?

Bertanyalah di tempat pengalaman itu terjadi. Prompt di dalam aplikasi cocok untuk pertanyaan tentang sebuah layar. Thread support cocok untuk pertanyaan tentang sebuah perbaikan. Email cocok untuk pertanyaan tentang seminggu pemakaian, atau tentang alur yang ditinggalkan orang. Panggilan cocok untuk pertanyaan yang tidak bisa Anda duga.

Setiap kanal menghasilkan jenis jawaban yang berbeda:

Di aplikasi: singkat, langsung, dan spesifik, tetapi hanya dari orang yang sedang hadir. Anda tidak mendengar apa pun dari pengguna yang sudah pergi.
Thread support: dari orang yang sudah cukup kesal untuk menulis. Bagus untuk menemukan hal yang rusak, kurang baik untuk menilai sisa produk.
Email: jawaban lebih panjang dari lebih sedikit orang, dan satu-satunya cara menjangkau pengguna yang sudah diam. Tulis sebagai catatan singkat dari orang yang disebut namanya, dengan satu pertanyaan di dalamnya.
Wawancara: cara untuk mempelajari mengapa orang melakukan sesuatu. Minta mereka menunjukkan cara kerja mereka, dan diamlah selagi mereka melakukannya.

Kualitas sinyal umpan balik membahas cara menimbang apa yang dikatakan setiap kanal.

Bagaimana cara meminta umpan balik secara profesional?

Spesifik soal hal yang ditanyakan, jelaskan mengapa Anda bertanya, dan buat jawabannya memakan waktu kurang dari semenit. Permintaan yang profesional menyebut momennya, menegaskan bahwa seorang manusia akan membaca jawabannya, dan tidak meminta maaf karena mengganggu.

Sebut tindakan persisnya ("ekspor yang baru Anda jalankan"), minta satu hal, pakai kotak teks bebas tanpa kolom wajib, dan tanda tangani dengan nama depan.

Apa kalimat yang baik untuk meminta umpan balik?

Kalimat yang baik adalah pertanyaan tentang momen tertentu yang bisa dijawab dalam beberapa kata. Bandingkan dua kolom di bawah ini. Yang kiri bisa dijawab dengan angkat bahu. Yang kanan mengharuskan orang mengingat sesuatu yang nyata.

Pertanyaan lemah	Pertanyaan lebih kuat
"Ada masukan?"	"Apa bagian tersulit saat menyiapkan ini?"
"Bagaimana pendapat Anda tentang produk kami?"	"Untuk apa Anda memakai ini minggu lalu?"
"Nilai pengalaman Anda dari 1 sampai 10."	"Apakah Anda menyelesaikan yang ingin Anda lakukan hari ini?"
"Beri tahu kami cara memperbaiki."	"Apa satu hal yang memperlambat Anda minggu ini?"
"Maukah Anda merekomendasikan kami?"	"Kepada siapa terakhir kali Anda menunjukkan ini, dan apa yang Anda katakan?"

Satu lagi yang cocok hampir di mana saja: "Apa yang Anda pakai sebagai gantinya ketika ini tidak berhasil untuk Anda?" Pertanyaan ini memunculkan pesaing yang sebenarnya, yang sering kali berupa spreadsheet.

Apa cara terburuk untuk meminta umpan balik?

Permintaan terburuk itu terlalu luas, terlalu dini, terlalu panjang, atau menggiring. Semuanya punya masalah yang sama: orang tidak bisa menjawab tanpa melakukan pemikiran yang seharusnya Anda lakukan.

"Mohon isi survei 20 pertanyaan kami." Yang menyelesaikannya adalah orang dengan waktu luang paling banyak atau pendapat paling kuat.
Popup di halaman pertama setelah login. Pengguna datang untuk melakukan sesuatu dan Anda menghalanginya. Menutupnya adalah satu-satunya jawaban yang masuk akal.
"Kami sangat menantikan masukan Anda!" tanpa pertanyaan. Ini meminta pengguna mengarang topiknya.
Pertanyaan menggiring: "Seberapa suka Anda dengan dasbor baru?" Anda mendapat persetujuan dan tidak belajar apa-apa.
Penilaian tanpa tindak lanjut. Angka 6 dari 10 memberi tahu suasana hati. Ia tidak memberi tahu apa yang harus diubah.
Bertanya, lalu diam. Ini merugikan putaran berikutnya, yang dibahas di bawah.

Apa sebutan untuk umpan balik pelanggan tentang produk?

Umpan balik tentang produk biasanya disebut umpan balik produk, dan terbagi menjadi dua jenis. Laporan bug menyatakan sesuatu tidak berfungsi sebagaimana mestinya. Permintaan fitur menyatakan ada yang kurang. Pembedaan ini menentukan siapa yang melihatnya lebih dulu, dan permintaan fitur vs bug menarik garisnya. Jenis ketiga, pujian, layak disimpan dan dikutip dengan izin.

Formulir umpan balik yang menawarkan "Bug" dan "Permintaan fitur" sebagai pilihan pertama sudah melakukan penyortiran awal itu untuk Anda.

Apa yang dilakukan dengan jawabannya?

Taruh setiap jawaban di tempat tim sudah bekerja, dengan kata-kata orang itu tetap utuh. Satu baris kutipan lebih baik daripada ringkasan Anda. Beri tag menurut jenis dan perkiraan urgensi, gabungkan yang berulang, lalu putuskan: bangun, tunda, atau tolak.

Menolak juga merupakan jawaban. "Kami tidak akan membangun ini, dan inilah alasannya" mengakhiri penantian, dan menolak permintaan fitur punya contoh kalimatnya. Untuk saluran pipanya, melacak permintaan fitur menjelaskan cara membawa permintaan dari lima kanal ke satu daftar. Jika Anda menerima permintaan secara tertulis, template permintaan fitur menjaga agar permintaan bisa dibandingkan.

Widget Changeloop menyimpan setiap kiriman sebagai GitHub issue, sehingga umpan balik mendarat di samping kode yang akan memperbaikinya. Dengan alat apa pun aturannya sama: satu daftar, satu pemilik, tidak ada jawaban yang tertinggal di kotak masuk seseorang.

Mengapa memberi tahu orang apa yang dirilis?

Itu menunjukkan kepada orang tersebut bahwa menjawab ada gunanya. Pengguna yang pernah memberi tahu Anda sesuatu lalu mendengar "ini sudah dirilis, terima kasih" punya alasan untuk menjawab lagi. Yang tidak mendengar apa-apa menyimpulkan bahwa kotak itu tidak dibaca.

Jadi langkah terakhir dalam meminta adalah membalas. Beri tahu setiap orang yang meminta kapan permintaannya dirilis, dengan bahasa mereka, lewat kanal yang mereka pakai. Menutup lingkaran umpan balik pelanggan menjelaskan mekanismenya: entri changelog yang diterbitkan adalah pemicu pesan, sehingga peminta baru diberi tahu setelah perubahan itu live. Di Changeloop, ketika umpan balik widget menjadi issue GitHub dan pull request yang digabung menutupnya, menyetujui entri akan memposting komentar "Shipped" di issue itu dan menampilkan entri itu ke pengirim di widget; issue yang dibuat manual, serta repositori GitLab atau Bitbucket, tidak mendapat komentar. Dokumentasi kami mencantumkan pengaturan widget dan feed.

Balasan bisa singkat: "Anda meminta impor CSV pada bulan Maret. Hari ini sudah live, dan begini cara kerjanya." Itu juga memberi Anda pertanyaan berikutnya yang terbaik, yaitu apakah fitur itu mencakup yang mereka butuhkan.

Rencana awal

Pilih satu momen dari tabel di atas, yaitu saat pengguna paling sering berhasil atau menyerah. Tulis satu pertanyaan untuknya, taruh di satu kanal, dan baca setiap jawaban selama dua minggu sebelum menambah prompt kedua. Balas siapa pun yang memberi sesuatu yang konkret.

FAQ

Seberapa sering Anda sebaiknya meminta umpan balik pelanggan? Kaitkan permintaan dengan peristiwa, bukan kalender. Pengguna sebaiknya melihat paling banyak satu prompt seminggu, dan tidak ada tepat setelah menjawab satu. Pesan berikutnya setelah umpan balik sebaiknya berupa balasan tentang apa yang terjadi padanya.

Bagaimana meminta umpan balik tanpa mengganggu pengguna? Bertanyalah setelah tugas, bukan di tengahnya, batasi pada satu pertanyaan, dan buat mudah ditutup. Hormati penutupan itu selama beberapa minggu.

Haruskah menawarkan insentif untuk umpan balik? Biasanya tidak perlu. Pertanyaan yang spesifik dan balasan yang terlihat lebih berbobot daripada voucher, dan insentif menarik orang yang mengejar hadiahnya. Simpan untuk wawancara, ketika Anda meminta 20 menit waktu seseorang.

Bagaimana jika tidak ada yang menjawab? Persempit pertanyaannya dan dekatkan ke momennya, misalnya satu layar, ditanyakan tepat setelah dipakai. Jika tetap sepi, kirim email langsung ke beberapa pengguna dan pakai percakapan itu untuk menulis prompt yang lebih baik.

Contoh roadmap produk: enam format dan cara gagalnya

Fri, 02 Oct 2026 00:00:00 GMT

Contoh roadmap produk yang layak ditiru terbagi menjadi enam format: Now/Next/Later, linimasa kuartalan, roadmap tema, roadmap berbasis hasil, roadmap publik, dan roadmap rilis internal. Masing-masing menjawab pertanyaan yang berbeda untuk pembaca yang berbeda, jadi contoh yang tepat adalah yang cocok dengan siapa yang akan membaca roadmap Anda. Tata letak adalah hal terakhir yang diputuskan.

Setiap contoh di bawah ini untuk produk rekaan, sebuah aplikasi tugas tim kecil, dan semua itemnya karangan. Yang penting adalah bentuknya: apa yang masuk ke setiap slot, seperti apa entri yang nyata, dan apa yang membuat format itu rusak setelah satu kuartal.

Apa saja contoh roadmap produk yang baik?

Contoh roadmap yang baik itu singkat, menyebut pembacanya, dan membuat satu jenis janji. Pilih format berdasarkan janji yang sanggup Anda tepati: arah, tanggal, tema pekerjaan, hasil, komitmen publik, atau jadwal pengiriman.

Format	Dibuat untuk	Berhasil bila	Gagal bila
Now/Next/Later	Seluruh perusahaan	Rencana sering berubah	"Next" penuh dan berubah menjadi antrean
Linimasa kuartalan	Sales, support, eksekutif	Tanggal memang kendala nyata	Tanggal mundur dan tidak ada yang memperbarui
Berbasis tema	Pimpinan, karyawan baru	Anda ingin menjelaskan alasannya	Tema terlalu luas sehingga item apa pun cocok
Berbasis hasil	Produk dan engineering	Tujuannya bisa diukur	Metriknya tidak punya pemilik atau data
Publik	Pelanggan	Anda bisa menjaganya tetap kecil	Berubah menjadi tumpukan backlog
Rilis internal	Engineering, QA, support	Beberapa tim merilis bersama	Disangka strategi

Seperti apa tiap contoh roadmap produk?

Setiap format di bawah ini ditampilkan dengan entri yang realistis, diikuti siapa yang cocok memakainya, kapan ia bertahan, dan bagaimana biasanya ia gagal.

Now/Next/Later

NOW (sedang dibangun bulan ini)
  Tampilan tersimpan di inbox
  Ekspor CSV yang berfungsi untuk akun besar
NEXT (sudah diputuskan, urutan belum pasti)
  SSO untuk paket Team
  Notifikasi Slack
LATER (arah, belum ada komitmen)
  Aplikasi mobile
  Log audit

Format ini cocok untuk perusahaan yang tidak ingin menjanjikan tanggal, seperti banyak tim tahap awal. Ia bertahan karena tiga kolomnya menggambarkan seberapa pasti Anda: "now" sedang dikerjakan, "next" sudah diputuskan, "later" masih harapan. Ia gagal ketika "later" menjadi tempat parkir semua ide yang tidak mau ditolak siapa pun, dan ketika "next" diam-diam mendapat urutan dan tanggal tanpa ada yang menyebutnya linimasa.

Linimasa atau roadmap kuartalan

Q4 2026
  Okt   Tampilan tersimpan di inbox
  Nov   SSO beta dengan lima mitra desain
  Des   SSO tersedia umum
Q1 2027
  Jan   Notifikasi Slack
  Mar   Log audit (hanya ekspor)

Format ini cocok untuk sales, support, dan keuangan, yang perlu merencanakan sesuatu. Ia berhasil ketika tanggal adalah kendala nyata, seperti kontrak, konferensi, atau tenggat kepatuhan. Ia gagal ketika tanggal hanyalah tebakan, karena satu bulan di roadmap bisa berubah menjadi janji di deck penjualan dalam hitungan minggu. Jika memakai format ini, tandai setiap kuartal sebagai komitmen atau perkiraan, dan buat kuartal kedua terlihat jelas lebih longgar daripada yang pertama.

Roadmap berbasis tema

TEMA: Pengalaman minggu pertama
  Impor dari CSV dan Trello
  Template awal
TEMA: Siap untuk tim yang lebih besar
  SSO
  Log audit
  Izin berbasis peran
TEMA: Lebih sedikit langkah manual
  Notifikasi Slack
  Tugas berulang

Format ini cocok untuk pembaruan ke pimpinan dan karyawan baru, karena ia menjelaskan mengapa pekerjaan itu ada sebelum mendaftar pekerjaannya. Ia bertahan ketika setiap tema berkaitan dengan alasan yang dipedulikan pelanggan. Ia gagal ketika temanya terlalu lebar ("Pertumbuhan", "Kualitas") sehingga setiap item cocok di bawah tema mana pun, dan pengelompokan itu tidak menjelaskan apa-apa lagi.

Roadmap berbasis hasil

TUJUAN: Lebih banyak tim baru menyelesaikan setup
  Metrik: setup selesai dalam 7 hari, 40% menjadi 55%
  Taruhan: impor CSV, template awal
TUJUAN: Lebih sedikit tiket support soal ekspor
  Metrik: tiket ekspor per minggu, 30 menjadi 10
  Taruhan: perbaikan ekspor akun besar, halaman status ekspor

Angkanya hanya ilustrasi, dan tata letaknyalah intinya: satu tujuan, satu metrik dengan titik awal dan target, serta taruhan yang akan Anda coba. Format ini cocok untuk tim produk dan engineering yang dipercaya memilih solusinya sendiri. Ia berhasil ketika metriknya ada dan seseorang memilikinya. Ia gagal ketika tujuannya tidak terukur, atau ketika "taruhan" itu sama saja dengan daftar fitur sebelumnya yang ditempeli kalimat hasil di atasnya.

Roadmap publik untuk pelanggan

DIRENCANAKAN
  Tampilan tersimpan di inbox
SEDANG DIBANGUN
  Notifikasi Slack
DIRILIS
  Ekspor CSV untuk akun besar

Ini format terkecil, dan janjinya paling kuat. Ia cocok untuk pelanggan, yang ingin tahu apakah permintaan mereka didengar. Ia bertahan dengan sangat sedikit item, tanpa tanggal, dan judul yang ditulis dengan kata-kata pelanggan. Ia gagal sebagai tempat pembuangan backlog: setiap "mungkin" yang Anda cantumkan adalah janji yang kelak akan ditagih seseorang. Cara menjalankannya dari issue tracker Anda ada di roadmap publik dalam tiga kolom, jadi tidak diulang di sini.

Roadmap rilis internal

Rilis	Target	Pemilik	Bergantung pada	Status
5.2	14 Okt	Platform	Upgrade layanan auth	Kode selesai
5.3	11 Nov	Inbox	API tampilan tersimpan	Sedang berjalan
5.4	9 Des	Platform	Kontrak vendor SSO	Terblokir

Format ini cocok untuk engineering, QA, dan support, yang perlu tahu apa yang dirilis bersamaan dan apa yang menghambat apa. Ia berhasil ketika akurat sampai ke minggunya dan setiap baris punya pemilik. Ia gagal ketika seseorang mengira ini strategi: jadwal pengiriman menyebut apa yang akan keluar dan kapan, dan tidak mengatakan apa-apa tentang apakah rilis-rilis itu taruhan yang tepat.

Format roadmap produk mana yang harus dipilih?

Pilih berdasarkan pembaca dulu, lalu berdasarkan seberapa pasti Anda sebenarnya. Jika Anda tidak bisa menyebut siapa yang membaca roadmap dan keputusan apa yang dibantu olehnya, tidak ada contoh di atas yang bisa menyelamatkannya.

Pelanggan yang bertanya "apakah kalian mendengar saya?" Pakai format publik, dan batasi pada beberapa item.
Sales dan support yang bertanya "bisakah saya memberi tahu pelanggan tanggalnya?" Pakai linimasa kuartalan, dengan komitmen dan perkiraan dipisahkan jelas.
Pimpinan yang bertanya "mengapa pekerjaan ini?" Pakai tema, atau hasil jika Anda punya datanya.
Tim yang berubah arah tiap bulan. Pakai Now/Next/Later dan tahan godaan untuk memberinya tanggal.
Engineer yang bertanya "apa yang dirilis kapan?" Pakai roadmap rilis, dan pisahkan dari yang strategis.

Kebanyakan tim akhirnya punya dua: roadmap strategis dalam salah satu dari empat bentuk pertama, dan jadwal rilis di bawahnya. Roadmap publik lalu menjadi tampilan tersaring dari yang strategis, hanya menampilkan apa yang siap Anda pertanggungjawabkan.

Bagaimana cara menulis roadmap produk?

Tulis roadmap dengan menyebut pembacanya, memilih format yang sesuai dengan pertanyaan mereka, mendaftar hanya item yang akan Anda pertahankan dalam rapat, dan memberi setiap item status serta pemilik. Lalu putuskan seberapa sering roadmap itu ditinjau sebelum Anda menerbitkannya.

Sebutkan pembaca dan keputusannya. "Support memutuskan apa yang dikatakan ke pelanggan soal SSO" adalah alasan. "Semua orang harus melihat roadmap" tidak memberi apa pun untuk dirancang.
Mulai dari yang sudah Anda ketahui. Permintaan yang terbuka, diurutkan dengan aturan yang bisa Anda jelaskan, adalah bahan mentah yang lebih baik daripada brainstorming.
Tulis setiap item sebagai hasil bagi pelanggan. "Simpan filter yang sering Anda pakai" lebih enak dibaca daripada "Implementasi persistensi tampilan tersimpan", dan memberi tahu pelanggan apakah itu masalah mereka.
Putuskan apa yang tidak akan ada di roadmap. Tanggal, estimasi, dan backlog ide adalah tiga pengecualian yang umum.
Tetapkan tanggal tinjauan. Roadmap tanpa tinjauan terjadwal punya pemakaman yang tidak terjadwal.

Bagaimana menjaga roadmap produk tetap mutakhir?

Jaga roadmap tetap mutakhir dengan memindahkan item saat pekerjaan bergerak, dari tempat yang sama dengan tempat pekerjaan dilacak, dan dengan mencatat apa yang terjadi saat item dirilis atau dibatalkan. Roadmap yang diperbarui manual di alat terpisah menjadi usang karena itu bukan pekerjaan harian siapa pun.

Sumber kebenaran termurah adalah issue tracker. Jika setiap kolom roadmap sesuai dengan sebuah label di issue, roadmap berubah ketika labelnya berubah, dan tidak ada yang diketik ulang. Versi Changeloop memakai label roadmap:planned, roadmap:building, dan roadmap:shipped, dan ketika sebuah issue membawa dua label, yang paling maju yang menang. Memindahkan kartu ke shipped tetap merupakan perubahan label tersendiri, jadi jadikan itu bagian dari tinjauan tempat Anda menyetujui entri changelog.

Entri itu adalah separuh lainnya. Ketika item dirilis, changelog menyebutkan apa yang berubah dalam bahasa pelanggan, dan peminta yang menginginkannya bisa diberi tahu. Menutup lingkaran itu adalah inti dari lingkaran umpan balik pelanggan, dan roadmap adalah bagian lingkaran itu yang bisa dilihat pelanggan sebelum apa pun dirilis. Jika Anda membatalkan sebuah item, katakan; "tidak" secara publik juga menutup permintaan itu, dan menolak permintaan fitur membahas cara menyusun kalimatnya. Tim yang ingin melihat seperti apa entri jadi bisa menjelajahi contoh changelog.

FAQ

Apa format roadmap produk yang paling sederhana? Now/Next/Later. Formatnya hanya tiga kolom, tidak butuh tanggal, dan mengelompokkan item berdasarkan kepastian. Untuk tim kecil yang sering berubah arah, ini juga format yang paling sulit dibuat salah secara memalukan.

Berapa banyak item yang sebaiknya ada di roadmap produk? Lebih sedikit dari yang Anda kira. Kurang dari sepuluh item di semua kolom sudah cukup untuk roadmap publik, dan roadmap strategis internal jarang butuh lebih dari selusin. Lebih dari itu, ia hanya backlog dengan judul yang lebih bagus.

Haruskah roadmap produk mencantumkan tanggal? Hanya jika tanggalnya memang kendala nyata, dan hanya untuk kuartal terdekat. Setelah itu, pakai kolom atau tema. Tanggal di roadmap menjadi komitmen dalam percakapan penjualan, entah Anda bermaksud begitu atau tidak.

Apa perbedaan antara roadmap produk dan rencana rilis? Roadmap menyatakan apa yang ingin Anda bangun dan mengapa. Rencana rilis menyatakan build mana yang dirilis pada tanggal berapa dan siapa pemiliknya. Roadmap berubah ketika strategi Anda berubah, dan rencana rilis berubah ketika pekerjaannya berubah.

Proses manajemen rilis untuk tim yang sering merilis

Fri, 02 Oct 2026 00:00:00 GMT

Proses manajemen rilis adalah rangkaian langkah yang membawa sebuah perubahan dari "sudah di-merge" ke "berjalan di produksi dan dijelaskan kepada orang yang terdampak". Untuk tim yang sering merilis, prosesnya terdiri dari tujuh langkah: merencanakan cakupan, mengisolasi perubahan, build dan tes, persetujuan, deploy dan verifikasi, komunikasi, dan tinjauan. Setiap langkah butuh satu pemilik bernama dan satu kriteria selesai, atau langkah itu diam-diam berhenti dilakukan.

Panduan ini mengasumsikan tim berisi 5 sampai 50 engineer yang deploy mingguan atau harian dan ingin prosesnya tidak menghalangi.

Langkah	Pemilik	Kriteria selesai
1. Merencanakan cakupan	Product atau tech lead	Daftar perubahan di rilis ini tertulis, dan yang berisiko ditandai
2. Branch atau flag	Engineer pemilik perubahan	Pekerjaan ada di branch berumur pendek atau di balik flag, sehingga main tetap siap rilis
3. Build dan tes	CI, dengan penulis siaga untuk kegagalan	Pipeline hijau pada commit persis yang akan dirilis
4. Persetujuan	Reviewer, plus release manager untuk perubahan berisiko	Review selesai, jalur rollback disebut, keputusan go atau no-go dicatat
5. Deploy dan verifikasi	Release manager atau engineer on-call	Ter-deploy, smoke check lulus, error rate dan latensi sesuai baseline sebelum rilis
6. Komunikasi	Orang yang memahami perubahan, disunting orang yang tidak	Release notes terbit di tempat pengguna membaca, support dan sales diberi tahu
7. Tinjauan	Release manager	Metrik dibaca, apa pun yang salah punya pemilik dan perbaikan

Apa itu proses manajemen rilis?

Itu adalah jalur berulang yang diikuti sebuah perubahan untuk sampai ke pengguna: cakupan, build, tes, persetujuan, deploy, verifikasi, pengumuman, dan meninjau kembali. Gunanya menuliskannya adalah agar setiap rilis mengikuti jalur yang sama, sehingga orang yang sedang cuti, karyawan baru, atau engineer on-call pukul 2 pagi bisa menjalankannya tanpa bertanya kepada siapa pun cara kerjanya.

Apa saja jenis manajemen rilis?

Ada tiga jenis yang praktis: continuous deployment, rilis terjadwal, dan manajemen perubahan yang diatur regulasi. Ketiganya berbeda dalam seberapa banyak yang terjadi sebelum rilis dan seberapa banyak yang diotomatisasi. Continuous deployment merilis setiap perubahan yang di-merge, rilis terjadwal mengelompokkan perubahan dalam satu kereta, dan manajemen perubahan terregulasi menambahkan persetujuan formal dan jejak audit.

	Continuous deployment	Rilis terjadwal	Manajemen perubahan terregulasi atau ITIL
Unit rilis	Satu pull request yang di-merge	Satu batch, mingguan atau dua mingguan	Satu permintaan perubahan
Langkah cakupan	Implisit, merge adalah cakupannya	Rapat perencanaan rilis	Catatan perubahan dengan peringkat risiko
Persetujuan	Code review plus pemeriksaan otomatis	Release manager mengesahkan batch	Change advisory board atau penyetuju yang didelegasikan
Kontrol risiko	Feature flag, canary, rollback cepat	Staging soak, release candidate	Rencana backout terdokumentasi, jendela pemeliharaan
Kadens umum	Banyak per hari	Mingguan sampai bulanan	Ditetapkan kalender perubahan
Titik lemah	Tidak ada yang memberi tahu pengguna apa yang berubah	Batch besar menyembunyikan perubahan yang merusak	Waktu proses melampaui perubahannya sendiri

Kebanyakan tim adalah campuran. Produk SaaS bisa deploy secara kontinu sementara aplikasi mobile-nya keluar dalam kereta mingguan, dan satu layanan pembayaran yang diperhatikan auditor mengikuti catatan perubahan formal. Pilih jenisnya per layanan, bukan per perusahaan. Ketika perubahan hanya diekspos bertahap, rilis dan pengumuman menjadi dua peristiwa terpisah, kasus yang dibahas di release notes feature flag.

Apa tanggung jawab seorang release manager?

Release manager memiliki jalur yang ditempuh perubahan menuju produksi. Mereka memegang kalender rilis, memutuskan apakah perubahan sudah siap, menjalankan atau mengawasi deploy, mengambil keputusan rollback, memastikan pengguna diberi tahu, dan menjalankan tinjauan sesudahnya.

Sebelum rilis, mereka memastikan cakupan dan memeriksa bahwa setiap perubahan berisiko punya jalur rollback. Selama rilis, mereka menjalankan checklist deploy, mengamati menit-menit pertama metrik produksi, dan memutuskan rollback lebih awal. Sesudahnya mereka memastikan catatan sudah keluar dan mencatat apa yang harus diperbaiki di proses.

Di tim kecil, putar perannya tiap minggu dan tulis checklist agar tidak ada yang butuh pengetahuan lisan. Monorepo dengan banyak paket yang dirilis mandiri biasanya butuh satu pemilik rilis per paket, atau perannya berubah menjadi hambatan.

Apa saja KPI utama untuk manajemen rilis?

Lacak metrik pengiriman software DORA, dan tambahkan satu milik Anda sendiri: berapa lama sampai pengguna diberi tahu. Riset DORA mengidentifikasi lima metrik, dibagi menjadi throughput (change lead time, deployment frequency, failed deployment recovery time) dan instabilitas (change fail rate, deployment rework rate).

Panduan DORA mendefinisikannya dengan istilah sederhana (dora.dev, software delivery metrics):

KPI	Yang diukur	Yang perlu diperhatikan
Change lead time	Waktu dari commit di version control sampai ter-deploy di produksi	Angka yang naik biasanya berarti antrean di review atau persetujuan
Deployment frequency	Seberapa sering Anda deploy, atau jeda antar deployment	Frekuensi yang turun berarti batch membesar
Failed deployment recovery time	Waktu pulih dari deployment yang butuh intervensi segera	Masalah rollback dan alerting terlihat di sini
Change fail rate	Porsi deployment yang butuh rollback atau hotfix	Naik ketika batch terlalu besar atau tes tipis
Deployment rework rate	Porsi deployment yang tidak direncanakan dan disebabkan insiden produksi	Tanda bahwa perbaikan dirilis lebih cepat daripada pelajarannya
Waktu sampai pengguna diberi tahu	Menit dari deploy produksi sampai catatan yang menghadap pengguna terbit	Ukur sendiri, tidak ada kerangka yang menyediakannya

Materi lama mendaftar empat metrik kunci dan menyebut pemulihan sebagai "time to restore". Panduan saat ini memakai lima di atas.

Panduan yang sama memperingatkan agar metrik ini tidak diperlakukan sebagai target. Menetapkan tujuan seperti "semua deploy beberapa kali sehari pada akhir tahun" mengundang tim untuk mengakali angkanya, dan metrik dimaksudkan dibaca per aplikasi atau layanan, bukan dicampur di seluruh perusahaan. Saran praktisnya untuk memperbaiki semuanya adalah mengecilkan ukuran setiap perubahan, karena perubahan yang lebih kecil lebih mudah ditinjau, dilewatkan di pipeline, dan dipulihkan.

Bagaimana komunikasi rilis masuk ke proses manajemen rilis?

Ini langkah keenam, dan punya pemilik serta kriteria selesai seperti setiap langkah lain: catatan terbit di tempat pengguna membaca, dan tim internal diberi tahu. Tim paling sering melewatkannya, karena perkakas deployment melaporkan sukses begitu kode live.

Cara termurah menjaga langkah ini tepat jadwal adalah menulis entri saat perubahan di-merge, bukan saat rilis keluar. Pull request sudah memuat judul, penulis, issue yang tertaut, dan konteksnya. Draf yang dibangun darinya disunting, bukan ditulis dari ingatan seminggu kemudian. Itulah gagasan di balik otomatisasi changelog: turunkan draf saat merge, tahan untuk disetujui manusia, lalu terbitkan di mana-mana dari satu sumber. Changeloop bekerja seperti ini, membuat draf entri dari pull request yang di-merge dengan AI dan menahannya untuk persetujuan sebelum apa pun diterbitkan.

Dua variasi layak direncanakan sebelumnya. Support dan sales butuh catatan yang berbeda dari pelanggan, yang menjadi fungsi release notes internal. Rilis yang dipicu insiden tidak punya waktu untuk siklus penyusunan normal, jadi siapkan template singkat, seperti dijelaskan di release notes darurat. Template release notes memberi bentuk awal untuk versi yang menghadap pelanggan.

Bagaimana menjaga proses tetap ringan?

Otomatisasi setiap kriteria selesai yang bisa diperiksa mesin, dan sisakan manusia untuk penilaian. Pipeline hijau, penanda deploy di dasbor, dan draf entri changelog per pull request yang di-merge bisa diperiksa. Apakah rencana rollback meyakinkan, atau catatan masuk akal bagi pelanggan, membutuhkan manusia.

Untuk menguji proses, pilih satu rilis bulan lalu dan tanyakan apakah orang di luar tim bisa mengetahui, dari catatan tertulis saja, apa yang dirilis, siapa yang menyetujui, bagaimana diverifikasi, dan kapan pengguna diberi tahu. Celah apa pun adalah perbaikan Anda berikutnya.

FAQ

Apa perbedaan antara manajemen rilis dan manajemen perubahan? Manajemen rilis membuat sekumpulan perubahan di-build, dites, di-deploy, dan diumumkan. Manajemen perubahan, dalam pengertian ITIL, adalah proses persetujuan dan risiko di sekitar setiap perubahan. Tim yang sering merilis melebur persetujuan ke dalam code review dan pemeriksaan otomatis.

Seberapa sering kita sebaiknya merilis? Sesering yang diizinkan tes dan jalur rollback Anda, yang bagi banyak tim web berarti harian atau lebih. Panduan DORA adalah mengecilkan ukuran setiap perubahan, karena perubahan kecil lebih mudah ditinjau dan dipulihkan.

Apakah tim kecil butuh release manager? Mereka butuh tanggung jawabnya, tetapi belum tentu jabatannya. Putar peran itu di antara engineer, beri orang yang bertugas checklist tertulis, dan pastikan seseorang memiliki masing-masing dari tujuh langkah.

Apa yang harus ada di checklist rilis? Cakupan dikonfirmasi, pipeline hijau pada commit yang dirilis, jalur rollback disebut, persetujuan dicatat, smoke check setelah deploy, metrik dibandingkan dengan baseline, release notes terbit, support diberi tahu, dan tinjauan dijadwalkan. Jaga tetap satu halaman.

Contoh release notes untuk setiap jenis perubahan

Fri, 02 Oct 2026 00:00:00 GMT

Contoh release notes terbaik itu singkat, menyebut siapa yang terdampak, dan menjelaskan apa yang harus dilakukan berikutnya. Di bawah ini ada satu contoh untuk setiap jenis perubahan yang akan Anda rilis, beserta alasan mengapa contoh itu berhasil, sehingga Anda bisa menyalin bentuknya dan mengganti faktanya dengan milik Anda.

Semua contoh adalah rekaan, untuk aplikasi invoice fiktif bernama Tidepool.

Apa kesamaan contoh release notes yang baik?

Semuanya memberi tahu pengguna apa yang berubah dan apa yang harus dilakukan, jika ada, dengan bahasa pengguna. Setiap jenis perubahan punya tugas berbeda, jadi bentuknya bergeser di antara mereka.

Jenis perubahan	Entri harus menyebut	Letaknya
Fitur baru	Apa yang sekarang bisa dilakukan pembaca, dan siapa yang mendapatkannya	Paling atas catatan
Peningkatan	Apa yang jadi lebih cepat atau mudah, dengan angka jika ada	Setelah fitur
Perbaikan bug	Gejala yang dilihat pembaca, dan bahwa itu sudah diperbaiki	Setelah peningkatan
Breaking change	Siapa yang terdampak, tanggalnya, migrasinya	Pertama, selalu
Perbaikan keamanan	Apa yang terekspos, apakah dieksploitasi, apa yang harus dilakukan	Pertama
Deprecation	Apa yang akan hilang, tanggal berakhirnya, penggantinya	Dekat bagian atas
Catatan app store	Satu kalimat sederhana per perubahan, dalam batas karakter	Listing store
Catatan internal	Apa yang berubah dan apa yang disampaikan ke pelanggan	Kanal support dan sales

Seperti apa catatan fitur baru yang baik?

Catatan fitur yang baik dibuka dengan apa yang sekarang bisa dilakukan pembaca dan menyebut paket atau peran yang mendapatkannya. Ia melewatkan detail implementasi.

Kirim invoice dalam bahasa pelanggan. Sekarang Anda bisa memilih bahasa untuk setiap pelanggan, dan invoice, pengingat, serta halaman pembayaran mereka mengikutinya. Bahasa Prancis, Jerman, Spanyol, dan Portugis tersedia di semua paket. Atur di halaman pelanggan, di bawah Preferensi penagihan.

Judulnya adalah frasa yang akan diucapkan pembaca dengan lantang, dan isinya memberi cakupan dan lokasi. Pembaca yang hanya memindai baris tebal tetap tahu apa yang dirilis. Metode yang lebih luas ada di cara menulis release notes.

Seperti apa catatan peningkatan yang baik?

Catatan peningkatan menjelaskan perubahan yang akan dirasakan pembaca, dan menaruh angka terukur jika ada. Tanpa angka, sebutkan apa yang tidak perlu lagi dilakukan pembaca.

Daftar invoice dimuat sekitar tiga kali lebih cepat. Akun dengan lebih dari 5.000 invoice dulu menunggu sekitar sembilan detik untuk daftarnya. Sekarang terbuka dalam sekitar tiga detik. Tidak ada tindakan yang diperlukan.

"Peningkatan performa" tidak memberi tahu pembaca apa-apa, sedangkan sembilan detik lawan tiga adalah klaim yang bisa mereka cek Senin pagi. Penutup "Tidak ada tindakan yang diperlukan" menjawab pertanyaan yang dimiliki setiap pembaca.

Seperti apa catatan perbaikan bug yang baik?

Catatan perbaikan bug menjelaskan gejala yang dilihat pengguna, bukan penyebab di kode, dan menyebut apakah mereka perlu mengulang sesuatu. Perbaikan yang tidak disadari siapa pun bisa masuk ke daftar di bagian bawah.

Diperbaiki: email pengingat terkirim dua kali pada tanggal jatuh tempo. Sebagian pelanggan menerima dua pengingat identik jika invoice mereka jatuh tempo pada hari terakhir bulan. Ini sudah diperbaiki. Pengingat yang sudah terkirim tidak terpengaruh, dan tidak ada yang perlu mengirim ulang apa pun.

Judulnya diawali "Diperbaiki" sehingga pemindai bisa memilahnya sekilas, dan kondisi sebenarnya (hari terakhir bulan) langsung mengikuti.

Bagaimana menulis release notes untuk breaking change?

Catatan breaking change dibuka dengan tanggal dan kelompok yang terdampak, lalu memberi migrasi dalam entri yang sama. Letakkan paling pertama dalam release notes, karena ini satu-satunya entri yang tidak boleh terlewat pembaca.

Tanda tangan webhook menjadi wajib pada 1 Desember 2026. Mulai tanggal itu Tidepool berhenti mengirim payload webhook tanpa tanda tangan. Ini berdampak pada siapa pun yang menerima webhook tanpa memeriksa header Tidepool-Signature. Untuk bermigrasi, verifikasi header dengan secret di Pengaturan, Developer. Jika Anda sudah memverifikasi tanda tangan, tidak ada tindakan yang diperlukan.

Tanggalnya ada di judul, sehingga bertahan saat dipindai. Kelompok yang terdampak disebut menurut apa yang mereka lakukan, dan kalimat terakhir membebaskan orang yang sudah aman, yang mengurangi beban support. Panduan tentang breaking changes membahas cara memutuskan apakah suatu perubahan termasuk.

Seperti apa catatan perbaikan keamanan?

Catatan keamanan menyebut apa yang terekspos, apakah ada yang mengeksploitasinya, siapa yang terdampak, dan apa yang harus mereka lakukan. Tetap faktual dan tenang.

Keamanan: tautan reset password bisa dipakai ulang. Antara 3 dan 17 September 2026, tautan reset password tetap valid setelah dipakai sekali. Kami tidak menemukan tanda bahwa ini dieksploitasi. Sudah diperbaiki, dan semua tautan reset yang belum terpakai telah dibatalkan. Jika Anda meminta reset dalam rentang itu, minta tautan baru.

Rentang waktu yang tepat membuat pembaca bisa menilai paparan mereka sendiri, dan kalimat tentang eksploitasi menjawab pertanyaan pertama yang diajukan siapa pun. "Potensi masalah" terdengar seperti menutup-nutupi, jadi nyatakan apa yang Anda ketahui.

Bagaimana menulis pemberitahuan deprecation?

Pemberitahuan deprecation menyebut apa yang akan dihapus, memberi tanggal akhir yang tegas, dan menunjuk ke penggantinya.

Endpoint invoice v1 di-deprecate dan berakhir pada 1 Maret 2027. GET /v1/invoices tetap berfungsi hingga 1 Maret 2027, lalu mengembalikan 410 Gone. Gunakan GET /v2/invoices, yang mengembalikan field yang sama plus currency. Respons dari v1 kini menyertakan header Sunset dengan tanggal akhirnya. Panduan migrasi berdampingan ada di dokumentasi.

Nama endpoint ada di judul, karena orang yang terdampak mencarinya, dan penggantinya diletakkan di samping penghapusan. Header Sunset memberi tahu developer panggilan mana yang masih memakai versi lama. Pembahasan yang lebih panjang ada di mendeprecate API.

Seperti apa catatan rilis app store?

Catatan app store terdiri dari dua atau tiga kalimat sederhana, karena kebanyakan orang hanya membaca baris pertama. Mulai dengan perubahan yang akan disadari pengguna.

Pindai struk kertas dan Tidepool mengisi jumlah, tanggal, dan vendor. Mode gelap kini mengikuti pengaturan ponsel Anda. Kami juga memperbaiki crash saat membuka invoice dari notifikasi.

Perubahan yang paling berguna ada di depan, dan perbaikannya menyebut situasi yang menyebabkan crash. Tidak ada nomor versi dan tidak ada "perbaikan bug dan peningkatan". Release notes untuk aplikasi mobile membahas aturan khusus store.

Apa yang harus ada di catatan rilis internal?

Catatan internal adalah versi untuk support dan sales. Ia menambahkan apa yang dilewatkan catatan publik: apa yang harus dikatakan, dan apa yang jangan dijanjikan.

Invoice multibahasa dirilis hari ini (semua paket). Support: pelanggan mengatur bahasa di Preferensi penagihan, dan invoice yang sudah ada tetap memakai bahasa aslinya. Bahasa Italia belum tersedia. Sales: ini terbuka untuk setiap paket, jadi jangan memosisikannya sebagai upgrade.

Setiap audiens mendapat baris berlabelnya sendiri, dan catatan itu menarik batasnya ("Bahasa Italia belum tersedia") sebelum pelanggan bertanya. Artikel release notes internal membahas format dan kanalnya.

Seperti apa release note yang buruk, setelah ditulis ulang?

Release note yang buruk mendaftar apa yang dilakukan tim, bukan apa yang didapat pembaca. Perbaiki dengan memindahkan hasilnya ke depan dan menghapus istilah internal.

Sebelum:

v3.8.1 Merefaktor scheduler pengingat. Memperbaiki race condition di ReminderJob. Memperbarui bull ke 4.12. Peningkatan lain-lain.

Sesudah:

Email pengingat tidak lagi terkirim dua kali. Pelanggan dengan invoice yang jatuh tempo pada hari terakhir bulan bisa menerima dua pengingat. Itu sudah diperbaiki, dan pengingat yang sudah terkirim tidak perlu dikirim ulang. Tidak ada tindakan yang diperlukan.

Juga di 3.8.1: bull diperbarui ke 4.12.

Pembaruan dependensi turun menjadi baris catatan kaki, dan race condition berubah menjadi gejala yang akan dikenali pelanggan.

Bagaimana menjaga release notes tetap konsisten antar rilis?

Susun draf setiap entri saat perubahan di-merge, dan minta seseorang menyetujuinya sebelum rilis.

Changeloop bekerja dengan cara ini: ia membuat draf entri dari setiap pull request yang di-merge dengan AI dan menahannya sampai disetujui manusia. Langkah persetujuan itulah tempat editor menerapkan aturan di atas. Untuk menetapkan formatnya lebih dulu, mulailah dari template release notes, dan lihat contoh changelog untuk melihat seperti apa halaman yang sudah jadi.

FAQ

Apa itu release notes baru? Release notes baru adalah pesan yang diterbitkan bersama rilis terbaru sebuah produk, yang menjelaskan apa yang berubah dan apa yang perlu dilakukan pengguna. Isinya mencakup fitur, peningkatan, perbaikan, dan breaking change.

Apa perbedaan antara release note dan changelog? Changelog menyimpan semuanya, untuk siapa pun yang menginginkan riwayat penuh. Release note memilih dari sana: satu rilis, ditulis untuk pembaca yang sedang menentukan apakah rilis itu penting bagi mereka. Perbandingan lengkapnya ada di changelog vs release notes.

Apa arti release notes? Release notes memberi tahu pengguna apa yang berubah dalam sebuah rilis. Istilah ini mencakup apa pun yang menjelaskan apa yang dirilis, dari teks "What's New" di app store sampai halaman di situs perusahaan.

Seberapa panjang setiap entri release note? Dua sampai empat kalimat cukup untuk kebanyakan entri: hasilnya, siapa yang terdampak, dan apa yang harus dilakukan. Breaking change atau perbaikan keamanan bisa lebih panjang karena butuh tanggal atau migrasi.

Versioning API Stripe: cara kerjanya dan apa yang ditiru

Fri, 02 Oct 2026 00:00:00 GMT

Versioning API Stripe bekerja berdasarkan tanggal. Setiap akun dikunci ke versi API yang dinamai menurut tanggal rilis, dan satu request mana pun bisa menimpa kunci itu dengan header Stripe-Version. Saat artikel ini ditulis (Oktober 2026), versi terkini di dokumentasi Stripe adalah 2026-09-30.endive, dan skema yang sama bisa ditiru API yang jauh lebih kecil dalam satu akhir pekan.

Setiap fakta tentang Stripe di bawah berasal dari halaman Stripe sendiri, ditautkan di tempat dipakai.

Mekanisme	Yang dilakukan Stripe	Sumber
Nama versi	Tanggal, plus nama rilis sejak 2024 (`2026-09-30.endive`)	Versioning
Versi default	Dikunci di akun, diubah di Workbench	Versioning
Override per request	Header `Stripe-Version`, atau opsi SDK	Upgrades
Webhook	Dirender dalam versi yang diatur di endpoint	Upgrades
Kadens	Rilis bulanan tanpa breaking change, rilis mayor dua kali setahun	Versioning
Versi lama	Tetap berfungsi lewat modul perubahan versi internal	Engineering post

Bagaimana versioning API Stripe bekerja?

Stripe memberi setiap akun versi API default, dan setiap request yang tidak menyebut versi memakai versi itu. Pemanggil memilih kapan berpindah, dengan mengubah default atau mengatur versi pada request tertentu.

Engineering post Stripe menyatakan akun dikunci saat pertama kali membuat request API: akun itu "automatically pinned to the most recent version available", dan sejak itu setiap panggilan secara implisit diberi versi tersebut.

String versinya adalah tanggal. Sejak rilis 2024-09-30.acacia, string itu juga membawa nama, seperti 2026-09-30.endive. Tanggal mengurutkan versi, dan nama memberi tahu keluarga rilis mayor mana yang dimiliki sebuah versi.

Bagaimana memilih versi per request?

Kirim header Stripe-Version pada request, atau atur versi di SDK. Panduan upgrade Stripe menunjukkan bentuk header, dan panggilan yang sama berfungsi di lingkungan live maupun test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Panduan Stripe mencatat bahwa ketika Anda mengatur versi secara global atau per request di SDK, objek respons kembali dalam versi itu.

Stripe juga menyarankan agar tidak bersandar pada default akun. Dengan kata-katanya, tentukan versi untuk setiap request, dengan header atau SDK yang dikunci, agar kode Anda yang memutuskan versinya dan bukan pengaturan di dasbor.

SDK mengunci dengan cara berbeda per bahasa. Dokumentasi menyatakan versi terbaru dari pustaka berbahasa dinamis memakai versi API yang paling baru saat rilis SDK itu terbit, sedangkan yang bertipe kuat (Java, Go, dan .NET) terkunci padanya. Memasang versi pustaka pada dasarnya adalah memilih versi API.

Apa yang terjadi pada webhook ketika versi berubah?

Event webhook dirender dalam versi API yang melekat pada endpoint-nya, bukan versi yang dipakai kode server Anda. Dokumentasi Stripe menyatakan event memakai versi yang diatur saat endpoint dibuat, dan selain itu default akun. Mengubah versi SDK tidak mengubah apa yang diterima handler webhook Anda.

Jalur request dan jalur event Anda karena itu bisa berada pada dua versi berbeda. Untuk event destination, Anda mengatur snapshot_api_version hanya saat membuat destination, jadi versi yang berbeda berarti destination baru.

Jalur upgrade Stripe untuk ini adalah menjalankan secara paralel. Buat endpoint baru pada versi target, kirim event yang sama ke keduanya, ajari handler memproses satu dan mengabaikan yang lain, lalu beralih dan nonaktifkan endpoint lama. Karena setiap event tiba dua kali selama tumpang tindih, handler harus idempoten. Itu pola yang bagus untuk ditiru bagi API apa pun yang memancarkan event, dan changelog webhook adalah tempat Anda mengumumkan perubahan payload yang membuatnya diperlukan.

Apa itu rilis bulanan dan rilis mayor?

Sejak rilis 2024-09-30.acacia, Stripe merilis versi API baru setiap bulan tanpa breaking change, dan menerbitkan rilis mayor baru dua kali setahun yang dimulai dengan versi berisi breaking change. Halaman versioning-nya menyatakan Anda bisa upgrade ke rilis bulanan mana pun tanpa memperbarui kode, sedangkan rilis mayor bisa membutuhkan perubahan.

Rilis mayor punya nama. Halaman versioning memberi Basil sebagai contoh, dan pengumuman proses dari Stripe menyatakan nama-namanya berasal dari tumbuhan, dimulai dengan Acacia, dan rilis bulanan mempertahankan nama rilis mayor sebelumnya agar namanya menandakan aman untuk di-upgrade. Changelog Stripe mendaftar nama yang dipakai, dan saat artikel ini ditulis entri terbarunya adalah 2026-09-30.endive.

Jadi tanggal menjawab "seberapa baru", dan nama menjawab "apakah ini batas breaking". Pengumuman Stripe juga menyisakan ruang untuk pengecualian: Stripe berhak merilis breaking change di luar siklus jika sebuah integrasi akan sangat terdampak tanpanya. Pengumumannya ada di proses rilis API baru Stripe.

Apa versi terbaru API Stripe?

Saat artikel ini ditulis (Oktober 2026), halaman versioning Stripe menyatakan versi terkini adalah 2026-09-30.endive, dan changelog-nya mencantumkan versi yang sama sebagai yang terbaru. Stripe menerbitkan versi baru setiap bulan, jadi string apa pun yang tercetak di artikel cepat usang. Baca changelog langsung sebelum mengunci apa pun, dan kunci versi yang Anda uji.

Bagaimana Stripe menjaga versi lama tetap berfungsi?

Stripe menjaga versi lama tetap hidup dengan menulis setiap breaking change sebagai modul perubahan versi yang berdiri sendiri dan menerapkan modul-modul itu mundur dari bentuk data terbaru. Engineering post tentang versioning API menjelaskan mekanismenya.

Setiap modul menyatakan apa yang diubahnya, mendokumentasikan perubahan itu, dan menyertakan fungsi transformasi. Post itu memberi contoh sebuah field yang berubah dari string menjadi hash. Untuk membangun respons, sistem menentukan versi target, lalu berjalan mundur dalam waktu dan menerapkan setiap modul yang ditemuinya sampai mencapai versi itu.

Dua efek samping mengikuti dari desain itu, dan post tersebut menyebut keduanya. Karena modul menyatakan field dan resource yang disentuhnya, Stripe bisa menghasilkan changelog API-nya dari modul saat deployment. Dan karena versi akun diketahui, dokumentasi bisa menyesuaikan diri dengan versi itu dan memperingatkan perubahan yang tidak kompatibel ke belakang sejak versi tersebut.

Berapa biayanya, dan apa yang sebaiknya ditiru API yang lebih kecil?

Versioning membutuhkan perhatian engineering, dan Stripe mengatakannya. Engineering post mengakui adanya beban pemeliharaan dan menyatakan tujuan bahwa makin sedikit pemikiran yang dibutuhkan untuk perilaku lama saat menulis kode baru, makin baik. Post itu juga menjelaskan tinjauan API ringan sebelum rilis, agar perubahan versi tidak perlu dilakukan sama sekali.

API kecil tidak sanggup membiayai rantai modul untuk setiap versi lama, dan tidak membutuhkannya. Tiru bagian yang membawa nilai:

Versi bertanggal. Tanggal tidak membutuhkan penilaian tentang apa yang dihitung "mayor", dan pemanggil bisa membacanya. Artikel praktik terbaik versioning membandingkannya dengan skema URL dan header.
Default yang dikunci. Kunci akun atau key ke versi saat pemakaian pertama, agar API tidak bergeser di bawah integrasi yang sudah berjalan.
Override per request. Header yang memungkinkan pemanggil menguji versi baru pada satu panggilan, di produksi, sebelum berkomitmen.
Versi pada endpoint webhook. Payload event adalah tempat pemanggil paling sering terkejut.
Satu entri changelog per versi. Buat entri itu menyebut versi, tanggal, siapa yang terdampak, dan apa yang harus dilakukan. Apa yang dihitung breaking adalah ujian untuk apa yang pantas masuk versi baru, dan artikel changelog API membahas entrinya sendiri.

Lewati rantai modul sampai jumlah versi yang didukung memaksanya. Dua atau tiga versi aktif bisa ditangani dengan beberapa cabang dan tanggal sunset, yang dibahas menutup versi API.

Jika Anda menerbitkan changelog bertanggal, riwayat versi hanya sebaik entri-entrinya. Di Changeloop, draf entri dibuat dari setiap pull request yang di-merge dan ditahan agar manusia menyetujuinya sebelum diterbitkan ke halaman dan feed changelog. Di situlah entri per versi ditulis, dan satu gerbang manusia adalah tinjauan yang menyatakan apa yang harus dilakukan pemanggil.

FAQ

Apa versi terbaru API Stripe? Saat artikel ini ditulis (Oktober 2026), halaman versioning Stripe menyatakan versi terkini adalah 2026-09-30.endive. Stripe menerbitkan versi baru setiap bulan, jadi periksa changelog-nya sebelum mengunci, dan tulis versinya di kode Anda alih-alih bersandar pada default akun.

Bagaimana mengatur versi API Stripe pada sebuah request? Kirim header Stripe-Version, misalnya Stripe-Version: 2026-09-30.endive, atau atur versi di SDK sisi server Anda secara global atau per request. Tanpa keduanya, request memakai versi default akun Anda, yang Anda atur di Workbench.

Apakah webhook memakai versi API Stripe yang sama dengan request saya? Belum tentu. Event webhook memakai versi yang diatur saat endpoint dibuat, dan default akun jika tidak ada yang diatur. Meng-upgrade SDK tidak mengubah payload yang diterima handler webhook Anda, jadi upgrade endpoint secara terpisah dan uji secara paralel.

Apakah versioning bertanggal ala Stripe cocok untuk API kecil? Versi bertanggal, default yang dikunci, header per request, dan satu entri changelog per versi itu murah dan layak ditiru. Rantai modul perubahan versi internal tidak, sampai Anda mendukung banyak versi lama sekaligus. Mulailah dengan dua versi aktif dan tanggal sunset untuk yang lebih tua.

Siapa yang menulis changelog, dan siapa yang seharusnya

Tue, 22 Sep 2026 00:00:00 GMT

Tanyakan pada tim siapa yang menulis changelog dan jawaban jujurnya biasanya "siapa pun yang ingat", yang merupakan mode kegagalan yang sama yang coba diperbaiki mewajibkan entri changelog di CI di tingkat mekanis. Tapi memaksa entri ada tidak memutuskan siapa yang memenuhi syarat untuk menulis yang baik, dan tim yang melewati pertanyaan itu cenderung default ke siapa pun yang paling mudah diwajibkan, biasanya penulis PR, tanpa memeriksa apakah itu benar-benar orang yang bisa menulisnya dengan baik.

Mengapa penulis PR tidak otomatis menjadi penulis changelog terbaik?

Karena dia tahu implementasinya, belum tentu dampaknya, dan itu jenis pengetahuan yang berbeda. Di mana conventional commits berhenti membahas kesenjangan ini dari sisi pesan commit: fix(auth): reject expired refresh tokens benar dan tidak memberi tahu apa pun kepada pelanggan, dan orang yang menulis perbaikan itu sering kali orang yang paling tidak siap menerjemahkannya, karena dia sudah berpikir dalam istilah bug itu selama berjam-jam dan kehilangan pandangan luar tentang apa yang sebenarnya dialami pengguna. Ini alasan yang sama mengapa penulis teknis ada sebagai profesi: menerjemahkan implementasi menjadi dampak adalah keterampilan tersendiri, berbeda dari membangun sesuatu itu sendiri, dan itu butuh latihan tak peduli seberapa bagus developer itu dalam kodenya sendiri.

Apakah itu berarti produk atau dukungan seharusnya menulis setiap entri sebagai gantinya?

Tidak, karena mereka punya kesenjangan yang berlawanan: mereka tahu apa yang penting bagi pengguna tapi tidak selalu tahu apa yang sebenarnya dirilis, yang menghasilkan entri yang mudah dibaca tapi kadang salah dalam cakupan, klaim "sekarang mendukung X" untuk fitur yang masih di belakang flag, atau perbaikan yang digambarkan lengkap padahal hanya mencakup satu dari tiga kasus. Mode kegagalan entri yang ditulis developer adalah sulit-dibaca-tapi-akurat; mode kegagalan entri yang ditulis PM adalah mudah-dibaca-tapi-belum-terverifikasi. Tidak ada peran yang memiliki kedua paruh dari apa yang dibutuhkan entri yang baik.

Peran	Biasanya benar	Biasanya salah
Developer yang menulis kode	Cakupan pasti dari apa yang berubah	Membingkainya untuk seseorang yang tidak membangunnya
PM atau pemimpin dukungan	Mengapa itu penting bagi pengguna	Batasan pasti dari apa yang sebenarnya dirilis
Pemilik changelog khusus	Suara konsisten, memeriksa silang cakupan	Butuh keduanya di atas untuk diperiksa silang

Seperti apa sebenarnya model kepemilikan yang berhasil?

Draf dari siapa pun yang paling dekat dengan perubahan, ditinjau oleh siapa pun yang paling dekat dengan pengguna, dengan satu orang bernama bertanggung jawab atas kata-kata akhir alih-alih semua orang berasumsi orang lain akan menangkap masalah. Draf itu perlu ada dan akurat lebih daripada perlu bagus; kalimat kasar yang ditulis developer yang dengan benar mengatakan apa yang berubah adalah titik awal yang lebih baik daripada yang dipoles tapi belum diverifikasi, karena menulis ulang untuk kejelasan lebih mudah daripada menulis ulang untuk kebenaran. Langkah tinjauan adalah di mana PM atau pemimpin dukungan membaca draf dan mengajukan satu pertanyaan yang menangkap kesenjangan keterbacaan: apakah saya akan memahami ini jika saya tidak melihat kodenya.

Haruskah orang yang sama selalu menjadi yang bertanggung jawab, atau bergilir?

Bernama dan stabil mengalahkan bergilir, setidaknya untuk persetujuan akhir. Pemilik bergilir berarti setiap entri ditinjau oleh seseorang yang menurunkan ulang konvensi tim dari awal, yang persis bagaimana suaranya melenceng dari entri ke entri dan pembaca mulai menyadari changelog ditulis oleh komite. Satu orang, atau kelompok stabil yang sangat kecil, mengumpulkan penilaian dari waktu ke waktu, kapan mengatakan "ditingkatkan" versus menyebutkan angka spesifik, kapan perbaikan butuh entrinya sendiri versus dilipat ke dalam batch, dan penilaian itu lebih berharga daripada mendistribusikan pekerjaan secara merata.

Draf (developer, dari PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Ditinjau (pemilik changelog, diperiksa terhadap PR nyata):
"Diperbaiki: ekspor yang diurutkan berdasarkan tanggal
bisa mengembalikan hasil di luar urutan melewati halaman
pertama. Sekarang konsisten di semua halaman."

Apakah tim kecil butuh proses sebanyak ini untuk satu baris teks?

Bukan peran sebagai orang terpisah, tapi dua langkahnya masih penting bahkan sendirian. Tim satu orang adalah baik developer maupun peninjau, dan disiplin yang bertahan di skala itu adalah melakukan tinjauan sebagai langkah mental terpisah, bukan langsung melompat dari menulis perbaikan ke menerbitkan deskripsinya dalam satu tarikan napas. Jebakan di skala kecil adalah melewatkan langkah kedua sepenuhnya, bukan kurangnya orang kedua, karena tidak ada yang eksternal memaksanya, dan kesenjangan akurasi yang ada untuk ditangkap langkah itu tidak hilang hanya karena orang yang sama secara teoretis bisa menyadari titik butanya sendiri.

Apa yang terjadi ketika tidak ada yang bertanggung jawab atas entri akhir?

Changelog memburuk secara tidak merata alih-alih gagal secara terbuka, yang lebih buruk karena tidak ada yang menyadarinya sampai pembaca menunjukkannya. Beberapa entri tetap tajam karena siapa pun yang menulisnya peduli; yang lain menjadi samar, "berbagai peningkatan dan perbaikan bug", karena siapa pun yang menulisnya bergerak cepat dan tidak ada yang menangkapnya sebelum diterbitkan. Batasan format Keep a Changelog menangkap penyimpangan struktural, tanggal yang hilang, kategori yang salah, tapi tidak ada dalam template yang menangkap entri samar yang secara teknis diformat dengan baik, yang persis kesenjangan yang ada untuk ditutup pemilik bernama.

FAQ

Haruskah pemilik changelog berupa peran engineering atau produk? Keduanya bisa berhasil jika orang tersebut punya kelancaran teknis untuk memverifikasi cakupan sekaligus cukup jarak dari implementasi untuk menulis bagi pembaca luar; gelarnya kurang penting daripada apakah dia bisa melakukan kedua paruh, atau tahu kepada siapa harus bertanya untuk paruh yang tidak bisa dia lakukan.

Apakah jadwal bergilir gaya siaga pernah cocok untuk kepemilikan changelog? Untuk volume, kadang, jika tim terlalu kecil bagi satu orang untuk meninjau semuanya; untuk suara dan penilaian, tidak, karena itu persis yang dikikis rotasi. Rotasi yang berbagi beban menulis draf sambil mempertahankan satu peninjau stabil mendapat manfaatnya tanpa penyimpangannya.

Apa tanda tercepat ada yang salah dengan susunan kepemilikan saat ini? Entri yang akurat tapi sulit dibaca, atau mudah dibaca tapi salah dalam cakupan, dalam pola yang mengikuti siapa yang menulisnya. Jika kualitas berkorelasi dengan penulis alih-alih tetap konsisten, kepemilikan adalah kesenjangannya, bukan keterampilan menulis.

Apakah otomasi mengurangi seberapa penting kepemilikan? Itu mengurangi seberapa banyak penulisan yang dibutuhkan, bukan seberapa banyak penilaian yang dibutuhkan. Otomasi changelog membahas apa yang bisa dihasilkan pipeline dengan aman, pemformatan, penerbitan, cross-posting; kata-kata, pengelompokan, dan apa yang dianggap layak disebutkan tetap menjadi keputusan manusia tidak peduli seberapa banyak pipeline yang diotomasi.

Bagaimana jika penulis PR dan peninjau tidak setuju soal kata-katanya? Keputusan peninjau yang menang, karena pertanyaan yang mereka jawab, apakah pembaca luar akan memahami ini, adalah yang menjadi alasan peran itu ada. Itu tidak membuat pandangan developer tidak berharga: jika ketidaksepakatannya soal akurasi alih-alih pemilihan kata, peninjau yang mengalah, karena cakupan adalah bagian yang harus benar dari penulis. Memisahkan dua jenis ketidaksepakatan ini, kata-kata versus akurasi, menghentikan sebagian besar sebelum berubah jadi kebuntuan.

Release notes darurat: menulis di bawah tekanan waktu nyata

Tue, 22 Sep 2026 00:00:00 GMT

Kebanyakan release notes ditulis setelah kode selesai, ditinjau dengan santai, dan diterbitkan sesuai jadwal yang tidak ada hubungannya dengan seberapa mendesak seseorang perlu membacanya. Rilis darurat, patch keamanan, bug kehilangan data, perbaikan gangguan, membalikkan semua kondisi itu sekaligus: catatan harus ada sebelum kebanyakan orang biasanya akan mulai menulisnya, hampir tidak mendapat tinjauan, dan dibaca orang yang cemas alih-alih santai. Cara menulis release notes membahas proses normal; ini tentang apa yang berubah saat tidak ada waktu tersisa untuk mengikutinya.

Apa satu hal yang harus benar dilakukan catatan rilis darurat jika tidak ada hal lain?

Apakah pembaca perlu melakukan sesuatu, dinyatakan di kalimat pertama, tanpa framing apa pun sebelumnya. Pembaca yang menemukan catatan rilis yang dipicu insiden sering kali sudah khawatir, karena mendengar tentang masalah dari halaman status, thread dukungan, atau penggunanya sendiri, dan catatan yang dibuka dengan konteks sebelum item tindakan terbaca sebagai menahan informasi tepat dalam keadaan di mana menahan terbaca paling buruk. "Tidak perlu tindakan, ini menambal kerentanan yang tidak memerlukan data pengguna untuk dieksploitasi" dan "Perbarui segera: rilis ini memperbaiki bug yang bisa menampilkan data satu akun ke akun lain" keduanya satu kalimat, dan keduanya melakukan seluruh pekerjaan yang dibutuhkan pembaca yang panik sebelum membaca hal lain apa pun.

Apakah pengeditan biasa masih berlaku saat tidak ada waktu untuk melakukannya?

Naluri untuk memampatkan bertahan bahkan saat proses banyak draf yang biasanya menghasilkannya tidak bertahan. Penulisan ulang menjelaskan memangkas draf pertama yang bertele-tele menjadi kalimat esensialnya; di bawah tekanan waktu sering kali tidak ada draf pertama untuk dipangkas, yang berarti disiplinnya harus berjalan di kepala Anda saat menulis alih-alih sebagai langkah terpisah setelahnya. Cara tercepat untuk mendekatinya: tulis kalimat yang akan Anda katakan dengan lantang kepada seseorang yang bertanya "apa yang perlu saya ketahui", lalu berhenti, karena kalimat itu biasanya baik yang tercepat diproduksi maupun satu-satunya yang benar-benar akan diproses pembaca dalam keadaan itu.

Release note normal	Release note darurat
Ditulis setelah tinjauan kode, sebelum publikasi	Sering ditulis bersamaan dengan perbaikan, sebelum tinjauan lengkap
Dioptimalkan untuk kemudahan pindai di banyak entri	Dioptimalkan agar satu entri dibaca terisolasi, di bawah stres
Bisa menunda detail ke changelog yang ditautkan	Harus mendahulukan satu fakta yang paling penting
Framing dan konteks disambut baik	Framing sebelum item tindakan terbaca sebagai penundaan

Apakah pernah tidak apa-apa menerbitkan catatan sebelum benar-benar yakin apa penyebab masalahnya?

Ya, jika catatannya jujur tentang ketidakpastian itu alih-alih menyiratkan keyakinan yang tidak Anda miliki. "Kami telah menyebarkan perbaikan untuk tingkat error yang meningkat di checkout; kami masih mengonfirmasi akar penyebabnya dan akan memperbarui catatan ini" bisa dipertahankan dan membeli waktu dengan benar; catatan yang menyatakan penyebab spesifik yang sebenarnya belum Anda konfirmasi adalah jenis tebakan yang menjadi hal yang dikutip kembali orang kepada Anda nanti jika ternyata salah. Disiplin yang penting di sini bukan kecepatan diagnosis, tapi tidak pernah membiarkan keyakinan catatan melebihi keyakinan tim yang sebenarnya, karena klaim teknis yang salah dalam catatan darurat merusak kepercayaan lebih daripada ketidaktahuan yang diakui.

Terlalu yakin, belum diverifikasi:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."

Jujur di bawah tekanan waktu:
"Diperbaiki: beberapa pelanggan dikenakan biaya dua kali
untuk satu pesanan. Kami telah menghentikan kejadian baru
dan mengembalikan dana akun yang terdampak dalam 24 jam.
Menyelidiki akar penyebab."

Apakah catatan darurat harus menyebutkan penyebab masalahnya, atau hanya bahwa itu sudah diperbaiki?

Katakan apa yang diperbaiki dan apa yang harus dilakukan pembaca; simpan akar penyebab untuk tindak lanjut begitu benar-benar diketahui, bukan diperkirakan. Pembaca di tengah insiden ingin tepat dua fakta, apakah ini sudah teratasi dan apakah ini memengaruhi saya, dan penjelasan akar penyebab, bahkan yang akurat, bersaing dengan dua fakta itu untuk perhatian pada momen terburuk untuk kehilangannya. Postmortem, diterbitkan terpisah begitu investigasi selesai, adalah tempat akar penyebab seharusnya berada; mencampur kedua dokumen di bawah tekanan waktu menghasilkan catatan yang lebih lambat ditulis dan lebih lambat dibaca, kebalikan dari yang dibutuhkan keadaan darurat.

Apakah masalah pembaruan paksa dari aplikasi mobile juga berlaku di sini?

Prinsip yang sama, lebih dipampatkan lagi. Release notes untuk aplikasi mobile membahas pembaruan paksa, di mana catatan harus menyatakan alasan dan tenggat waktu sebelum apa pun karena pembaca sudah kesal karena tidak punya pilihan; release note darurat web biasanya opt-in bagi pembaca dalam artian mereka memilih apakah akan bertindak berdasarkan itu, tapi naluri "nyatakan batasan lebih dulu" yang sama berlaku, hanya karena alasan berbeda: bukan kekesalan, kemendesakan.

Bagaimana menghindari catatan darurat terbaca sebagai pengakuan kesalahan padahal seharusnya tidak?

Jelaskan perbaikannya dan efeknya, bukan kesalahannya, dan tahan dorongan untuk meminta maaf berlebihan, yang terbaca sebagai pengisi bagi pembaca yang menginginkan dua fakta di atas. "Kami menemukan dan memperbaiki bug yang memengaruhi beberapa ekspor" menyatakan apa yang terjadi tanpa menambahkan drama padanya; "Kami sangat menyesal atas masalah serius ini yang berdampak pada pelanggan kami yang berharga" menunda informasi yang berguna satu kalimat penuh untuk menyampaikan momen emosional yang tidak diminta pembaca. Catatan yang singkat dan faktual tidak dingin, itu menghormati keadaan pembaca yang sebenarnya, yang di bawah tekanan nyata adalah ketidaksabaran, bukan kebutuhan akan ketenangan.

FAQ

Haruskah release note darurat melalui proses tinjauan yang sama dengan yang normal? Yang lebih ringan, bukan tanpa sama sekali: satu peninjau cepat yang memeriksa bahwa catatan tidak melebih-lebihkan kepastian sepadan dengan beberapa menit yang dibutuhkannya, karena risiko klaim teknis yang tidak ditinjau menjadi salah lebih tinggi justru karena ditulis dengan cepat.

Apakah tidak apa-apa menerbitkan catatan darurat tanpa tautan ke detail lebih lanjut? Hanya sebentar. Catatan tanpa tautan berfungsi sebagai hal pertama yang diterbitkan; tambahkan satu ke halaman status atau tindak lanjut begitu salah satunya ada, karena pembaca yang menginginkan lebih dari satu kalimat yang Anda berikan butuh tempat untuk pergi, meskipun tempat itu mengatakan "detail lebih lanjut segera".

Haruskah catatan darurat pernah dilewati sepenuhnya, membiarkan perbaikan dirilis secara diam-diam? Hanya untuk masalah yang tidak bisa disadari atau terdampak oleh pembaca mana pun; jika ada kemungkinan pembaca mengalami masalahnya, catatan adalah yang memberi tahu mereka bahwa itu sudah berakhir, dan keheningan terbaca seolah masalahnya mungkin masih aktif.

Berapa lama catatan darurat harus tetap disematkan atau menonjol setelah insiden teratasi? Sampai jendela kecemasan langsung menutup, biasanya satu atau dua hari, lalu bisa melipat ke dalam changelog normal seperti entri lainnya; catatan yang tetap disematkan selama berminggu-minggu mulai terbaca sebagai kekhawatiran yang belum teratasi alih-alih yang sudah teratasi.

Protobuf breaking changes: apa yang bertahan di wire

Tue, 22 Sep 2026 00:00:00 GMT

API REST berubah saat bentuk JSON berubah, dan sebagian besar bentuk itu terlihat di respons yang bisa Anda baca di browser. API gRPC berubah saat berkas .proto berubah, dan format biner wire milik Protocol Buffers punya aturan sendiri tentang apa yang bisa ditoleransi client yang tidak ada hubungannya dengan apa yang dikatakan nama field. Dua penyuntingan yang terlihat sama kecilnya di diff, menomori ulang sebuah field versus menambahkannya, jatuh di sisi berlawanan dari garis yang breaking changes gambar secara umum: satu tidak terlihat bagi setiap client yang ada, yang lain merusak semuanya sekaligus. Membedakan protobuf breaking changes dari yang aman berarti membaca aturan format wire itu sendiri, bukan menebak dari bagaimana perubahan itu terbaca di diff .proto.

Mengapa penomoran field lebih penting daripada nama field dalam Protobuf?

Karena format wire mengkodekan field berdasarkan nomor, bukan nama. Kode yang dihasilkan dalam setiap bahasa membaca dan menulis nomor-nomor itu; nama field email di berkas .proto Anda adalah kemudahan bagi manusia yang tidak pernah menyentuh byte biner yang dikirim lewat jaringan. Mengganti nama field, email menjadi email_address, aman di wire biner selama nomornya tetap sama, yang mengejutkan insinyur yang terbiasa dengan REST, di mana key JSON yang diganti namanya adalah persis jenis perubahan yang merusak client. Pengecualiannya adalah kasus REST yang sama: format ProtoJSON dan text menserialisasi nama, jadi mengganti nama merusak transcoding JSON (grpc-gateway, misalnya), berkas text-format dan field mask. Menomori ulang field yang sama, mempertahankan nama tapi mengubah 1 menjadi 7, adalah kebalikannya persis: tidak terlihat dalam review kode yang hanya menampilkan nama, dan itu merusak setiap pesan yang dikirim atau diterima client sejak titik itu.

Perubahan	Aman di wire	Mengapa
Mengganti nama field, mempertahankan nomornya	Biner ya, JSON dan text tidak	Pengkodean biner menggunakan nomor; ProtoJSON dan format text menggunakan nama
Mengubah nomor sebuah field	Tidak	Setiap pesan yang ada sekarang dibaca sebagai field yang salah
Menambah field baru dengan nomor baru	Ya	Client lama mengabaikan field yang tidak mereka kenali
Menghapus field, menggunakan ulang nomor lamanya untuk hal lain	Tidak	Data lama diterjemahkan ke field baru yang salah
Mengubah tipe field secara tidak kompatibel (mis. `int32` ke `string`)	Tidak	Pengkodean wire berbeda per tipe

Apa yang membuat menghapus field berbeda dari melakukannya dalam respons JSON REST?

Nomornya menjadi radioaktif. Panduan resmi Protobuf merekomendasikan menandai nomor field yang dihapus sebagai reserved alih-alih membiarkannya digunakan ulang, karena penggunaan ulang adalah di mana kerusakan sebenarnya terjadi: client yang masih menjalankan kode yang dihasilkan bulan lalu mengirim pesan menggunakan nomor lama field itu untuk makna lama, dan server, yang sekarang mengharapkan nomor itu berarti sesuatu yang lain, salah menafsirkan data secara diam-diam alih-alih menolaknya secara langsung. REST tidak punya jebakan setara, karena key JSON yang dihapus hanya berhenti muncul; tidak ada cara bagi permintaan client lama untuk diam-diam ditafsirkan ulang sebagai sesuatu yang lain. Berkas .proto dengan reserved 4, 9, 12; di atas sebuah message adalah bekas luka permanen, dan itulah maksudnya: itu menghentikan nomor tersebut diberikan ke field baru oleh seseorang yang tidak tahu sejarahnya.

message Invoice {
  reserved 4; // dulu `legacy_customer_id`, dihapus 2026-06-01
  reserved "legacy_customer_id"; // namanya juga, untuk JSON/text
  string customer_id = 5;
  string status = 6;
}

Apakah menambah field pernah membutuhkan entri changelog sama sekali?

Biasanya bukan entri breaking change, tapi sering kali entri biasa, karena "aman di wire" dan "tidak terlihat bagi pembaca yang peduli" adalah dua klaim berbeda. Menambah field ke pesan respons tidak membebani apa pun secara struktural, client lama menerjemahkan pesan dan mengabaikan field baru secara otomatis. Tapi seseorang yang membangun integrasi baru terhadap layanan itu tidak punya cara mengetahui field itu ada kecuali seseorang memberi tahunya, karena tidak ada yang di build sukses atau tes yang lolos membuat field opsional baru terlihat. Changelog API membahas secara umum apa yang dihutangi entri aditif kepada pembaca; alasan khusus gRPC untuk tetap menulis satu adalah tidak ada padanan untuk menjelajahi respons REST di debugger untuk menyadari bahwa key baru muncul.

Bagaimana ini berbeda dari apa yang dihadapi pemanggil GraphQL?

Aturan untuk penambahan sama, tapi eksposurnya berbeda. Deprecation skema GraphQL membahas model di mana client hanya menerima field yang secara eksplisit dimintanya, yang membuat perubahan aditif pada dasarnya tanpa risiko dan penghapusan menjadi satu-satunya bahaya nyata. Client gRPC, sebaliknya, menerima apa pun yang dikirim server dan menerjemahkan semuanya terhadap salinan skema hasil kompilasi mereka sendiri; paparan client tidak dibatasi oleh apa yang dimintanya, hanya oleh apa yang bisa dibaca kode yang dihasilkannya. Perbedaan itu penting untuk menulis changelog: entri GraphQL bisa secara wajar mengasumsikan bahwa client terlindungi dari field yang tidak mereka minta, dan entri gRPC sama sekali tidak bisa mengasumsikan itu.

Apakah memversikan layanan gRPC bekerja sama seperti `/v1/`, `/v2/` REST?

Mekanismenya berbeda bahkan saat niatnya sama. Apa itu v1 dan v2 dalam API REST membahas versi sebagai jalur URL paralel yang melayani kontrak berbeda; layanan gRPC biasanya memversikan lewat nama paket di berkas .proto itu sendiri, payments.v1.InvoiceService menjadi payments.v2.InvoiceService, yang mengubah nama layanan yang sepenuhnya memenuhi syarat yang dipanggil client alih-alih segmen URL yang dimintanya. Kedua pendekatan menyelesaikan masalah yang sama, membiarkan kontrak lama tetap berfungsi sementara yang baru ada, tapi tim yang berasal dari latar belakang REST sering mencari nomor versi di tempat yang salah dan melewatkan bahwa deklarasi paket sedang melakukan pekerjaan itu.

Apa yang seharusnya benar-benar disebutkan entri changelog gRPC?

Pesannya, nomor field-nya, dan apakah itu aditif atau penghapusan yang membutuhkan migrasi, dalam urutan kepentingan itu bagi pembaca yang memutuskan apakah harus bertindak. "Menambahkan shipping_address (field 8) ke Order" memberi tahu integrator semua yang diperlukan untuk memperbarui kode yang dihasilkan dan mulai menggunakannya. "Mencadangkan field 4 pada Invoice, legacy_customer_id hilang" memberi tahunya untuk memeriksa apakah ada sesuatu di kode basisnya yang masih membaca field itu, sesuatu yang tidak dikomunikasikan catatan gaya REST "menghapus field dari respons" dengan urgensi yang sama, karena penghapusan REST hanya mengembalikan lebih sedikit data sementara penggunaan ulang field Protobuf secara aktif merusaknya.

FAQ

Bisakah tipe field pernah diubah tanpa merusak format wire? Hanya dalam grup kompatibel spesifik yang didokumentasikan Protobuf, seperti memperlebar int32 ke int64 dalam beberapa kasus. Perlakukan perubahan tipe apa pun sebagai breaking kecuali Anda sudah memeriksanya terhadap tabel kompatibilitas Protobuf sendiri; mengasumsikan kompatibilitas melalui analogi dengan sistem tipe suatu bahasa adalah bagaimana ini menjadi salah.

Apakah mendepresiasi field dalam Protobuf bekerja seperti direktif @deprecated GraphQL? Mirip: Protobuf mendukung opsi field [deprecated = true] yang bisa ditampilkan tooling. Keduanya tidak ditegakkan: server GraphQL tetap menjawab query untuk field yang di-deprecate, dan client protobuf tetap mengkodekannya. Keduanya bersifat penasihat dan membutuhkan dukungan changelog yang sama.

Apakah menomori ulang pernah aman jika Anda mengontrol setiap client? Dalam sistem yang sepenuhnya tertutup, pada prinsipnya, tapi itu menghilangkan seluruh properti keamanan yang menjadi alasan keberadaan nomor field, dan "kami mengontrol setiap client" adalah klaim yang berhenti benar begitu build di-cache, deploy tertunda, atau client ditambahkan yang tidak ada yang ingat. Cadangkan nomornya alih-alih menggunakannya ulang, bahkan secara internal.

Apakah layanan gRPC membutuhkan halaman changelog seperti API REST publik? Hanya jika tim eksternal mengonsumsinya tanpa membaca diff .proto secara langsung, tes "siapa yang ada di sisi lain" yang sama yang diterapkan changelog API internal secara umum. Layanan gRPC yang hanya dikonsumsi layanan lain dari tim yang sama sering bisa melewati changelog formal demi riwayat commit, karena siapa pun yang membacanya sudah membuka skemanya.

Format berkas changelog: JSON, YAML, atau cukup Markdown

Thu, 17 Sep 2026 00:00:00 GMT

Sebagian besar tim memulai changelog sebagai berkas Markdown karena itu jalur dengan resistansi paling kecil: bisa dibaca dalam diff pull request, bisa dibaca di GitHub tanpa merender apa pun, dan familiar bagi siapa pun yang pernah menulis README. Pilihan itu berjalan baik sampai sesuatu selain manusia perlu membaca berkas itu, halaman, widget, ringkasan email, dan saat itu format berhenti gratis. Otomasi changelog membahas kebutuhan struktural secara umum, tipe, tanggal, badan, dan tautan; ini membahas format berkas mana yang benar-benar memberikan struktur itu dan berapa biaya untuk mencapainya di masing-masing format.

Apa yang salah dengan changelog Markdown biasa?

Tidak ada, sampai sesuatu perlu mem-parsingnya kembali ke dalam field. Judul, tanggal, dan daftar berpoin di bawahnya remeh dibaca bagi manusia dan sungguh sulit di-parsing dengan andal, karena Markdown tidak punya skema: tanggal bisa ada di judul, tebal di baris pertama, atau sama sekali tidak ada di entri lama, dan setiap variasi itu adalah Markdown valid yang dibaca benar oleh manusia dan tidak oleh parser. Tim yang mengotomasi changelog Markdown biasanya berakhir menulis parser regex khusus yang rusak begitu format sebuah entri sedikit saja melenceng, yang sering terjadi, karena tidak ada yang memaksa konsistensi saat menulis.

Apa yang sebenarnya didapat dari format terstruktur?

Jaminan bahwa setiap entri punya bentuk yang sama, diperiksa saat entri ditulis alih-alih ditebak saat dibaca. Berkas JSON atau YAML dengan skema yang ditentukan, tipe, tanggal, versi, audiens, badan, tautan, gagal dengan berisik jika field wajib hilang, sama seperti respons API yang ketat; berkas Markdown hanya merender apa pun yang ada, benar atau tidak. Perbedaan itu tak terlihat sampai hari sebuah skrip butuh tanggal setiap entri untuk mengurutkan feed, dan separuh entri menyimpannya di tempat berbeda.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Apakah itu berarti berkas yang bisa dibaca manusia harus hilang?

Tidak, dan mencoba membuat berkas YAML atau JSON berperan ganda sebagai apa yang dibaca manusia dalam pull request biasanya kesalahan ke arah sebaliknya: meninjau diff JSON bersarang lebih buruk daripada meninjau kalimat prosa, dan peninjau yang harus mem-parsing struktur data secara mental untuk menangkap kesalahan kata-kata adalah peninjau yang akhirnya berhenti menangkap kesalahan kata-kata. Kedua format bisa berdampingan: data terstruktur adalah sumber kebenaran yang dibaca pipeline otomasi, dan rendering Markdown atau HTML yang dihasilkan adalah yang benar-benar ditinjau dan dibaca manusia, diproduksi dari berkas terstruktur alih-alih dirawat manual di sampingnya.

Format	Bisa dibaca manusia apa adanya	Bisa di-parsing mesin tanpa kode khusus	Mode kegagalan umum
Markdown	Ya	Tidak	Bentuk entri tidak konsisten merusak parser naif
JSON	Buruk	Ya	Bertele-tele; mudah salah edit manual jadi JSON tidak valid
YAML	Cukup	Ya	Sensitif spasi; indentasi salah adalah kesalahan parsing diam, bukan berisik

Format terstruktur mana yang sebenarnya lebih mudah diedit manual, JSON atau YAML?

YAML, bagi siapa pun yang menulis entri secara manual alih-alih lewat generator, karena ia menghilangkan penguncian kutip dan pencocokan kurung yang dituntut JSON untuk setiap string dan objek bersarang. Trade-off-nya adalah sensitivitas spasi YAML gagal secara diam dengan cara yang biasanya tidak dilakukan ketidakcocokan kurung JSON: parser JSON langsung menolak input yang cacat, sementara parser YAML bisa menerima berkas yang salah indentasi dan begitu saja mem-parsingnya ke struktur yang salah, yang merupakan kegagalan lebih buruk karena tidak ada yang memberi tahu Anda itu terjadi. Jika entri selalu hanya ditulis oleh skrip, trade-off ini sebagian besar hilang dan parsing JSON yang lebih ketat menjadi pilihan default yang lebih aman.

Apakah halaman changelog butuh format terstruktur sendiri, terpisah dari berkas yang memasoknya?

Bukan yang terpisah, yang sama dirender berbeda. Halaman changelog membahas cara membuat halaman itu sendiri bisa dibaca mesin lewat feed JSON dan markup schema.org; feed itu adalah output yang dihasilkan, bukan sumber kebenaran kedua yang harus disinkronkan dengan berkas yang mendasarinya. Merawat data terstruktur secara manual di dua tempat, berkas sumber dan feed halaman, adalah cara keduanya akhirnya melenceng, jadi keputusan format berkas yang diambil di sini seharusnya menjadi satu-satunya hal yang darinya semua yang hilir, halaman, widget, email, dihasilkan, tidak pernah disalin manual.

Apakah biaya migrasi mengubah changelog Markdown yang ada ke format terstruktur sepadan?

Biasanya hanya begitu otomasi menjadi tujuan sebenarnya, bukan sebelumnya. Proyek satu orang yang menerbitkan berkas Markdown di README GitHub tidak punya kebutuhan otomasi nyata, dan mengubahnya ke YAML tidak membeli apa pun selain seremoni. Konversi itu membayar dirinya sendiri saat lebih dari satu konsumen hilir, halaman, email ringkasan, feed publik, butuh membaca data yang sama, karena itu persis titik di mana ketidakkonsistenan parser Markdown mulai menghasilkan output yang terlihat salah alih-alih hanya menjengkelkan untuk dirawat.

FAQ

Bisakah changelog Markdown dibuat bisa di-parsing tanpa mengubah format sepenuhnya? Sebagian, dengan frontmatter: blok YAML kecil di atas setiap entri (tanggal, tipe, versi) di samping badan Markdown untuk prosa. Ini mendapatkan field terstruktur yang dibutuhkan parser tanpa memaksa seluruh entri ke JSON atau YAML, dan ini titik tengah yang masuk akal bagi tim yang belum siap untuk migrasi penuh.

Apakah format berkas penting untuk SEO atau untuk bagaimana halaman changelog peringkat? Tidak secara langsung. Mesin pencari membaca halaman yang dirender, bukan berkas sumber, jadi format berkas tidak terlihat bagi mereka; yang penting bagi halaman itu sendiri adalah apakah ia bisa dibaca mesin dengan haknya sendiri, yang merupakan urusan terpisah dari apa yang menghasilkannya.

Haruskah setiap entri changelog melalui berkas yang sama, atau bisakah tipe dipisah ke beberapa berkas? Satu berkas lebih sederhana sampai volume entri membuatnya sulit di-diff atau ditinjau; memisah berdasarkan tahun atau kategori adalah katup pelepas yang masuk akal begitu diff satu berkas menjadi terlalu besar untuk ditinjau dengan wajar, tapi itu menambah langkah penggabungan sebelum apa pun di hilir bisa membaca "semua entri" sebagai satu daftar.

Apakah ada format berkas changelog standar, seperti ada standar untuk RSS? Tidak ada yang diadopsi secara luas. Keep a Changelog mengusulkan konvensi Markdown, dan beberapa alat punya format sendiri; sebuah changeset adalah berkas Markdown dengan frontmatter YAML yang menyebut paket dan kenaikan versinya, yaitu pola frontmatter yang dijelaskan di atas. Tidak satu pun dari ini adalah format yang dibaca alat lain langsung dari awal seperti pembaca RSS memahami RSS secara universal.

Permintaan fitur duplikat: menggabung tanpa kehilangan suara

Thu, 17 Sep 2026 00:00:00 GMT

Tiga pelanggan meminta kapabilitas yang sama dalam tiga minggu berbeda, diungkapkan dengan tiga cara berbeda, dan proses triase yang dibangun untuk menangkap duplikat melakukan tugasnya: ia mengelompokkan mereka, menghitungnya sebagai satu permintaan dengan tiga suara, dan backlog tetap bersih. Itu bagian mudahnya. Label mana yang layak dipakai membahas mengelompokkan berdasarkan kapabilitas mendasar sebelum triase berdasarkan kata-kata sebagai perbaikan mekanis untuk duplikat; yang tidak dibahas adalah apa yang terjadi pada kata-kata itu sendiri begitu tiga permintaan menjadi satu baris, dan kerugian itu biasanya lebih besar daripada masalah penghitungan duplikat yang diselesaikannya.

Apa yang sebenarnya hilang saat duplikat digabung?

Kata-kata spesifik yang digunakan setiap pemohon, yang sering lebih informatif daripada hitungan suara tempat ia menyusut. Satu pelanggan mungkin meminta "cara mengekspor hasil yang difilter", yang lain "ekspor CSV yang menghormati filter tersimpan saya", dan yang ketiga "ekspor yang tidak menyertakan kolom tersembunyi". Ketiganya adalah permintaan mendasar yang sama, dikelompokkan dengan benar, tapi setiap kata-kata membawa penekanan sedikit berbeda tentang apa yang penting bagi orang itu, dan penggabungan yang hanya menyimpan kata-kata dari pengiriman pertama membuang sepenuhnya dua lainnya. Hitungan bertahan; tekstur yang akan membantu seseorang membangun versi fitur yang tepat, tidak.

Mengapa tekstur penting jika hitungan suara sudah mengatakan permintaan itu ada?

Karena permintaan dan desain adalah pertanyaan berbeda, dan hanya kata-kata spesifik yang menjawab yang kedua. Sepuluh suara pada "ekspor" memberi tahu tim bahwa fitur itu layak dibangun; tidak mengatakan apa pun tentang apakah "ekspor" berarti CSV, PDF, email terjadwal, atau endpoint API, dan penggabungan yang membuang sembilan dari sepuluh pengiriman asli demi kata-kata yang pertama bisa diam-diam mempersempit spesifikasi ke apa pun yang kebetulan diminta pemohon pertama itu, meskipun sembilan lainnya menginginkan sesuatu yang sedikit berbeda. Apa yang sebenarnya harus dicatat permintaan fitur membahas celah yang sama persis dari sisi asupan; menggabung duplikat adalah tempat itu muncul kembali setelah asupan, tepat pada titik di mana tim paling membutuhkan rentang dari apa yang sebenarnya diminta.

Seperti apa proses penggabungan yang menyimpan kata-kata alih-alih membuangnya?

Menambahkan alih-alih mengganti. Item kanonik menyimpan satu judul untuk tampilan backlog, tapi kata-kata asli dari setiap pengiriman yang digabung tetap melekat padanya, entah sebagai daftar kutipan atau sebagai tiket sumber yang ditautkan, sehingga siapa pun yang meninjau item itu kemudian bisa melihat rentang nyata dari apa yang diminta orang alih-alih ringkasan satu anggota tim. Ini hampir tidak berbiaya untuk dibangun, satu field pada tiket alih-alih sistem baru, dan ini perbedaan antara penggabungan yang memampatkan informasi dan yang hanya memampatkan tampilannya.

Fitur: Ekspor CSV yang difilter
Suara: 12
Permintaan yang digabung:
  - "cara mengekspor hasil yang difilter" (acct_4421)
  - "ekspor CSV yang menghormati filter tersimpan saya" (acct_8832)
  - "ekspor yang tidak menyertakan kolom tersembunyi" (acct_1097)
  ...

Apakah setiap duplikat layak digabung, atau ada kecocokan yang salah?

Beberapa adalah kecocokan yang salah, dan memperlakukan "terdengar mirip" sebagai "adalah permintaan yang sama" adalah mode kegagalannya sendiri. "Biarkan saya mengekspor data saya" dan "biarkan saya mengekspor hanya tampilan yang difilter" bisa dikelompokkan oleh kecocokan kata kunci pada "ekspor" padahal sebenarnya menggambarkan dua cakupan berbeda dari kapabilitas umum yang sama; menggabungnya entah menggembungkan hitungan suara untuk hal yang salah atau, lebih buruk, merilis versi yang lebih sempit karena kebetulan tiba lebih dulu. Tinjauan manusia atas pengelompokan, bahkan yang cepat, menangkap ini sebelum menumpuk; kecocokan kemiripan otomatis saja akan menggabung berlebihan berdasarkan kosakata dan menggabung kurang berdasarkan niat.

Kapan sebenarnya pengecekan duplikat harus berjalan, saat asupan atau belakangan?

Keduanya, untuk alasan berbeda. Pengecekan saat asupan menangkap kasus yang jelas, permintaan baru yang menyatakan ulang sesuatu yang sudah terbuka, sebelum itu sempat menjadi baris item terlacak tersendiri; pencarian kemiripan terhadap permintaan terbuka saat pengiriman menangani kebanyakan kasus ini tanpa melibatkan manusia. Tinjauan kedua belakangan, pada kadensi yang lebih lambat, menangkap kasus yang terlewat asupan: dua permintaan yang memakai bahasa cukup berbeda untuk lolos dari kecocokan kata kunci atau embedding saat itu, tapi ternyata, begitu tim sudah melihat selusin variasi, menggambarkan kapabilitas mendasar yang sama. Melewatkan tinjauan kedua membiarkan hampir-duplikat tersebar di bawah judul terpisah tanpa batas waktu, masing-masing dengan hitungan suara kecilnya sendiri yang tidak pernah bertambah ke angka yang seharusnya membuatnya dibangun.

Haruskah pemohon tahu pengirimannya digabung ke item yang sudah ada?

Ya, dan ini disiplin yang sama dengan menutup lingkaran umpan balik pelanggan diterapkan satu langkah lebih awal dari biasanya: pemohon yang mengirim sesuatu dan tidak pernah mendengar kabar lagi menyimpulkan permintaannya tidak ke mana-mana, meskipun digabung dengan benar ke item dengan sebelas suara lain yang akhirnya dirilis. Konfirmasi singkat, "kami telah menggabungkan ini dengan permintaan yang sudah ada yang juga dibuat orang lain", berbiaya satu pesan dan mencegah pelanggan mengirim ulang permintaan yang sama setiap beberapa bulan karena tidak punya visibilitas apakah itu pernah benar-benar dilacak.

Apakah menggabung mengubah siapa yang mendapat kredit saat fitur dirilis?

Seharusnya menyertakan semua orang, bukan hanya yang mengirim pertama. Menutup lingkaran umpan balik membahas memberi tahu pemohon saat permintaan mereka dirilis; untuk item yang digabung itu berarti setiap akun yang melekat pada penggabungan, bukan hanya yang kata-katanya menjadi judul kanonik, karena dari sudut pandang setiap pemohon dia meminta ini dan itu dirilis, tanpa peduli kata-kata siapa yang kebetulan disimpan proses triase. Dengan Changeloop itu berarti pull request menyebut setiap issue yang tertaut (Fixes #142, fixes #187); issue yang tidak disebutnya tidak mendapat komentar.

FAQ

Berapa banyak kata-kata yang layak disimpan per permintaan yang digabung, kutipan atau tautan tiket lengkap? Kutipan singkat biasanya cukup untuk kasus umum, karena tujuannya membiarkan peninjau melihat rentang kata-kata sekilas; simpan juga tautan tiket lengkap ketika yang asli punya konteks tambahan signifikan, seperti tangkapan layar atau deskripsi alur kerja rinci yang akan diratakan kutipan satu baris.

Apakah menyimpan kata-kata setiap duplikat membuat backlog lebih sulit dipindai? Tidak, jika dilipat secara default. Judul kanonik adalah yang dilihat peninjau yang memindai cepat; kata-kata yang digabung berjarak satu klik atau satu perluasan, hadir bagi yang melakukan riset lebih dalam tapi tanpa memenuhi tampilan bagi yang hanya menghitung suara.

Bagaimana jika dua permintaan terlihat identik tapi ternyata menginginkan hal berbeda setelah dibangun? Pisahkan lagi begitu itu menjadi jelas, dan perlakukan penggabungan asli sebagai keputusan masuk akal yang dibuat dengan informasi yang tersedia saat itu, bukan sebagai kesalahan yang harus dihindari diulangi. Sistem pengelompokan yang tidak pernah membatalkan penggabungan apa pun akhirnya akan punya beberapa penggabungan salah yang tertanam permanen.

Apakah ada ambang suara di mana permintaan yang digabung harus mendapat tinjauan manusia atas kata-kata mendasarnya? Bukan angka tetap, tapi permintaan apa pun yang mendekati keputusan pembangunan layak mendapatkan itu tanpa peduli hitungan suara, karena itu titik di mana perbedaan antara "ekspor" dan "ekspor sebagai CSV dengan filter tersimpan" berhenti menjadi nuansa dan mulai menjadi spesifikasi.

Deprecation GraphQL tanpa nomor versi

Thu, 17 Sep 2026 00:00:00 GMT

API REST bisa merilis /v2/ berdampingan dengan /v1/ dan membiarkan pemanggil berpindah sesuai kecepatan mereka sendiri. GraphQL punya satu skema di satu endpoint, dan setiap client, aplikasi mobile dengan build tahun lalu dan dashboard internal yang dirilis pagi ini, mengkueri graph yang sama. Tidak ada URL untuk di-fork. Men-deprecate sebuah field berarti menandainya sebagai deprecated di tempat, dalam skema yang sudah menjadi tumpuan semua orang, yang membuat disiplinnya berbeda dari REST meskipun masalah dasarnya, memberi tahu pemanggil bahwa sesuatu akan hilang, sama dengan yang dibahas deprecation API secara umum.

Bagaimana GraphQL menandai field sebagai deprecated, jika tidak ada versi untuk dinaikkan?

Dengan directive @deprecated, diterapkan langsung pada field:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Field tetap bisa dikueri. Ia tidak hilang, tidak mengembalikan 404, tidak mengubah perilaku; ia hanya membawa catatan yang bisa dibaca mesin yang akan ditampilkan sebagian besar alat GraphQL, GraphiQL, Apollo Studio, linter skema, kepada siapa pun yang menelusuri skema atau menulis kueri terhadapnya. Ini seluruh mekanismenya. Tidak ada endpoint deprecation terpisah, tidak ada header, tidak ada dokumen pendamping yang diwajibkan spec, yang menjadi baik daya tariknya maupun jebakannya: directive mudah ditambahkan dan mudah diabaikan, karena tidak ada yang memaksa client untuk melihatnya.

Apakah ada yang benar-benar melihat alasan deprecation?

Hanya yang menggunakan skema secara langsung, lewat introspection atau editor yang sadar skema, dan itu audiens yang lebih kecil daripada pembaca biasa changelog API. Aplikasi mobile yang dibangun terhadap sebuah kueri enam bulan lalu sudah memanggang kueri itu ke dalam binary-nya; ia akan terus meminta price dan terus mendapat jawaban, deprecated atau tidak, sampai seseorang membangun ulang aplikasi dengan field baru dan merilis pembaruan. Directive memberi tahu developer yang menulis kode baru untuk tidak menggunakan field lama. Ia tidak melakukan apa pun untuk client yang sudah dirilis dan berjalan.

Mekanisme	Siapa yang terjangkau
Directive `@deprecated`	Developer yang menelusuri skema atau menulis kueri baru
Kegagalan CI dari linter skema	Tim pemilik basis kode client, jika mereka menjalankan satu
Entri changelog	Siapa pun yang membacanya, termasuk tim client tanpa linter
Tidak ada (field tetap berfungsi)	Client yang sudah dibangun yang menggunakan field lama

Apakah field yang deprecated tetap harus mendapat entri changelog?

Ya, dan itu melakukan lebih banyak pekerjaan daripada directive saja, karena changelog menjangkau orang yang tidak bisa dijangkau directive: tim mitra yang mengonsumsi graph tanpa menelusuri skemanya, client yang dibangun terhadap salinan skema yang di-cache berbulan-bulan lalu, siapa pun yang hanya akan menyadarinya dengan membaca prosa. Changelog API membahas secara umum apa yang menjadi kewajiban entri kepada pemanggil; entri GraphQL berutang satu hal yang jarang harus dijelaskan REST, karena pemanggil REST menyimpulkannya dari nomor versi: apakah field lama masih berfungsi hari ini, masih berfungsi dengan peringatan, atau benar-benar berhenti mengembalikan data. Directive saja tidak menjawab semua itu untuk pembaca yang tidak pernah membuka skema.

Kapan sebenarnya aman menghapus field dari skema?

Hanya setelah log kueri menunjukkan tidak ada yang memintanya lagi, yang merupakan pertanyaan penggunaan, bukan pertanyaan kalender. Sebuah field bisa membawa @deprecated selama setahun dan tetap menjadi penopang bagi satu client yang tidak pernah dibangun ulang; menghapusnya pada jadwal tetap, seperti yang sering dilakukan Sunset REST, merusak client itu tanpa peringatan yang bisa ditindaklanjuti, karena GraphQL tidak memberinya apa pun untuk ditindaklanjuti selain directive yang tidak pernah dibacanya. Catat penggunaan tingkat field sebelum berkomitmen pada tanggal penghapusan, dan perlakukan hitungan kueri bukan nol sebagai jeda, bukan hitung mundur.

Apakah menambah field membawa risiko yang sama seperti di API REST?

Lebih rendah, untuk field baru, karena client GraphQL hanya menerima field yang diminta secara eksplisit. Menambah priceV2 di samping price tidak bisa merusak kueri yang ada dengan cara menambah field ke respons JSON REST bisa merusak deserializer yang ketat, karena tidak ada yang memaksa client meminta field baru. Menambah nilai ke enum yang sudah ada adalah pengecualian yang layak disebutkan dalam napas yang sama: client yang men-switch pada setiap nilai enum secara ekshaustif, sesuatu yang didorong bahasa dengan tipe kuat, rusak begitu nilai baru muncul, terlepas apakah ada kueri yang memintanya atau tidak. Keamanan ini hanya berlaku untuk field dan anggota union yang dipilih sendiri oleh client; tidak berlaku untuk himpunan tertutup yang dienumerasi tangan oleh kode client.

Apa yang dibutuhkan entri changelog GraphQL yang tidak dibutuhkan entri REST?

Bentuk kueri, bukan hanya nama field, karena "field price deprecated" kehilangan bagian yang benar-benar dibutuhkan pemanggil: tipe mana dan kueri mana yang menyentuhnya. Entri yang berguna menyebutkan tipe, field, field pengganti, dan, jika bisa dibuat, kueri aktual di produksi yang masih meminta bentuk lama. Bagian terakhir itu, mengaitkan pemberitahuan deprecation dengan penggunaan nyata, adalah yang didapat gratis oleh pemanggil REST dari log server pada sebuah URL dan tidak didapat pemanggil GraphQL, karena setiap kueri mengenai endpoint yang sama apa pun yang dimintanya.

Adakah selain field yang bisa membawa directive `@deprecated`?

Nilai enum, menggunakan directive yang sama di definisi nilai itu sendiri, bukan di field:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

Spec mendefinisikan @deprecated untuk tepat dua lokasi, definisi field atau nilai enum, dan tidak ada yang lain per rilis stabilnya; deprecation tingkat argumen dan input-field hanya ada dalam bahasa draft yang lebih baru, bukan dalam apa yang diimplementasikan kebanyakan server hari ini. Nilai enum yang ditandai dengan cara ini tetap menjadi nilai sah yang masih bisa dikembalikan atau diterima server, janji tidak-breaking yang sama seperti yang dibuat field yang deprecated, yang membuatnya aman dirilis sebelum benar-benar menghapus nilai itu.

FAQ

Apakah GraphQL mendukung sesuatu seperti header Sunset untuk seluruh endpoint? Tidak, karena biasanya hanya ada satu endpoint. Waktu deprecation hidup di tingkat field, dalam teks alasan directive @deprecated dan dalam changelog atau panduan migrasi apa pun yang diterbitkan tim di sampingnya, bukan dalam header respons yang bisa dibaca client secara programatik.

Bisakah field yang deprecated dihapus lalu ditambahkan kembali nanti dengan tipe berbeda? Hanya sebagai nama field baru. Memperkenalkan kembali nama field yang sama dengan tipe yang berubah adalah persis breaking change yang ingin dihindari siklus deprecation; beri pengganti namanya sendiri, seperti yang dilakukan priceV2, dan biarkan yang lama benar-benar punah sebelum namanya bebas untuk digunakan lagi.

Haruskah teks alasan @deprecated menautkan ke entri changelog? Ya, ketika tooling skema mendukungnya. Field alasan menerima string biasa, dan URL di dalam string itu adalah jalan terpendek dari developer yang menatap output introspection ke penjelasan lebih lengkap yang bisa diberikan entri changelog.

Apakah perubahan skema GraphQL pernah backward compatible dengan cara yang tidak dimiliki REST? Perubahan field aditif, ya, karena alasan di atas: client hanya mendapat apa yang mereka minta. Nilai enum baru adalah pengecualiannya, karena client yang mengenumerasi himpunan tertutup bisa rusak pada nilai yang tidak diperkirakannya. Penghapusan dan perubahan tipe persis sama breaking-nya dengan padanan RESTnya.

Cara menulis panduan migrasi API

Mon, 07 Sep 2026 00:00:00 GMT

Panduan migrasi API adalah dokumen yang mengubah perubahan tak kompatibel menjadi checklist, bukan gangguan: apa yang berubah, apa yang harus dilakukan, dan sampai kapan. Entri changelog bisa menyebutkan perubahan tak kompatibel dalam dua kalimat; panduan migrasi adalah yang benar-benar dibuka pemanggil ketika dua kalimat itu berkata "ini merusak Anda" dan mereka perlu tahu persis apa yang harus diedit. Mempublikasikan entri tanpa panduan adalah cara pemanggil mengetahui perubahan tak kompatibel dari tiket dukungan alih-alih dari dokumen yang ditulis untuk mencegahnya.

Apa itu panduan migrasi API?

Dokumen langkah demi langkah yang membawa pemanggil dari bentuk lama API ke yang baru, ditulis untuk seseorang dengan kode yang harus diubah, bukan seseorang yang masih memutuskan apakah akan mengadopsi API. Perbedaan itu penting: panduan migrasi mengasumsikan integrasi yang sudah ada dan lalu lintas produksi yang sudah ada, jadi harus mencakup rollback, migrasi parsial, dan cara mengetahui apakah migrasi berhasil, semua yang tidak dibutuhkan panduan integrasi pertama.

Dokumen	Mengasumsikan	Menjawab
Panduan migrasi	Integrasi yang sudah ada	Bagaimana saya pindah dari bentuk lama ke baru?
Entri changelog	Tidak ada, hanya pembaca yang mengecek	Apa yang berubah, dan kapan?
Referensi API	Tidak ada, atau integrasi pertama	Apa fungsi endpoint ini?
Pemberitahuan deprecation	Integrasi yang memakai yang lama	Kapan ini berhenti berfungsi?

Panduan migrasi biasanya berada di antara dua yang terakhir: pemberitahuan deprecation memulai jam, dan panduan migrasi adalah yang diikuti pemanggil sebelum jam itu habis.

Kapan sebuah perubahan butuh panduan migrasi, bukan hanya entri changelog?

Ketika ada lebih dari satu langkah antara perilaku lama dan baru, atau ketika perubahan menyentuh cukup banyak titik pemanggilan sehingga pemanggil lebih diuntungkan oleh contoh yang dikerjakan daripada deskripsi. Apa itu perubahan tak kompatibel, dan cara merilisnya membahas uji apakah perubahan itu tak kompatibel; jika jawabannya ya, pertanyaan kedua adalah apakah perbaikannya adalah edit satu baris atau migrasi sungguhan. Kolom yang diganti nama bisa ditangani pemanggil hanya dengan entri changelog. Perubahan pada autentikasi, paginasi, atau penanganan error hampir selalu pantas mendapat panduan, karena kode pengganti yang benar tidak jelas dari deskripsi satu kalimat.

Apa yang harus dimuat panduan migrasi?

Lima hal, dan melewatkan salah satunya adalah cara panduan berubah menjadi halaman yang dibaca pemanggil sekali lalu kembali ke coba-coba. Kode lama, ditampilkan seperti yang sebenarnya muncul dalam proyek. Kode baru, ditampilkan dengan cara yang sama, bukan sebagai deskripsi abstrak perbedaannya. Apa yang rusak jika tak ada yang diubah, dikatakan dengan jelas, karena "tidak ada" adalah jawaban yang valid dan umum yang tetap perlu didengar pemanggil secara eksplisit. Cara memverifikasi migrasi berhasil, seperti kolom respons atau kode status untuk dicek. Dan jadwal: kapan perilaku lama berhenti berfungsi, dan apakah kedua bentuk tersedia sementara itu.

## Migrasi kolom mata uang dari float ke integer (v3.0.0)

Sebelum:
  { "amount": 19.99 }

Sesudah:
  { "amount": 1999 }  // unit mata uang terkecil (sen)

Yang berubah: `amount` sekarang adalah bilangan bulat dalam unit
terkecil mata uang akun. Kode yang membaca `amount` sebagai float
akan membaca nilai 100x terlalu besar mulai 1 Oktober 2026.

Verifikasi: setelah migrasi, tagihan $19.99 harus terbaca sebagai
`amount: 1999`, bukan `amount: 19.99`.

Jadwal: v2 tetap mengembalikan float sampai 15 Januari 2027. v3
mengembalikan bilangan bulat sejak peluncuran. Kedua versi aktif
sekarang.

Setiap dari lima hal itu menjawab pertanyaan yang jika tidak, harus ditebak atau ditanyakan pemanggil ke dukungan, dan itulah biaya sesungguhnya yang dihemat panduan migrasi.

Siapa yang harus menulisnya, dan kapan?

Siapa pun yang merancang perubahan, pada saat yang sama ketika dirilis, bukan tim dukungan yang merekonstruksinya dari tiket belakangan. Yang membuat keputusan tahu bagian mana dari perilaku lama yang seharusnya tidak diandalkan siapa pun dan mana yang merupakan kontrak tak sengaja; panduan yang ditulis belakangan oleh seseorang tanpa konteks itu cenderung terlalu menjelaskan yang jelas atau melewatkan satu kasus tepi yang benar-benar merusak orang. Panduan dan entri changelog yang mengumumkan perubahan tak kompatibel sebaiknya dirilis bersamaan, dengan entri menautkan ke panduan alih-alih mengulanginya.

Bagaimana ini berkaitan dengan versioning dan changelog API?

Secara langsung: panduan migrasi adalah versi rinci dari yang hanya diringkas dalam satu kalimat oleh entri MAJOR di semantic versioning dan changelog Anda. Entri changelog mengatakan perubahan tak kompatibel dan garis besar apa yang berubah; panduan migrasi adalah tautan yang seharusnya dibawa entri itu. Changelog API: apa yang dipublikasikan dan siapa yang membacanya mencantumkan panduan migrasi sebagai salah satu dari lima dokumen yang dipelihara API, masing-masing menjawab pertanyaan berbeda; ini adalah yang menjawab "bagaimana saya benar-benar pindah dari A ke B", dan pantas mendapat halamannya sendiri justru karena jawaban itu biasanya terlalu panjang untuk entri changelog.

Berapa lama panduan migrasi harus tetap dipublikasikan?

Setidaknya selama perilaku lama masih bisa dijangkau, dan idealnya juga setelahnya. Pemanggil yang bermigrasi terlambat delapan belas bulan, setelah mengabaikan tiga pemberitahuan deprecation, masih membutuhkan panduan, dan menghapusnya pada hari perilaku lama dimatikan hanya menjamin pemanggil yang paling membutuhkannya tidak menemukannya. Simpan di URL yang stabil dan perbarui bagian jadwal alih-alih menarik halaman. Panduan peningkatan milik Stripe sendiri adalah contoh publik dari pola ini: satu halaman yang tetap terkini dari rilis ke rilis, bukan dokumen baru per versi yang basi begitu versi berikutnya rilis. Panduan Anda sendiri layak mendapat tempat yang sama mudah ditemukannya, di samping dokumentasi yang sudah dibaca pemanggil, alih-alih terkubur di arsip blog.

FAQ

Apakah setiap perubahan tak kompatibel butuh panduan migrasi? Tidak. Perubahan yang bisa ditangani pemanggil hanya dengan entri changelog, seperti satu kolom yang diganti nama dengan pengganti yang jelas, tidak butuh panduan terpisah. Perubahan yang menyentuh beberapa titik pemanggilan atau butuh contoh yang dikerjakan, ya.

Haruskah panduan migrasi berada bersama dokumentasi API atau di changelog? Bersama dokumentasi, ditautkan dari entri changelog. Entri adalah yang dilihat pelanggan lebih dulu; panduan adalah yang dibutuhkan begitu mereka memutuskan untuk bertindak, dan tempatnya di sebelah materi referensi yang sudah dipakai pemanggil.

Apa bedanya panduan migrasi dengan pemberitahuan deprecation? Pemberitahuan deprecation menyatakan sesuatu akan hilang dan sampai kapan. Panduan migrasi adalah instruksi apa yang harus dilakukan soal itu. Pemberitahuan deprecation tanpa panduan migrasi yang ditautkan memberi pemanggil tenggat tanpa memberitahu cara memenuhinya.

Haruskah perilaku lama dan baru sama-sama didokumentasikan selama jendela migrasi? Ya, di halaman yang sama jika memungkinkan, sehingga pemanggil melihat persis apa yang berubah alih-alih menyusunnya dari dua dokumen terpisah yang ditulis pada waktu berbeda.

Check changelog untuk GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Setiap tim yang menjaga changelog secara manual pernah mengalami percakapan yang sama setelah insiden yang sama: sebuah rilis keluar tanpa entri, seseorang bertanya kenapa, dan jawaban jujurnya adalah orang yang seharusnya menulisnya sedang bergerak cepat dan langkah changelog itu hanya hidup dalam ingatan. Otomasi changelog membahas apa yang bisa diotomatisasi pipeline dengan aman dan apa yang masih butuh manusia; check changelog di CI adalah separuh lain dari masalah ini, karena mengotomatisasi penulisan tidak membantu jika tidak ada yang wajib memicunya sejak awal. GitHub Actions adalah tempat kebanyakan tim sudah menjalankan check pull request mereka, jadi di situlah check ini hidup juga.

Mengapa "kami minta orang menambahkan entri" gagal dengan pola yang bisa diprediksi?

Karena itu bersaing untuk mendapat perhatian dengan segala hal lain di pull request, dan itu satu-satunya bagian tanpa konsekuensi langsung jika dilewatkan. Test gagal dengan keras dan memblokir merge. Entri changelog yang hilang tidak memblokir apa pun, jadi ia kalah begitu seseorang terburu-buru, yang dalam praktiknya adalah kebanyakan waktu. Kebijakan yang ditegakkan oleh ingatan merosot persis pada kecepatan yang diharapkan: baik-baik saja untuk beberapa minggu pertama setelah semua orang setuju, lalu diam-diam ditinggalkan begitu orang yang peduli pergi berlibur atau pindah tim.

Apa yang sebenarnya diverifikasi check CI untuk entri changelog?

Bukan kualitas tulisannya, hanya bahwa entri itu ada dan berbentuk benar, yang merupakan cakupan tepat untuk check changelog yang berjalan di CI, bukan di kepala seseorang. Bentuk umum: check itu melihat diff PR dan mensyaratkan entah berkas baru di direktori changeset (pola yang digunakan Changesets dan alat serupa) atau baris yang diubah di berkas changelog, dan menggagalkan build jika tidak ada satu pun. Peninjauan tentang apa yang sebenarnya dikatakan entri itu tetap terjadi di tempat yang selalu terjadi, di code review, karena penilaian itu bukan urusan skrip.

Apa yang diverifikasi check CI	Apa yang tidak diverifikasi
Ada changeset atau baris changelog di diff	Apakah kalimatnya jelas
Entri merujuk paket yang benar, dalam monorepo	Apakah perubahan itu benar-benar layak dapat entri
Berkas valid secara sintaksis (front matter, bentuk JSON)	Apakah entri jujur tentang dampaknya

Apakah setiap PR butuh itu, atau ada perubahan yang dikecualikan?

Beberapa dikecualikan, dan daftar pengecualian itulah tempat sistem seperti ini benar-benar dibangun atau ditinggalkan. Kenaikan dependency tanpa efek terlihat, perubahan hanya test, refactor internal tanpa perubahan perilaku: tak satu pun dari ini seharusnya memaksa kontributor mengarang entri changelog untuk sesuatu yang tidak dipedulikan siapa pun yang membaca changelog. Pola yang berhasil adalah label atau flag yang bisa diterapkan kontributor (no-changelog-needed) dan memenuhi check CI tanpa berkas, ditinjau oleh siapa pun yang menyetujui PR, sehingga pengecualian itu sendiri melewati pengawasan yang sama seperti entri.

Apa yang terjadi pada pengecualian sah, seperti hotfix mendesak?

Gate itu berada pada merge, bukan pada deploy: hotfix di bawah tekanan waktu nyata bisa merge dengan entri placeholder atau tiket lanjutan, asalkan check CI terpenuhi oleh niat alih-alih hanya paragraf yang selesai; beberapa tim menerima stub satu baris yang dihaluskan maintainer sebelum potongan rilis berikutnya. Yang seharusnya tidak pernah diizinkan gate adalah melewati langkah itu diam-diam, karena stub yang terlupakan adalah kegagalan lebih kecil daripada entri yang tidak pernah ada, dan stub setidaknya meninggalkan jejak yang bisa ditemukan seseorang nanti.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # diff membutuhkan branch dasar
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Bagaimana Anda tahu check itu sendiri sudah benar sebelum mulai memblokir PR sungguhan?

Buka dulu pull request percobaan terhadap branch sekali pakai: satu dengan changeset, satu tanpa, dan satu lagi membawa label pengecualian, dan pastikan ketiganya mendapat hasil yang Anda harapkan sebelum check itu berlaku bagi pekerjaan orang lain. Check changelog yang fail open, meloloskan setiap PR karena sebuah kondisi ditulis terbalik, lebih buruk daripada tidak punya check sama sekali, karena itu terlihat seperti cakupan yang sebenarnya tidak ada. workflow_dispatch pada berkas yang sama, dijalankan manual terhadap beberapa PR yang baru-baru ini di-merge, menangkap kebanyakan kesalahan semacam ini tanpa perlu pull request sungguhan sama sekali.

Apakah ide yang sama berlaku di luar GitHub Actions?

Bentuknya tetap sama, hanya sintaksnya yang berubah. GitLab CI mengekspresikan aturan yang sama sebagai blok rules job yang memeriksa $CI_MERGE_REQUEST_LABELS, bukan if ala GitHub Actions, dan persetujuan merge request yang diwajibkan bisa menggantikan langkah peninjauan pengecualian. Check yang dibahas artikel ini memakai GitHub Actions karena itu platform yang sudah dipakai kebanyakan pembacanya, tapi kebutuhan yang mendasarinya, gate yang diperiksa mesin alih-alih konvensi yang sekadar diminta, sama saja di mana pun CI berjalan sebelum merge.

Apakah ini bekerja sama di monorepo?

Butuh satu bagian lagi: paket mana entri itu untuk. Changelog monorepo membahas mengapa satu berkas untuk seluruh repo berhenti bekerja begitu paket dirilis secara independen; check CI mewarisi persyaratan yang sama; changeset yang tidak menyebutkan paket bukan bukti berguna bahwa changelog yang tepat akan diperbarui, hanya bahwa suatu berkas berubah di suatu tempat dalam diff. Alat yang dibangun untuk ini (Changesets adalah yang umum di ekosistem JavaScript) meminta kontributor memilih paket yang terpengaruh dan kenaikan semver pada saat yang sama changeset dibuat, sehingga check CI mendapat kedua bagian itu gratis alih-alih menyimpulkannya belakangan.

FAQ

Haruskah check CI memblokir merge, atau hanya memperingatkan? Memblokir. Peringatan secara fungsional identik dengan meminta dengan sopan, yang justru sudah gagal. Label pengecualian ada tepatnya agar kasus hanya-peringatan yang sah tetap punya jalur sah melalui gate ketat yang sama.

Siapa yang meninjau apakah label pengecualian diterapkan dengan benar? Siapa pun yang menyetujui pull request, sebagai bagian dari peninjauan yang sudah dilakukannya. Label seharusnya tidak pernah diterapkan sendiri tanpa peninjauan, atau ia menjadi jalan pintas diam-diam yang sama yang seharusnya ditutup gate.

Apakah mewajibkan ini di CI menggantikan kebutuhan pipeline otomasi changelog? Tidak, ia memberi makan pipeline itu. Otomasi changelog membahas mengubah entri terstruktur menjadi halaman, feed, dan email; check CI adalah yang menjamin entri terstruktur itu ada untuk diotomatisasi sejak awal.

Apa versi terkecil dari ini yang layak dibangun lebih dulu? Satu check yang gagal jika tidak ada berkas berubah di bawah direktori changelog yang ditentukan, dengan satu label pengecualian. Perutean per paket dan penyimpulan semver untuk monorepo bisa datang belakangan; kebiasaan intinya, entri ada atau seseorang secara eksplisit bilang itu tidak diperlukan, adalah yang layak dimiliki sejak hari pertama.

Cara menolak permintaan fitur tanpa kehilangan pelanggan

Mon, 07 Sep 2026 00:00:00 GMT

Menutup lingkaran biasanya berarti memberi tahu seseorang bahwa permintaan mereka sudah dirilis. Separuh yang sulit, yang tidak dimiliki proses oleh kebanyakan sistem pelacakan sama sekali, adalah bilang tidak. Kebanyakan permintaan fitur tidak pernah dirilis, yang berarti sebagian besar penutupan lingkaran yang sebenarnya dihutangi produk kepada penggunanya adalah penolakan, bukan pengumuman, dan penolakan yang ditangani buruk lebih mahal biayanya untuk niat baik daripada yang akan dikeluarkan keheningan. Ditangani dengan baik, biayanya bisa hampir tidak ada, karena yang paling diinginkan yang meminta, kebanyakan waktu, adalah tahu bahwa mereka didengar, bukan fiturnya sendiri.

Mengapa menolak dengan baik sama pentingnya dengan merilis dengan baik?

Karena keheningan terbaca sebagai penolakan tanpa penjelasan, dan tidak yang dijelaskan terbaca sebagai perhatian. Yang tidak mendengar apa-apa berasumsi permintaannya diabaikan atau hilang, dan kedua kesimpulan itu mengajarinya berhenti repot-repot bertanya, yang merupakan hasil yang sama yang didapat produk dari penolakan sungguhan, hanya dicapai lebih lambat dan dengan lebih banyak kekesalan di sepanjang jalan. Balasan yang bilang tidak, dengan jelas dan dengan alasan, menutup lingkaran sama lengkapnya dengan fitur yang dirilis, dan melakukannya lebih cepat.

Balasan	Yang dipelajari yang meminta	Biaya untuk hubungan
Keheningan	Tak ada yang membaca, atau tak ada yang peduli	Tinggi, dan bertambah di setiap permintaan mendatang
Balasan otomatis tanpa alasan	Ada di antrean entah di mana, tanpa batas waktu	Sedang; membeli waktu tapi bukan kepercayaan
Penolakan dengan alasan	Sudah dibaca, dipertimbangkan, dan dijawab	Rendah, jika alasannya jujur
Penolakan dengan alternatif	Kebutuhan sebenarnya benar-benar didengar	Terendah; sering membangun kepercayaan

Apa yang membuat penolakan mendarat dengan buruk?

Hampir selalu tiga hal, dikombinasikan. Keumuman: "terima kasih atas masukan Anda" yang siap saji yang tidak merujuk pada apa yang sebenarnya diminta terbaca seolah tidak dibaca sama sekali, meski sebenarnya dibaca. Penundaan: penolakan yang datang enam bulan setelah permintaan, saat yang meminta sudah lupa pernah bertanya, terasa lebih buruk dari tidak yang cepat, karena menyiratkan permintaan itu dibiarkan tak tersentuh alih-alih dipertimbangkan dan ditolak. Dan alasan yang tidak kuat: "tidak ada di roadmap kami" tidak menjawab apa pun, sementara "ini akan memerlukan merancang ulang cara kerja izin, yang tidak kami rencanakan untuk disentuh tahun ini" memberi yang meminta sesuatu yang benar-benar bisa mereka evaluasi dan, jika cukup penting, dieskalasi atau dihindari.

Apa yang seharusnya benar-benar dikatakan penolakan yang baik?

Empat hal, dalam urutan ini: pengakuan yang menyebutkan permintaan spesifik, bukan parafrase umum; alasan sebenarnya, dinyatakan dengan jujur bahkan ketika alasan jujurnya adalah "ini tidak cocok dengan arah produk" alih-alih alasan yang lebih halus; apakah pintunya tertutup atau hanya belum terbuka sekarang, karena itu butuh nada yang sangat berbeda; dan, ketika ada, alternatif yang menjawab kebutuhan mendasar meski bukan fitur yang diminta secara harfiah.

Hai Jamie,

Terima kasih atas permintaan menambahkan impor CSV massal untuk
undangan tim. Kami sudah meninjaunya, dan kami tidak akan
membangunnya: alur undangan kami dibangun di sekitar peninjauan
individual setiap anggota baru demi keamanan, dan impor massal akan
bertentangan dengan itu by design, bukan karena kelalaian.

Jika masalah sebenarnya adalah mengundang tim besar dengan cepat, API
mendukung undangan individual berbasis skrip, yang memberi Anda
hampir semua kecepatan tanpa melewati peninjauan: [tautan]. Beri tahu
saya jika Anda ingin bantuan menyiapkannya.

Perhatikan yang dilakukan ini yang tidak bisa dilakukan template: menyebut fitur sebenarnya, memberi alasan yang terkait dengan keputusan desain sungguhan alih-alih kebijakan samar, dan menawarkan jalan yang menyelesaikan masalah mendasar alih-alih hanya menutup tiket.

Apa bedanya ini dengan menutup lingkaran pada fitur yang dirilis?

Mekanismenya mirip, nadanya tidak. Menutup lingkaran umpan balik dengan pelanggan membahas kasus yang dirilis, di mana pesannya adalah kabar baik dan risiko utamanya adalah lupa mengirimnya. Penolakan adalah kabar buruk, atau setidaknya kabar yang tidak diinginkan, dan butuh lebih banyak perhatian pada alasan yang diberikan dan lebih sedikit otomatisasi dalam penyampaian: notifikasi fitur yang dirilis bisa berupa komentar siap saji yang dipicu perubahan status, tapi penolakan yang terbaca siap saji justru adalah mode kegagalan yang ingin dihindari seluruh pendekatan ini. Keduanya tetap berbagi satu syarat: permintaan asli harus tetap terhubung dengan yang mengajukannya, disiplin pelacakan yang sama yang dibahas pelacakan permintaan fitur, kalau tidak tak ada cara mengirim salah satu pesan itu secara individual.

Haruskah penolakan bersifat publik, seperti status di roadmap publik?

Biasanya bukan alasan spesifiknya, meski statusnya bisa. Roadmap publik membahas label status yang bisa dicek yang meminta tanpa bertanya lagi, dan status "ditolak" atau "tidak direncanakan" bisa jadi bagian dari sistem itu. Tapi alasan rinci, terutama saat menyentuh prioritas internal atau konteks yang kurang menyenangkan, biasanya lebih bernilai di balasan individual daripada di halaman status publik, di mana formulasi yang sama harus berfungsi untuk setiap pembaca alih-alih untuk satu orang yang benar-benar bertanya.

Apakah setiap permintaan yang ditolak pantas mendapat balasan individual?

Setiap permintaan dari orang yang disebutkan namanya dan bisa dihubungi, ya, setidaknya yang singkat. Permintaan bervolume tinggi, duplikat, atau anonim adalah pengecualian: mengelompokkan permintaan serupa dan membalas sekali per kelompok, atau memperbarui label status bersama, masuk akal ketika balasan individual sungguh tidak bisa diskalakan. Batas yang harus dijaga adalah "kami tidak bisa membalas semua orang secara individual" seharusnya menjadi batasan operasional sungguhan, dicek terhadap volume sebenarnya, bukan alasan default untuk melewatkan balasan yang hanya butuh dua menit.

FAQ

Lebih baik menolak cepat dengan alasan lemah, atau meluangkan waktu untuk yang baik? Cepat, dengan alasan jujur, mengalahkan keduanya jika terpisah. Balasan cepat dengan alasan sungguhan, meski singkat, mengungguli balasan lambat dengan yang dipoles; penundaannya sendiri adalah bagian dari yang merusak kepercayaan.

Haruskah penolakan pernah menjanjikan meninjau kembali permintaan nanti? Hanya jika itu sungguh mungkin dan ada mekanisme untuk benar-benar meninjaunya kembali, seperti label yang memunculkannya lagi di siklus perencanaan. "Akan kami pertimbangkan" yang samar tanpa mekanisme itu secara fungsional sama dengan keheningan, hanya dirumuskan lebih ramah.

Bagaimana jika alasan jujurnya adalah sesuatu yang tidak bisa dibagikan perusahaan, seperti kekhawatiran kompetitif? Katakan itu langsung alih-alih mengarang alasan yang lebih halus. "Kami tidak bisa membagikan alasan spesifiknya di sini, tapi ini bukan sesuatu yang kami rencanakan untuk dibangun" lebih jujur, dan lebih dihormati, daripada penjelasan karangan yang runtuh di pertanyaan lanjutan.

Apakah menolak permintaan berarti harus dihapus dari pelacakan? Tidak. Simpan, berlabel ditolak dengan alasannya, sehingga jadi bagian dari pola yang dijadikan acuan pengelompokan permintaan serupa berikutnya, dan sehingga konteks yang berubah nanti (integrasi baru, prioritas tim baru) bisa memunculkannya lagi alih-alih memulai evaluasi dari nol.

Release notes feature flag: apa yang disampaikan, dan kapan

Mon, 07 Sep 2026 00:00:00 GMT

Menutup lingkaran pada permintaan fitur mengasumsikan ada momen bersih saat sesuatu itu dirilis. Feature flag menghilangkan momen itu, dan itulah yang membuat waktu release notes feature flag sulit ditentukan. Kode di-merge, flag ada, dan selama berhari-hari atau berminggu-minggu setelahnya fitur itu sekaligus live di produksi dan tidak terlihat bagi hampir semua orang yang mungkin ingin menggunakannya, sering termasuk orang yang awalnya memintanya. Memberi tahu terlalu cepat membuatnya menemui fitur yang belum ada. Memberi tahu terlalu lambat membuat lingkaran yang seharusnya membangun kepercayaan malah terbaca sebagai terlupakan.

Kenapa flag merusak urutan biasa "rilis, beri tahu"?

Karena itu memecah satu peristiwa jadi setidaknya dua: kode yang menjadi live, dan flag yang dinyalakan untuk akun tertentu. Setiap proses menutup lingkaran umpan balik mengasumsikan keduanya terjadi bersamaan, yang benar untuk kebanyakan rilis dan salah untuk apa pun di balik flag yang dipakai untuk rollout bertahap, penargetan, atau sebagai tombol darurat. Menutup lingkaran umpan balik pelanggan menjelaskan memberi tahu peminta persis pada saat entri changelog disetujui dan dipublikasikan; langkah itu ditulis untuk kasus di mana mempublikasikan entri dan fitur menjadi bisa dipakai adalah momen yang sama, dan flag justru kasus di mana keduanya tidak sama.

Momen	Apa yang benar	Sudah harus diberi tahu peminta
Kode di-merge, flag mati di mana-mana	Fitur ada, tidak ada yang bisa memakainya	Tidak
Flag menyala untuk akun peminta	Fitur ada, orang itu spesifik bisa memakainya	Ya
Flag menyala untuk persentase rollout yang mengecualikannya	Fitur ada, orang itu masih belum bisa memakainya	Tidak
Flag sepenuhnya dihapus, fitur begitu saja menyala	Fitur ada untuk semua orang	Ya, jika belum diberi tahu

Apa aturan sebenarnya untuk kapan memberi tahu seseorang?

Beri tahu saat flag menyala untuk akun mereka, bukan saat kode di-merge dan bukan saat flag dibuat. Satu aturan ini mencakup setiap baris tabel di atas, karena mengaitkan notifikasi dengan satu-satunya fakta yang benar-benar penting bagi peminta: apakah mereka, saat ini juga, bisa pergi memakai sesuatu itu. Notifikasi yang dikaitkan dengan merge atau pembuatan flag sebenarnya adalah laporan kemajuan rekayasa, dan orang yang meminta fitur tidak mau laporan kemajuan, mereka mau tahu kapan harus memeriksa.

Apakah itu berarti peminta butuh akses awal atau khusus?

Belum tentu, dan memaksakannya menciptakan masalah sendiri. Jika flag digulirkan bertahap karena alasan beban atau stabilitas, memindahkan satu akun ke depan antrean hanya untuk menutup lingkaran lebih cepat merusak alasan mengapa rollout itu dibuat bertahap sejak awal. Pilihan yang jujur adalah: menunggu akun peminta mencapai rollout secara alami dan memberi tahu mereka saat itu, atau, jika urgensinya membenarkan, dengan sengaja menyalakan flag lebih awal untuk mereka, sebagai keputusan nyata dari siapa pun yang memiliki rollout, bukan sebagai efek samping dari keinginan mengirim notifikasi.

Bagaimana jika flag itu tombol darurat, bukan mekanisme rollout?

Maka asumsi amannya terbalik. Flag yang dibuat agar bisa cepat mematikan fitur, alih-alih membertahapkan rilisnya, biasanya berarti fitur itu dimaksudkan sepenuhnya live begitu dibuat, dan flag ada demi keamanan alih-alih urutan. Dalam kasus itu, memberi tahu peminta saat waktu deploy sudah benar, sama seperti rilis mana pun tanpa flag; keberadaan flag adalah detail operasional yang seharusnya tidak mengubah kapan lingkaran ditutup. Perbedaan yang penting adalah untuk apa flag itu, bukan apakah ada satu.

Apakah flag mengubah apa yang seharusnya dikatakan release notes feature flag?

Itu mengubah kapan entri dipublikasikan, bukan apa isinya. Entri yang dipublikasikan persis pada saat flag menyala untuk 100% akun terbaca persis seperti entri changelog normal, dan memang seharusnya begitu; pembaca yang menemukannya nanti tidak punya alasan untuk tahu bahwa flag pernah terlibat. Yang seharusnya tidak dilakukan adalah dipublikasikan saat flag hanya menyala untuk persentase rollout kecil, karena entri changelog publik mengirim semua orang yang membacanya, termasuk akun tanpa flag, untuk mencari fitur yang tidak akan mereka temukan, yang merupakan versi lebih buruk dari masalah yang sama, dalam skala seluruh produk alih-alih skala satu peminta. Aturan waktu itulah seluruh perbedaan antara release notes feature flag dan entri biasa: isinya sama, hanya tanggal publikasinya yang bergeser. Cara menulis release notes membahas disiplin "tidak perlu tindakan" yang juga berlaku di sini: pembaca harus tahu apakah ini berlaku bagi mereka, bukan hanya bahwa itu ada di suatu tempat.

Haruskah email pembaruan produk memperlakukan fitur berflag secara berbeda?

Ya, terutama dengan menunda alih-alih menulis ulang. Template email pembaruan produk membahas notifikasi bertarget versus digest luas; fitur berflag adalah kasus di mana waktu notifikasi bertarget harus diperiksa terhadap status flag penerima itu sendiri sebelum dikirim, sesuatu yang tidak bisa dilakukan digest luas dengan mudah sama sekali, yang jadi alasan tambahan kenapa digest adalah kanal yang salah untuk apa pun yang masih di tengah rollout.

FAQ

Haruskah memberi tahu peminta bahwa fiturnya "segera hadir" begitu flag ada tapi belum menyala untuk mereka? Hanya jika ada tanggal nyata dan dekat, dan bahkan begitu, secukupnya saja. "Segera hadir" tanpa tanggal terbaca, setelah cukup waktu berlalu, sama saja dengan diam, dan menciptakan janji kedua yang juga harus dilacak dan ditepati.

Siapa yang memutuskan kapan flag sudah cukup jauh untuk menutup lingkaran? Siapa pun yang memiliki rollout, bukan siapa pun yang memiliki notifikasi. Pemilik rollout tahu apakah "100% akun" sudah dekat atau masih berminggu-minggu lagi; mengaitkan langkah penutupan lingkaran dengan status mereka, alih-alih tanggal kalender tetap, menjaga notifikasi tetap jujur.

Apakah fitur di balik flag permanen (tidak pernah sepenuhnya dihapus) pernah mendapat entri changelog publik? Ya, begitu mencapai apa pun yang dimaksud "ketersediaan umum" bagi produk itu, meski flag itu sendiri tetap ada di kode selamanya karena alasan operasional. Entri changelog membicarakan ketersediaan bagi pembaca, bukan detail implementasi tentang bagaimana ketersediaan itu terwujud.

Bagaimana jika flag dihapus dan fitur dimatikan alih-alih dirilis? Itu adalah penolakan, bukan notifikasi rilis, dan pantas mendapat kehati-hatian yang sama seperti penolakan lainnya. Cara menolak permintaan fitur membahas apa yang seharusnya dikatakan pesan itu; menutup lingkaran dengan jujur kadang berarti menutupnya dengan penolakan.

Apakah release notes feature flag butuh template terpisah dari entri normal? Tidak ada perubahan template, hanya satu langkah gating sebelum publikasi: periksa status flag untuk akun yang meminta, bukan hanya bahwa kodenya sudah di-merge, dan tahan entrinya sampai pemeriksaan itu lolos. Semua hal lain tentang entrinya, kata-katanya, panjangnya, disiplin FAQ-nya, tetap sama seperti release notes lainnya.

Cara melacak permintaan fitur tanpa kehilangannya

Mon, 07 Sep 2026 00:00:00 GMT

Pelacakan permintaan fitur hampir selalu gagal dengan salah satu dari dua cara. Entah permintaan tidak punya tempat tujuan, sehingga hidup di kotak masuk dan thread Slack di mana dilupakan satu per satu, atau punya tempat tujuan yang tak pernah dilihat lagi, sehingga dilupakan bersamaan. Sistem yang berfungsi harus tahan terhadap kedua kegagalan itu: butuh satu tempat di mana setiap permintaan mendarat, dan alasan untuk membuka tempat itu lagi bulan depan.

Dari mana sebenarnya permintaan fitur berasal?

Dari lebih banyak kanal dari yang diperhitungkan kebanyakan sistem pelacakan. Tiket dukungan yang menyertakan "akan bagus kalau". Komentar di roadmap publik. Panggilan penjualan di mana calon pelanggan menyebutkan satu hal yang menghalangi kesepakatan. Widget di dalam produk. Setiap kanal punya pemiliknya sendiri dan alatnya sendiri, dan justru karena itulah permintaan tersebar: antrean tiket dukungan dan backlog tim produk jarang menjadi sistem yang sama, dan permintaan yang hanya mencapai salah satunya, dalam praktiknya, hanya mencapai satu departemen.

Sumber	Pemilik umum	Di mana biasanya hilang
Tiket dukungan	Tim dukungan	Ditutup sebagai selesai, tak pernah dilihat lagi
Panggilan penjualan	Penjualan / manajemen akun	Kolom CRM yang tak dibaca siapa pun di produk
Widget di produk	Produk	Kiriman formulir tanpa tindak lanjut
Komentar roadmap	Siapa pun yang membangun roadmap	Thread komentar itu sendiri
Media sosial / ulasan	Pemasaran atau tidak ada	Ditangkap layar sekali, lalu hilang

Satu formulir intake untuk setiap kanal tidak berhasil, karena tidak ada yang mengadopsinya. Yang berhasil adalah satu tujuan yang menjadi muara setiap kanal, meskipun perutean pada awalnya lima menit salin-tempel per hari sampai diotomatisasi.

Apa yang sebenarnya merusak pelacakan permintaan fitur?

Hampir selalu dua hal. Pertama, tujuan yang tidak ada: permintaan dijawab di kanal tempat kedatangannya dan tak pernah tercatat secara permanen di mana pun, sehingga permintaan yang sama dari tiga pelanggan berbeda terlihat seperti tiga jawaban terpisah yang tak berhubungan alih-alih satu sinyal. Kedua, lebih sering terjadi, tujuan yang penuh dan berhenti dibaca. Spreadsheet dengan 400 baris tanpa penyaringan bukan lagi sistem pelacakan; itu arsip yang kebetulan bisa ditulis.

Kegagalan kedua lebih berbahaya, karena terlihat seolah pelacakan berfungsi. Permintaan tercatat. Tidak ada yang terlihat rusak sampai seseorang bertanya "berapa banyak orang yang meminta X" dan jawaban jujurnya adalah "kami harus membaca semua 400 baris untuk mengetahuinya".

Apa yang sebenarnya harus dicatat permintaan fitur?

Cukup untuk menjawab tiga pertanyaan nanti tanpa membaca ulang pesan asli: apa yang diminta, sedapat mungkin dengan kata-kata sendiri dari yang meminta; siapa yang meminta, dan cara menghubunginya jika jawabannya akhirnya "kami sudah membangunnya"; dan apa yang dibutuhkan untuk mengetahui apakah ini permintaan umum atau kasus satu kali. Kutipan langsung lebih berharga daripada parafrasa, karena parafrasa yang ditulis oleh siapa pun yang melakukan triase permintaan sudah membawa pembacaannya sendiri, dan justru pembacaan itulah yang tak bisa diperiksa orang kedua enam bulan kemudian.

Label mana yang layak dipakai?

Dua, dan menjawab pertanyaan berbeda. Label jenis memisahkan permintaan fitur dari laporan bug, karena keduanya butuh pemilik dan lini masa berbeda, dan mencampurnya dalam satu antrean membiarkan keluhan paling keras menggeser permintaan. Label prioritas, dijaga tetap pada set kecil seperti low, medium, dan high, memisahkan "menghalangi seseorang memakai produk" dari "akan bagus", karena keduanya pantas mendapat waktu respons yang sangat berbeda dan tak satu pun seharusnya mewarisi ritme yang lain. Menerapkan label jenis dengan benar mengasumsikan permintaan itu adalah seperti yang diklaimnya; ketika permintaan fitur sebenarnya adalah laporan bug membahas kasus di mana kata-kata pelanggan sendiri mengarahkan label itu ke arah yang salah.

Triase otomatis bisa menerapkan keduanya saat permintaan tiba. Di changeloop, kiriman widget mendapat label feature-request atau bug dan label priority:low|medium|high dalam langkah yang sama, ditambah tag from-widget sehingga sumbernya terlihat tanpa membuka itemnya. Itu cukup untuk menyaring backlog dalam semenit alih-alih semalam: tunjukkan setiap permintaan fitur berprioritas tinggi dari widget bulan ini.

Label ketiga layak dipakai begitu ada roadmap publik: status yang bisa dicek sendiri oleh yang meminta. Roadmap publik membahas status planned, building, dan shipped secara lengkap; singkatnya, label itu mengubah antrean privat menjadi sesuatu yang bisa dicek yang meminta tanpa bertanya lagi.

Bagaimana memutuskan apa yang dibangun selanjutnya?

Kelompokkan sebelum menghitung. Sepuluh permintaan yang diformulasikan berbeda untuk kapabilitas mendasar yang sama terbaca sebagai sepuluh baris tersebar di spreadsheet, dan sebagai sinyal kuat begitu dikelompokkan, dan pengelompokan itu biasanya langkah yang hilang, bukan penghitungannya. Hitungan mentah tanpa pengelompokan cenderung menghargai fitur dengan nama paling menarik, bukan yang punya permintaan nyata terbanyak di baliknya.

Timbang berdasarkan siapa yang meminta, bukan hanya berapa banyak yang meminta. Permintaan dari akun yang mendekati perpanjangan membawa urgensi berbeda dari permintaan yang sama dari pendaftaran uji coba, dan sistem pelacakan yang membuang konteks itu demi hitungan telanjang mengoptimalkan angka yang paling mudah dihitung, bukan yang paling berguna.

Setiap keputusan di sini juga menghasilkan permintaan yang kalah, dan itu juga pantas mendapat balasan; cara menolak permintaan fitur membahas apa yang harus dikatakan pada yang permintaannya tidak lolos. Mengelompokkan dan menimbang hanya separuh dari "apa yang dibangun selanjutnya"; memprioritaskan permintaan fitur membahas kerangka sesungguhnya, RICE, penimbangan pendapatan, dan hitungan mentah, serta di mana masing-masing gagal.

Bagaimana menutup lingkaran setelah sesuatu dirilis?

Ini langkah yang paling sering dilewatkan sistem pelacakan, dan yang benar-benar disadari yang meminta. Menutup lingkaran umpan balik dengan pelanggan membahas mekanismenya secara lengkap; yang relevan di sini adalah menutup lingkaran hanya berfungsi jika permintaan asli tetap terhubung dengan yang memintanya. Templat permintaan fitur yang dibangun dari issue GitHub, dengan identitas yang meminta melekat pada issue alih-alih terkubur dalam komentar, adalah yang membuat notifikasi "dirilis" otomatis mungkin terjadi alih-alih yang harus diingat seseorang untuk dikirim. Templat permintaan fitur menunjukkan templat konkretnya dan untuk apa setiap kolom.

FAQ

Alat apa yang harus saya pakai untuk melacak permintaan fitur? Apa yang sudah dicek tim setiap hari mengalahkan alat khusus apa pun yang tak dibuka siapa pun. Pelacak issue GitHub bekerja baik jika engineering sudah hidup di sana; papan ringan bekerja baik jika produk hidup di sana. Alatnya kurang penting dibanding apakah dibuka lagi.

Bagaimana mencegah permintaan fitur terduplikasi? Kelompokkan berdasarkan kapabilitas mendasar sebelum melakukan triase berdasarkan kata-kata. Pencarian di antara permintaan yang ada sebelum membuat yang baru menangkap sebagian besar duplikat; sesi pengelompokan bulanan menangkap sisanya. Menggabung duplikat tanpa kehilangan suara asli membahas apa yang harus dilakukan dengan kata-kata itu begitu pengelompokan sendiri selesai, sehingga penggabungan tidak diam-diam mempersempit permintaan ke pengiriman mana pun yang tiba lebih dulu.

Haruskah setiap permintaan fitur mendapat balasan? Setiap permintaan harus mendapat konfirmasi, walau singkat, tapi tidak setiap permintaan butuh keputusan segera. Status yang terlihat, seperti label roadmap yang bisa dicek sendiri oleh yang meminta, menggantikan sebagian besar balasan individu yang seharusnya menjadi kewajiban tim.

Apa bedanya pelacakan permintaan dengan roadmap publik? Pelacakan adalah catatan internal dari setiap permintaan, termasuk yang tak akan pernah dirilis. Roadmap publik adalah subset yang secara publik dikomitmenkan tim, dengan status yang bisa dilihat yang meminta tanpa bertanya lagi.

Ketika permintaan fitur sebenarnya adalah laporan bug

Mon, 07 Sep 2026 00:00:00 GMT

"Bisakah Anda menambahkan pengaturan untuk menaikkan batas ekspor?" terbaca seperti permintaan fitur, dan kebanyakan sistem triase melabelinya begitu di tempat. Kadang memang begitu. Kadang ekspor gagal pada angka di bawah batas yang didokumentasikan karena sebuah bug, dan pelanggan, yang tidak bisa melihat kode, sudah mengarang solusi paling masuk akal yang bisa dia jelaskan: beri saya angka lebih besar dan mungkin akan berfungsi. Label mana yang layak dipakai membahas label jenis yang membagi backlog menjadi permintaan fitur dan bug; ini adalah kasus di mana kata-kata pelanggan sendiri mengarahkan label ke arah yang salah, dan biaya kesalahannya adalah pergeseran lambat menuju backlog penuh permintaan yang tak benar-benar diinginkan siapa pun begitu dilihat lebih dalam.

Seperti apa permintaan fitur yang sebenarnya adalah bug?

Menyebutkan cara mengakali alih-alih masalahnya. Permintaan fitur yang sungguhan biasanya menjelaskan hasil yang sama sekali tidak didukung produk: "biarkan saya menjadwalkan ini untuk nanti", "tambahkan mode gelap". Bug yang salah diklasifikasikan menjelaskan angka, ambang batas, atau perilaku spesifik yang terdengar seperti pengaturan yang hilang tapi sebenarnya adalah gejala: "naikkan timeout", "tambahkan opsi retry", "biarkan saya mengekspor lebih banyak baris sekaligus". Tandanya adalah peminta mengusulkan implementasi, pengaturan, sakelar, override, alih-alih menjelaskan tujuan, karena dia sudah mencoba fitur seperti yang didokumentasikan dan itu tidak melakukan apa yang dikatakan dokumentasi seharusnya dilakukan.

Sinyal	Permintaan fitur	Bug menyamar sebagai permintaan fitur
Apa yang dijelaskan peminta	Hasil yang tidak bisa dilakukan produk	Parameter yang ingin diubahnya
Apakah perilaku terdokumentasi sudah mencakup ini	Tidak, benar-benar hilang	Ya, tapi tidak berfungsi seperti didokumentasikan
Apakah upaya lebih membuat permintaan hilang	Tidak	Kadang, jika bug bergantung ambang batas
Ke mana seharusnya dirutekan	Backlog produk	Antrean bug

Mengapa ini lebih penting dari kedengarannya?

Karena kedua antrean punya pemilik, lini masa, dan kriteria sukses berbeda, dan bug yang diarsipkan sebagai permintaan fitur diprioritaskan melawan permintaan fitur, bersaing untuk perhatian dengan celah produk sungguhan alih-alih diperbaiki sesuai lini masa yang layak diterima bug. Cara melacak permintaan fitur membahas mengapa mencampur bug dan fitur dalam satu antrean membiarkan keluhan paling keras menggeser permintaan sungguhan; permintaan fitur yang diam-diam adalah bug melakukan kerusakan sebaliknya, tetap di backlog produk mengumpulkan suara untuk "fitur" yang akan hilang begitu bug yang mendasarinya diperbaiki, yang membuang sinyal prioritas untuk siapa pun yang membaca backlog itu.

Bagaimana membedakannya ketika kata-kata pelanggan sendiri mengarah ke arah yang salah?

Tanyakan apa yang dia harapkan terjadi, bukan apa yang dia ingin Anda tambahkan. "Ekspornya terhenti di 500 baris dan saya butuh 2.000, bisakah Anda menaikkan batasnya" terdengar seperti permintaan fitur kenaikan batas sampai pertanyaan lanjutan, "apakah 500 batas yang didokumentasikan," mengungkap bahwa angka yang didokumentasikan adalah 5.000 dan ekspor gagal lebih awal. Satu pertanyaan itu saja, apa yang diharapkan versus apa yang terjadi, melakukan sebagian besar pekerjaan penyortiran, karena permintaan fitur sungguhan tidak punya perilaku terdokumentasi yang tidak dipenuhinya; tidak ada yang bisa diharapkan karena kemampuannya belum ada.

Haruskah agen dukungan atau engineer yang memutuskan ini?

Agen dukungan melakukan pemeriksaan pertama, karena mereka melihat tiket lebih dulu, tapi labelnya seharusnya mudah diubah dan murah untuk salah, bukan keputusan sekali jadi yang mengunci item itu di antrean salah selamanya. Pemeriksaan kedua yang ringan, seorang engineer yang menyisir label "permintaan fitur" baru setiap minggu untuk apa pun yang berbau bug tersamar, menangkap yang tidak bisa dikenali agen dukungan tanpa konteks basis kode. Ini tidak perlu formal; lebih seperti pandangan lima menit daripada proses peninjauan.

Apakah menutup lingkaran berubah setelah bug sungguhan ditemukan?

Ya, dan itu memperbaiki pesan yang bisa Anda kirim. Menutup lingkaran umpan balik pelanggan membahas memberi tahu peminta saat permintaannya dirilis; bug yang diklasifikasikan ulang mendapat versi lebih baik dari pesan itu, karena "kami menemukan dan memperbaiki bug di balik ini" terdengar seperti kompetensi, sementara "kami membangun fitur yang Anda minta" hanya akan benar secara kebetulan, karena permintaan fitur sungguhan, batas ekspor yang benar-benar lebih tinggi, mungkin tidak pernah dibangun begitu bug hilang dan batas asli 5.000 baris sudah cukup.

Apa yang terjadi jika kesalahan klasifikasi tidak pernah tertangkap?

Backlog terisi permintaan yang terlihat seperti permintaan sungguhan tapi bukan, dan keputusan prioritas yang diambil melawan backlog itu mewarisi distorsinya. "Fitur" dengan empat puluh suara bisa jadi sebenarnya empat puluh orang yang mengalami bug yang sama, dan membangun permintaan literalnya, pengaturan untuk menaikkan batas yang sebenarnya tak pernah jadi kendalanya, memberikan kompleksitas yang tidak memperbaiki apa pun, sementara bug yang mendasari terus menghasilkan "permintaan fitur" baru dari pelanggan yang belum menemukan thread ini.

FAQ

Apakah layak menambahkan langkah formal untuk memeriksa setiap permintaan fitur terhadap bug yang diketahui? Bukan langkah formal, lebih ke kebiasaan: siapa pun yang mentriase permintaan fitur baru seharusnya bertanya "apakah perilaku terdokumentasi sudah mengklaim melakukan ini" sebelum menerapkan label, karena satu pertanyaan itu saja menangkap sebagian besar kesalahan klasifikasi tanpa menambah beban proses.

Bagaimana jika pelanggan tetap bersikeras itu permintaan fitur bahkan setelah bug ditemukan? Jelaskan apa yang Anda temukan dan mengapa pengaturan yang diusulkannya tidak akan diperlukan lagi begitu bug diperbaiki. Kebanyakan pelanggan meminta cara mengakali karena mereka berasumsi perbaikan sungguhan tidak tersedia, bukan karena mereka secara khusus menginginkan pengaturan itu.

Apakah item yang diklasifikasikan ulang kehilangan suara atau komentar yang dikumpulkannya sebagai permintaan fitur? Seharusnya tetap disimpan, terlihat, karena suara itu adalah bukti yang membawa penemuan bug sejak awal, dan menyembunyikan jejak itu membuat kesalahan klasifikasi yang sama lebih sulit tertangkap lain kali, pada tiket berbeda.

Bisakah ini terjadi sebaliknya, laporan bug yang sebenarnya adalah permintaan fitur? Lebih jarang, tapi bisa: "ini rusak" kadang berarti "ini tidak melakukan apa yang saya asumsikan akan dilakukannya," yang merupakan kemampuan yang hilang, bukan cacat. Pertanyaan yang sama, apa yang diharapkan versus apa yang didokumentasikan, juga menyortir ke arah ini.

Tiket dukungan vs. permintaan fitur: mana yang Anda percaya?

Mon, 07 Sep 2026 00:00:00 GMT

Papan permintaan fitur menangkap apa yang diminta pengguna saat mereka punya waktu untuk duduk dan menjelaskan apa yang mereka inginkan. Tiket dukungan menangkap di mana pengguna terjebak sekarang, sering jengkel, sering tanpa kosakata untuk menjelaskan dengan rapi permintaan yang mendasarinya. Keduanya adalah sinyal nyata, dan tim yang hanya melihat salah satunya akhirnya menyelesaikan masalah yang salah dengan percaya diri, karena setiap kanal secara sistematis terlalu mewakili jenis pengguna yang berbeda dan jenis kebutuhan yang berbeda. Memprioritaskan permintaan fitur membahas peringkat apa yang sudah ada di papan; ini tentang kesenjangan antara apa yang sampai ke papan sama sekali dan apa yang hanya pernah muncul sebagai tiket dukungan.

Mengapa masalah yang mendasari sama bisa muncul di satu kanal dan tidak di kanal lain?

Karena kedua kanal punya biaya aktivasi berbeda, dan besarnya biaya itu menentukan siapa yang melewatinya. Mengajukan permintaan fitur butuh inisiatif: pengguna harus percaya bahwa permintaan itu layak diungkapkan, menemukan papannya, dan menulis sesuatu yang koheren, yang menyeleksi pengguna yang terlibat dan sabar yang sudah berinvestasi dalam produk. Mengajukan tiket dukungan hampir tidak butuh inisiatif dibandingkan itu, sering hanya klik "bantuan" di tengah tugas, yang berarti itu menangkap pengguna yang frustrasi saat itu, termasuk mereka yang tidak akan pernah repot dengan papan permintaan fitur sama sekali. Kesenjangan nyata dalam produk bisa tidak terlihat di papan fitur dan ribut di dukungan hanya karena pengguna yang mengalaminya adalah yang paling kecil kemungkinannya mengajukan permintaan formal.

Apakah volume tiket untuk fitur yang hilang berarti sama dengan jumlah suara untuk itu?

Tidak, karena keduanya mengukur populasi berbeda dalam kondisi berbeda. Permintaan fitur dengan seratus suara mewakili seratus orang yang meluangkan waktu untuk menemukan dan mendukung permintaan yang sudah ada, yang merupakan sinyal kuat permintaan yang bertahan dan dipertimbangkan. Seratus tiket dukungan tentang kesenjangan yang mendasari sama, diajukan dalam periode yang sama, kemungkinan mewakili pengguna yang menabrak tembok saat itu, beberapa di antaranya akan sepenuhnya lupa begitu gesekan langsungnya berlalu. Memperlakukan keduanya sebagai sinyal setara "seratus orang menginginkan ini" terlalu membobot volume tiket, karena tiket murah untuk dihasilkan dan suara tidak.

Papan permintaan fitur	Tiket dukungan
Butuh inisiatif untuk mengajukan	Hampir tidak butuh
Menangkap permintaan yang dipertimbangkan dan bertahan	Menangkap frustrasi saat itu
Condong ke pengguna yang terlibat dan sabar	Menangkap pengguna yang tidak akan pernah pakai papan
Jumlah suara adalah sinyal komitmen nyata	Jumlah tiket mencerminkan gesekan, tidak selalu keinginan

Apa artinya jika sebuah fitur punya tiket dukungan tapi hampir tidak ada suara di papan?

Sering kali, permintaan itu ada tapi pengguna yang mengalaminya tidak tahu papan itu ada, tidak percaya voting akan mengubah apa pun, atau menghadapi masalah itu terlalu jarang untuk repot berpindah kanal demi mendaftarkannya secara formal. Ini persis populasi yang secara struktural terlewat oleh papan permintaan, dan jumlah suara yang rendah di sini adalah bukti kesenjangan pengukuran, bukan bukti permintaan rendah. Perlakukan kelompok tiket dukungan seputar fitur yang hilang sebagai sinyalnya sendiri yang layak Anda daftarkan sendiri ke papan, atas nama pengguna, alih-alih tidak percaya pada tiket itu, agar tidak tetap tidak terlihat bagi siapa pun yang memprioritaskan hanya dari jumlah suara.

Papan terbaca sebagai prioritas rendah:
"Export to CSV": 4 suara dalam 6 bulan

Dukungan menceritakan kisah berbeda:
"Export to CSV": 31 tiket dalam periode yang sama, masing-
masing dari akun berbeda, masing-masing ditutup dengan
"belum didukung saat ini, akan meneruskan masukan"

Apakah lonjakan tiket dukungan selalu berarti masalah yang mendasari adalah fitur yang hilang?

Tidak, dan di sinilah kedua kanal bisa menyesatkan ke arah yang berlawanan. Lonjakan tiket sama seringnya disebabkan oleh antarmuka yang membingungkan seputar fitur yang sudah ada, bug, atau perubahan yang keluar tanpa penjelasan memadai, yang tidak satu pun terselesaikan dengan membangun sesuatu yang baru. Membaca setiap lonjakan tiket sebagai "pengguna menginginkan fitur yang tidak kami miliki" menghasilkan roadmap penuh hal-hal yang sebenarnya adalah kesenjangan dokumentasi atau masalah kegunaan yang menyamar. Tiket dukungan memberi tahu Anda di mana gesekannya; itu sendiri tidak memberi tahu Anda apakah solusinya fitur baru, perubahan antarmuka, atau artikel bantuan yang lebih baik, dan mencampuradukkan itu membuang waktu rekayasa untuk solusi yang salah.

Bagaimana kedua sinyal itu seharusnya benar-benar digabungkan saat memutuskan apa yang dibangun?

Gunakan tiket untuk menemukan di mana gesekannya, dan gunakan papan permintaan, ditambah jangkauan langsung di mana papannya tipis, untuk mengonfirmasi seperti apa hasil yang sebenarnya diinginkan. Kelompok tiket mengidentifikasi masalah nyata yang dirasakan; jarang menentukan solusi cukup presisi untuk dibangun, karena pengguna yang frustrasi dalam percakapan dukungan menjelaskan gejala, bukan spesifikasi. Papan permintaan, ketika punya cukup suara pada masalah yang mendasari sama, cenderung membawa lebih banyak detail "apa yang benar-benar akan memuaskan ini", karena menulis permintaan sudah merupakan tindakan menentukan apa yang diinginkan, bukan sekadar melaporkan apa yang salah.

Haruskah agen dukungan mencatat tiket sebagai permintaan fitur sendiri?

Ya, dan ini perbaikan berdaya ungkit tertinggi untuk kesenjangan antara kedua kanal. Agen yang mengenali tiket sebagai permintaan fitur yang menyamar, alih-alih hanya menyelesaikannya dan melanjutkan, bisa mencatatnya ke papan atas nama pelanggan, yang langsung menutup kesenjangan pengukuran alih-alih mengharuskan pelanggan menemukan dan menggunakan kanal kedua. Ini hanya berhasil jika mencatat memakan waktu detik bagi agen, bukan menit, sehingga gesekan melakukannya lebih rendah daripada gesekan hanya menutup tiket dan pindah ke berikutnya.

FAQ

Haruskah suara permintaan fitur pernah didiskon jika semuanya berasal dari satu akun atau tim? Ya, timbang berdasarkan akun atau organisasi yang berbeda alih-alih jumlah suara mentah, karena lima suara dari lima orang di perusahaan yang sama mewakili prioritas satu pelanggan, bukan lima konfirmasi independen permintaan.

Apakah layak membangun fitur yang banyak muncul di tiket tapi hampir tidak ada suara? Sering ya, asalkan volume tiket benar-benar berasal dari akun berbeda dan kebutuhan yang mendasari dikonfirmasi bukan diasumsikan; perlakukan jumlah suara yang rendah sebagai artefak pengukuran biaya aktivasi papan, bukan bukti bahwa permintaannya tidak nyata.

Bagaimana cara membedakan sekilas tiket kebingungan UI dari tiket fitur hilang yang genuine? Lihat apakah resolusinya melibatkan menjelaskan kemampuan yang sudah ada atau meminta maaf atas yang hilang. Pola resolusi "oh, sebenarnya ada di sana" menunjuk masalah antarmuka atau kemudahan penemuan; pola "kami belum mendukung itu" menunjuk kesenjangan nyata.

Apakah perbedaan ini sama pentingnya dengan volume dukungan yang sangat kecil? Secara mekanis kurang penting, karena segelintir tiket mudah dibaca satu per satu tanpa perlu analisis agregat, tapi bias yang mendasarinya, tiket terlalu mewakili pengguna frustrasi dan kurang mewakili yang sabar, hadir di skala mana pun dan layak diingat bahkan saat Anda membaca setiap tiket sendiri.

Tag git, rilis, dan changelog Anda

Mon, 07 Sep 2026 00:00:00 GMT

Tag git, rilis, dan entri changelog adalah tiga catatan berbeda dari peristiwa yang sama, dan mencampuradukkannya membuat changelog diam-diam melenceng dari apa yang sebenarnya dirilis. Tag menandai commit. Rilis mengemas tag itu dengan artefak dan deskripsi. Entri changelog menjelaskan, dengan istilah yang bisa dipakai pembaca di luar repositori, apa yang berubah. Biasanya terjadi berdekatan waktunya, dan justru karena itu mudah memperlakukannya sebagai satu langkah alih-alih tiga, dan justru karena itu jaraknya baru terlihat berbulan-bulan kemudian, saat seseorang bertanya "apa yang dirilis di v2.4" dan jawaban jujurnya butuh penggalian sungguhan.

Apa sebenarnya perbedaan di antara ketiganya?

Catatan	Hidup di	Ditulis untuk
Tag git	Repositori, sebagai referensi	Siapa pun yang checkout commit persis itu
Rilis	Host kode (GitHub, GitLab)	Siapa pun yang mengunduh build
Entri changelog	Changelog produk itu sendiri	Siapa pun yang memakai produk, bukan hanya repo

Tag adalah yang paling mekanis dari ketiganya: git tag v2.4.0 dan selesai, tanpa syarat apa pun yang harus menjelaskan isinya. Rilis menambahkan deskripsi dan biasanya artefak yang bisa diunduh, dan audiensnya tetap developer yang tahu apa itu halaman rilis. Entri changelog adalah satu-satunya dari ketiganya yang ditulis untuk pembaca yang mungkin tidak pernah membuka repositori, itu sebabnya ini yang butuh perhatian editorial paling banyak dan paling mungkin dilewati di bawah tekanan tenggat.

Apakah setiap tag git butuh entri changelog?

Tidak, dan memperlakukannya satu-lawan-satu adalah kesalahan umum. Tag bisa menandai tonggak internal, release candidate, atau hotfix yang tidak pernah menjangkau kebanyakan pengguna; tak satu pun dari itu harus punya entri publik. Ujinya sama dengan yang menentukan apakah sesuatu layak masuk changelog sama sekali: apakah pengguna atau pemanggil akan menyadari atau mempedulikannya. Kebanyakan tag lolos uji itu. Beberapa, seperti tag yang dibuat hanya untuk memicu pipeline CI, tidak pernah.

Apakah setiap entri changelog butuh tag sendiri?

Tidak selalu, dan di sinilah tim yang deploy berkelanjutan berbeda dari tim yang merilis paket berversi. Produk SaaS yang deploy beberapa kali sehari bisa mengelompokkan beberapa deploy di bawah satu entri changelog bertanggal tanpa tag 1:1 per deploy; pustaka yang dipublikasikan di registri paket biasanya butuh satu tag per versi yang dipublikasikan. Go modules dan Swift Package Manager me-resolve versi dari tag itu sendiri; di npm atau PyPI registri menyimpan versi yang dipublikasikan, dan tag adalah cara siapa pun memetakan versi itu kembali ke sumbernya. Repositori dengan beberapa paket yang diversi secara independen harus memutuskan ini per paket, bukan sekali untuk seluruh repo; changelog monorepo membahas bagaimana prefiks tag dan cakupan changelog seharusnya mengikuti batas paket, bukan batas folder. Semantic versioning dan changelog Anda membahas bagaimana nomor versi itu sendiri seharusnya memetakan ke kategori changelog; tag adalah mekanisme yang membuat nomor versi bisa diverifikasi terhadap kode sebenarnya.

Bagaimana deskripsi rilis seharusnya berkaitan dengan entri changelog?

Keduanya bisa jadi teks yang sama, tapi hanya jika audiens keduanya benar-benar sama, yang lebih jarang dari kelihatannya. Halaman rilis di host kode dibaca hampir seluruhnya oleh developer; jika produk juga punya pengguna non-teknis yang membaca changelog, menduplikasi deskripsi rilis apa adanya mengirim istilah internal dan formulasi berorientasi kode ke pembaca yang butuh versi bahasa awam. Pola paling bersih: tulis entri changelog sebagai artefak utama yang berorientasi pembaca, dan biarkan deskripsi rilis menautkannya atau menyimpan ringkasan yang lebih pendek dan teknis untuk audiens yang sudah nyaman di sana.

# Rilis v2.4.0 (GitHub, untuk developer)
Meningkatkan pipeline laporan ke mesin agregasi baru. Lihat changelog
untuk ringkasan berorientasi pelanggan:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, berorientasi pelanggan)
### Added
- Laporan sekarang dimuat dalam kurang dari satu detik, bahkan untuk
  akun dengan lebih dari satu juta baris.

Rilis yang sama, dua dokumen, masing-masing dengan formulasinya sendiri untuk pembacanya sendiri.

Dari mana sebenarnya entri changelog berasal?

Dari dua titik awal, dan kebanyakan pipeline nyata adalah campuran keduanya. Bisa dihasilkan dari pesan commit pada saat tag, yang cepat dan tidak pernah melewatkan pull request yang digabung; dari conventional commits ke changelog membahas pipeline itu secara lengkap. Atau bisa ditulis manual, terpisah dari tag sepenuhnya, disinkronkan dengan saat fitur dianggap selesai alih-alih saat kode digabung. Entri yang dihasilkan konsisten tapi mewarisi setiap pesan commit yang samar; entri yang ditulis manual lebih jelas tapi butuh seseorang untuk benar-benar menulisnya. Kebanyakan tim yang mengotomatisasi tetap menjaga langkah penyuntingan ringan pada teks yang dihasilkan sebelum menjadi entri publik, disiplin yang sama yang direkomendasikan Keep a Changelog, dalam praktik, terlepas dari dari mana teks mentahnya awalnya berasal.

Apa yang rusak ketika ketiganya tidak sinkron?

Kepercayaan pada yang dicek pembaca lebih dulu. Tag yang ada tanpa entri changelog yang sesuai terlihat, dari sisi pembaca changelog, seolah tidak terjadi apa-apa minggu itu. Entri changelog tanpa tag atau rilis yang sesuai membuat mustahil bagi seseorang yang men-debug masalah produksi untuk checkout kode persis yang live saat entri dipublikasikan. Solusinya bukan otomatisasi sempurna, tapi satu sumber kebenaran untuk pemetaan itu: satu tempat, meski hanya checklist proses rilis itu sendiri, yang menyatakan perubahan yang bisa dirilis mendapat ketiganya, dalam commit atau pull request yang sama yang memperkenalkannya.

FAQ

Haruskah entri changelog dihasilkan otomatis dari tag git? Bisa jadi titik awal, tapi tag saja tidak membawa deskripsi berorientasi pembaca, hanya rentang commit. Generasi otomatis harus membaca pesan commit dalam rentang itu, bukan hanya keberadaan tag, untuk menghasilkan sesuatu yang bisa dipakai.

Bagaimana jika kami tidak men-tag setiap rilis? Maka entri changelog menjadi catatan utama, dan tetap harus membawa tanggal dan, jika produk punya, nomor versi, sehingga entri tetap jadi sesuatu yang bisa dirujuk pembaca nanti bahkan tanpa tag yang sesuai.

Haruskah tag pra-rilis (seperti v2.4.0-rc.1) punya entri changelog? Umumnya tidak. Release candidate untuk pengujian internal atau beta, dan entri changelog untuknya melatih pembaca mengharapkan entri untuk versi yang mungkin tidak pernah dirilis persis seperti dideskripsikan. Simpan entri untuk tag yang mencapai ketersediaan umum.

Bisakah satu entri changelog mencakup beberapa tag git? Ya, dan sering kali seharusnya begitu untuk tim yang sering men-tag. Kelompokkan tag terkait di bawah satu entri bertanggal yang mendeskripsikan perubahan bersih, alih-alih mempublikasikan entri tipis per tag yang memecah satu fitur ke beberapa bacaan.

Release notes internal: siapa lagi yang perlu tahu

Mon, 07 Sep 2026 00:00:00 GMT

Setiap artikel lain di hub ini mengasumsikan pembaca release note adalah pelanggan. Support, sales, dan customer success juga membaca, atau mencoba, dan kebanyakan tahu apa yang dirilis karena pelanggan bertanya lebih dulu. Urutan itu terbalik, dan itu juga default di kebanyakan perusahaan, karena proses rilis berakhir pada saat catatan untuk pelanggan keluar, dan tidak ada yang membangun langkah kedua yang lebih kecil untuk orang-orang yang harus menjawab pertanyaan tentangnya satu jam kemudian.

Apa itu release note internal, dan bagaimana bedanya dari yang untuk pelanggan?

Ini dokumen yang lebih singkat, ditulis untuk orang yang sudah mengenal produk secara mendalam, yang memberi tahu mereka apa yang berubah dan apa yang harus dilakukan soal itu dalam pekerjaan konkret mereka. Agen support tidak butuh pembingkaian yang dipoles yang dipakai pengumuman untuk pelanggan; mereka perlu tahu seperti apa perubahan itu di produk sekarang, apa pertanyaan yang paling mungkin muncul soal itu, dan apakah tiket yang terbuka terdampak. Catatan untuk pelanggan menjual perubahan. Catatan internal membekali seseorang untuk menanganinya.

Audiens	Yang perlu mereka tahu	Di mana mereka membutuhkannya
Support	Apa yang berubah di UI, pertanyaan yang mungkin muncul, tiket terbuka yang terdampak	Di mana mereka sudah mencari jawaban
Sales	Apa yang dibuka untuk sebuah kesepakatan, apa yang belum bisa dilakukan	Di mana mereka bersiap untuk panggilan
Customer success	Apa yang harus dikatakan pada pelanggan yang ada, dan siapa yang memintanya	Di mana mereka merencanakan outreach
Pimpinan	Apa yang dirilis dibanding yang dijanjikan, dan kapan	Ringkasan singkat dan berulang, bukan per rilis

Kenapa tim internal tahu peluncuran terlambat?

Karena proses rilis biasanya dibangun di sekitar satu artefak, catatan untuk pelanggan atau entri changelog, dan semua yang internal diasumsikan mengikuti dari membaca dokumen tunggal itu. Itu tidak benar. Agen support sibuk dengan tiket di depan mereka, bukan menelusuri changelog untuk mencari konteks, dan catatan yang ditulis untuk pelanggan sering kali melewatkan justru detail operasional yang dibutuhkan agen, seperti paket mana yang mendapat fitur itu atau seperti apa pesan errornya saat gagal. Pada saat pelanggan bertanya, agen sedang membaca catatan publik yang sama yang baru saja dibaca pelanggan, tanpa keunggulan apa pun.

Apa yang harus dikatakan release note internal yang tidak dikatakan catatan untuk pelanggan?

Detail operasional yang sengaja dihilangkan catatan untuk pelanggan. Paket atau akun mana yang memilikinya. Seperti apa jika ada yang salah, dan apa yang harus dikatakan pada pelanggan yang menemuinya. Apakah itu menutup permintaan atau tiket terbuka, dan yang mana, agar agen yang menangani tiket terkait tahu harus memeriksanya. Siapa di tim yang bertanggung jawab jika pertanyaan melampaui apa yang dicakup catatan itu. Tidak satu pun dari ini milik versi untuk pelanggan, yang ditulis untuk dibaca sekali oleh seseorang di luar perusahaan; semua ini justru yang dibutuhkan seseorang yang menjawab pertanyaan yang sama empat puluh kali seminggu.

Catatan internal: ekspor CSV massal (rilis 08-09-2026)

- Hanya untuk paket Team dan Enterprise. Free dan Pro tidak ada
  perubahan.
- Kegagalan umum: ekspor di atas 50rb baris timeout; masalah
  diketahui, perbaikan dilacak terpisah. Beri tahu pelanggan
  untuk menyaring berdasarkan rentang tanggal.
- Menutup 14 permintaan terbuka berlabel `bulk-export`. Template
  balasan ada di dokumen bersama.
- Penanggung jawab: tim platform, #platform-eng untuk apa pun
  di luar catatan ini.

Empat baris yang bisa langsung dipakai agen support, tidak satu pun akan masuk entri changelog publik untuk fitur yang sama.

Siapa yang harus menulisnya, dan kapan?

Siapa pun yang menulis catatan untuk pelanggan biasanya orang yang tepat, karena mereka sudah punya seluruh konteks, tapi ini harus jadi langkah singkat terpisah, bukan mencoba membuat satu dokumen melayani kedua audiens. Menggabungkannya menghasilkan catatan untuk pelanggan yang penuh detail internal, atau catatan internal yang terlalu dipoles hingga tidak lagi benar-benar berguna, dan dalam praktiknya lebih cepat menulis dua dokumen singkat daripada bernegosiasi satu dokumen untuk melayani dua audiens sekaligus. Waktu lebih penting daripada siapa penulisnya: catatan internal harus keluar sebelum yang untuk pelanggan, bahkan hanya beberapa jam lebih awal, agar support tidak pernah tahu perubahan dari tempat yang sama dengan pelanggan.

Di mana ia harus berada agar support benar-benar menemukannya saat ada tiket?

Di mana tim sudah mencari sesuatu saat tiket masuk, bukan di changelog terpisah yang tidak ada alasan bagi siapa pun untuk membukanya sendiri. Tim support yang memakai basis pengetahuan bersama butuh catatan itu di sana, ditautkan dari tempat tiket tentang bagian produk itu sudah dilabeli. Tim yang hidup di kanal bersama butuh catatan itu diposting di sana, bisa dicari, pada saat relevan, alih-alih terkubur dalam ringkasan harian yang mereka telusuri sekali. Pola untuk pelanggan dari notifikasi bertarget versus digest juga berlaku di sini: catatan internal tentang perubahan spesifik dan akan datang seharusnya menjangkau tim langsung, bukan menunggu ringkasan mingguan yang tiba setelah tiket pertama sudah ada.

Apakah butuh ketelitian peninjauan yang sama dengan yang eksternal?

Lebih sedikit, dan itu disengaja. Catatan untuk pelanggan mewakili perusahaan secara publik dan pantas mendapat langkah penyuntingan yang cermat; catatan internal ada untuk cepat dan konkret, dan memegangnya pada standar polesan yang sama biasanya justru yang membuat tim berhenti menulisnya sama sekali. Catatan internal yang cepat dan agak kasar yang keluar satu jam sebelum peluncuran mengalahkan yang dipoles yang tiba keesokan harinya, saat tiket support pertama sudah datang dengan kebingungan.

FAQ

Haruskah release notes internal melalui proses persetujuan yang sama dengan yang untuk pelanggan? Tidak. Langkah yang lebih ringan dan cepat justru intinya. Mewajibkan peninjauan yang sama mengubah catatan internal hari yang sama menjadi catatan minggu berikutnya, saat support sudah menjawab pertanyaan tanpanya.

Siapa yang bertanggung jawab atas release notes internal jika tidak ada peran khusus komunikasi internal? Siapa pun yang menulis catatan untuk pelanggan, sebagai langkah kedua yang singkat tepat setelahnya. Tidak butuh penanggung jawab terpisah, hanya kebiasaan untuk tidak memperlakukan catatan untuk pelanggan sebagai satu-satunya artefak yang dihasilkan sebuah rilis.

Apakah release notes internal butuh changelog atau arsip sendiri? Tempat yang bisa dicari mengalahkan arsip kronologis yang tidak pernah digulir siapa pun. Jika support sudah punya basis pengetahuan, catatan itu miliknya di sana, dilabeli ke fitur, alih-alih di changelog internal terpisah yang hanya membantu orang yang sudah tahu tanggal rilisnya.

Apa risiko melewatkan release notes internal untuk perubahan kecil? Perubahan kecil justru yang membuat support mendapat pertanyaan tanpa peringatan, karena perubahan kecil jarang mendapat pengumuman seluruh perusahaan. Ukuran release note harus mengikuti skala ukuran perubahan; itu tidak boleh turun ke nol hanya karena perubahannya kecil.

Changelog API internal: apa yang berubah bagi tim lain

Mon, 07 Sep 2026 00:00:00 GMT

Setiap artikel lain di hub ini mengasumsikan pemanggil sebuah API berada di luar perusahaan: insinyur dari pelanggan, mitra, seseorang yang menemukan dokumentasi sendiri. Banyak API punya jenis pemanggil yang sama sekali berbeda, tim di ruangan sebelah atau dua lantai berjarak, dan itu mengubah perhitungan tentang apa yang harus disampaikan changelog kepada mereka, karena pesan Slack bisa menjangkau mereka dan biasanya tidak pernah ada tiket support yang dibuka. Kebanyakan tim menyimpulkan dari ini bahwa API internal tidak butuh changelog. Yang sebenarnya mereka butuhkan adalah changelog yang berbeda.

Apa yang membuat changelog API internal berbeda dari yang publik?

Audiensnya bisa dijangkau langsung, yang menghilangkan alasan utama kebanyakan changelog API publik ada: menyiarkan ke pemanggil yang tidak bisa dihubungi satu per satu. Tim pemilik API internal biasanya tahu persis tim lain mana yang memanggilnya, kadang sampai ke service tertentu. Itu membuat pesan bertarget, bukan feed publik, jadi pilihan default alami, dan itulah sebabnya API internal begitu sering berakhir tanpa changelog sama sekali: tim pemilik memberi tahu dua atau tiga tim yang diingatnya, dengan asumsi itu sudah mencakup semua orang.

	Changelog API publik	Changelog API internal
Siapa yang membaca	Pemanggil eksternal mana pun, kebanyakan tidak bisa dihubungi langsung	Sekumpulan kecil tim internal yang biasanya diketahui
Kanal default	Halaman dan feed	Pesan ke tim pemanggil, idealnya juga halaman
Risiko terbesar	Pemanggil melewatkan entri sepenuhnya	Tim pemilik lupa pemanggil yang tidak diingatnya ada
Yang menggantikan "kami tidak tahu siapa yang memanggil kami"	Tidak ada; publikasikan secara luas	Registri pemanggil yang nyata dan terus diperbarui

Kenapa "kami akan memberi tahu tim yang memanggil kami saja" gagal?

Karena kumpulan pemanggil tidak pernah sekecil atau sestatis yang diingat tim pemilik. Sebuah service yang dibangun untuk satu konsumen mendapat pemanggil kedua enam bulan kemudian, lewat integrasi yang tidak pernah diumumkan siapa pun, dan daftar mental "siapa yang memanggil kami" milik tim pemilik sekarang salah tanpa disadari siapa pun. Kegagalan ini wajar dan umum, hasil default dari mengandalkan ingatan alih-alih catatan, bukan tanda ada yang ceroboh. Apa itu breaking change membahas cara memutuskan apakah suatu perubahan API dihitung sebagai breaking sejak awal; kasus internal menambahkan pertanyaan kedua yang lebih sulit di atas itu, yaitu mengetahui siapa yang harus diberi tahu.

Apakah API internal tetap butuh halaman changelog bergaya publik?

Biasanya ya, meski kanal utamanya langsung. Halaman memberi pesan langsung sesuatu untuk ditautkan, sehingga notifikasi bisa singkat ("breaking change di /v2/accounts, detail di sini") alih-alih mencoba membawa seluruh penjelasan dalam pesan chat yang akan tergeser dan hilang. Halaman itu juga jadi tempat yang bisa diperiksa tim baru, atau tim yang melewatkan pesan langsung, saat integrasi mereka rusak dan mereka mencoba mencari tahu kenapa. Halaman itu tidak perlu dipoles atau publik; halaman itu perlu bisa ditautkan dan bertahan lebih lama dari thread Slack yang mengumumkannya.

Siapa yang sebenarnya memelihara daftar pemanggil?

Tim pemilik, dan ini harus diperlakukan sebagai artefak nyata, bukan pengetahuan lisan. Versi termurah adalah file di repository API itu sendiri, daftar singkat service konsumen dengan penanggung jawab per entri, diperbarui setiap kali integrasi baru dibangun, disiplin yang sama seperti deklarasi dependensi apa pun. Alternatifnya, bertanya ke sana kemari sebelum setiap breaking change, berhasil sampai suatu kali seseorang lupa bertanya pada orang yang tepat, dan API internal yang rusak diam-diam bagi satu tim adalah insiden yang lebih kecil daripada yang publik, tapi tetap insiden, biasanya ditemukan oleh on-call tim itu sendiri alih-alih oleh pemilik API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

File seperti ini mengubah "siapa yang perlu kita beri tahu" dari pertanyaan menjadi pencarian. Tool yang dibangun persis untuk masalah ini, seperti service catalog Backstage, memodelkan API sebagai entitas kelas satu dengan konsumen yang dideklarasikan, untuk alasan yang sama: begitu sebuah organisasi punya cukup banyak service internal, ingatan siapa pun tentang siapa memanggil apa tidak lagi akurat dengan sendirinya, dan sesuatu harus menyimpan catatannya. Dokumentasi untuk tool apa pun yang sudah Anda jalankan secara internal biasanya tempat pertama yang tepat untuk diperiksa sebelum membangun yang khusus sendiri.

Apa yang masuk entri changelog internal yang tidak dibutuhkan changelog publik?

Kekhususan operasional yang lebih banyak, karena pembaca adalah insinyur lain yang akan bertindak atas ini dalam infrastruktur yang sama, bukan membacanya sebagai ringkasan. Di lingkungan mana perubahan itu live dan kapan, karena service internal sering dipromosikan lewat tahap-tahap yang tidak pernah dilihat pemanggil publik. Apakah perubahan itu memerlukan pembaruan konfigurasi atau library klien di sisi konsumen, dirumuskan sebagai perintah jika ada. Dan, karena pemanggil internal sering bisa mengoordinasikan perbaikan langsung dengan tim pemilik, kontak bernama alih- alih kanal support: "beri tahu @maria kalau ini merusak sesuatu" adalah baris yang sepenuhnya masuk akal dalam entri internal dan aneh dalam changelog API publik.

Apakah ini berlaku sama untuk changelog di dalam monorepo?

Ini mempertajam masalah yang sama alih-alih menggantikannya. Changelog monorepo membahas kapan sebuah paket butuh changelog sendiri; API internal yang menjadi salah satu dari beberapa paket dalam monorepo tetap butuh konsumennya dilacak secara eksplisit, karena berbagi repository yang sama dengan pemanggilnya tidak berarti mereka akan menyadari perubahan kecuali ada yang memberi tahu mereka untuk memperhatikan. Kedekatan dalam repo bukan hal yang sama dengan kedekatan dalam perhatian.

FAQ

Apakah API yang hanya internal butuh changelog jika hanya punya satu pemanggil? Hampir tidak, dan pesan langsung ke tim tunggal itu biasanya cukup. Changelog jadi berharga begitu ada lebih dari satu pemanggil, atau begitu daftar pemanggil pernah mengejutkan tim pemilik, karena itu tandanya ingatan saja tidak lagi bisa diandalkan.

Haruskah perubahan API internal melalui review yang sama seperti yang publik? Kata-katanya bisa lebih ringan, karena pembacanya kolega bukan pemanggil eksternal, tapi keputusan apakah suatu perubahan bersifat breaking pantas mendapat kehati-hatian yang sama di kedua kasus. Pemanggil internal tetap punya kode produksi yang bergantung pada perilaku lama.

Bagaimana cara mengetahui siapa yang memanggil API internal jika itu tidak pernah dilacak? Log server atau data trafik dari service mesh adalah jawaban jujur jika registri konsumen tidak pernah dipelihara; perlakukan penemuan itu sebagai saat untuk mulai memeliharanya, bukan sebagai pembersihan satu kali.

Apakah pesan Slack cukup, atau perubahan internal tetap butuh entri changelog formal? Keduanya, untuk apa pun yang bukan murni penambahan. Pesan adalah yang terbaca tepat waktu; entri adalah yang bisa tetap ditemukan oleh tim yang menyelidiki masalah berminggu-minggu kemudian dan tidak pernah melihat pesan itu.

Release notes mobile: apa yang dipotong batasan

Mon, 07 Sep 2026 00:00:00 GMT

Semua yang dibahas hub ini tentang menulis release notes mengasumsikan halaman yang sepenuhnya Anda kendalikan: panjang berapa pun, tautan yang berfungsi, format yang tampil. Release notes aplikasi mobile hidup di dalam kotak milik orang lain. Apple memberi sekitar 4.000 karakter tapi hanya menampilkan beberapa baris pertama sebelum "lainnya" disentuh; Google memberi ruang serupa dengan masalah pratinjau efektif yang sama, dan kedua platform tidak menampilkan tautan yang bisa diklik di dalam teks. Aturan dari cara menulis release notes yang benar-benar dibaca orang masih berlaku: katakan apa yang berubah dan apa yang harus dilakukan pembaca, tapi ruang untuk melakukannya hanya sebagian kecil dari yang diizinkan halaman changelog, dan pemotongan harus disengaja, bukan tidak sengaja.

Apa yang benar-benar muat dalam pratinjau yang terlihat?

Satu sampai dua baris pertama, sekitar 80 sampai 170 karakter tergantung perangkat dan ukuran font, sebelum pembaca harus menyentuh untuk memperluas. Itu seluruh anggaran untuk bagian release note yang menentukan apakah ada yang akan membaca sisanya, dan itu berarti kalimat paling penting harus datang lebih dulu, bukan nomor versi, bukan sapaan, bukan judul kategori. Release note yang dimulai dengan "Baru di versi ini:" sudah menghabiskan sepertiga ruang terlihatnya untuk empat kata yang tidak memberi tahu apa pun kepada pembaca.

Platform	Batas total perkiraan	Pratinjau efektif sebelum "lainnya"
App Store (iOS)	~4.000 karakter	2-3 baris, sekitar 80-170 karakter
Google Play	~500 karakter per bahasa, beberapa field lebih pendek	2-3 baris, mirip iOS
Keduanya	Tidak ada tautan yang bisa diklik di field release notes	T/A

Apakah aturan "apa yang bisa dilakukan sekarang, apa yang harus disampaikan" masih berlaku di panjang ini?

Ya, dan jadi lebih ketat, bukan berbeda. Satu kalimat per entri, kata kerja lebih dulu, tanpa basa-basi: "Ekspor data Anda sebagai CSV dari Pengaturan." mengalahkan "Kami telah menambahkan kemampuan bagi pengguna untuk sekarang mengekspor data mereka dalam format CSV" dengan menggunakan sepertiga kata untuk mengatakan hal yang sama. Pada panjang halaman changelog, kalimat yang agak bertele-tele merugikan pembaca setengah detik. Pada panjang release note mobile, bertele-tele yang sama bisa mendorong seluruh kalimat keluar dari pratinjau yang terlihat, sehingga pembaca tidak pernah melihat kata kerja yang akan memberi tahu apa yang berubah.

Buruk, memboroskan pratinjau untuk basa-basi:
"Kami senang menghadirkan pembaruan baru penuh
peningkatan! Baca terus untuk detailnya."

Baik, semua nilai di baris pertama:
"Ekspor data sebagai CSV. Mode gelap sekarang mengikuti
pengaturan sistem. Perbaikan crash saat membuka tautan
yang dibagikan."

Apa yang harus dipotong yang biasanya dipertahankan entri changelog web?

Tautan, pertama, karena kedua toko tidak menampilkannya sebagai bisa diklik, jadi URL di dalam teks adalah beban mati yang harus diketik ulang pembaca. Jika entri butuh tujuan, katakan apa yang harus disentuh di dalam aplikasi sebagai gantinya: "Lihat filter baru di bawah Pengaturan > Pencarian" berhasil; "Baca lebih lanjut di example.com/blog/filter" tidak, di permukaan ini. Kedua, apa pun yang bersyarat atau spesifik untuk audiens tertentu: changelog web bisa bilang "jika Anda memakai API, ini memengaruhi Anda", tapi daftar toko menjangkau setiap pengguna yang terpasang sekaligus, jadi baris bersyarat terbaca sebagai kebisingan bagi 95% yang tidak terpengaruh. Taruh detail bersyarat itu dalam pesan in-app sebagai gantinya, dipicu untuk akun yang benar-benar terkait.

Haruskah setiap rilis punya catatannya sendiri, atau boleh saja memakai ulang "perbaikan bug dan peningkatan performa"?

Pakai ulang untuk rilis yang benar-benar seperti itu, tapi audit seberapa sering itu benar-benar benar. Cara menulis release notes sudah membahas kenapa frasa itu mengkhianati catatan yang ditulis dari dalam alih-alih untuk pembaca; di mobile, ini merusak dua kali lipat, karena release notes toko adalah salah satu dari sedikit tempat sebagian pengguna melihat apa pun di antara pembaruan, dan rangkaian panjang "perbaikan bug dan peningkatan performa" terbaca seolah aplikasi tidak berubah, yang jadi kesan lebih buruk daripada tidak ada catatan sama sekali untuk periode itu.

Apakah release notes memengaruhi apakah orang memperbarui aplikasi sama sekali?

Secara tidak langsung, lewat visibilitas alih-alih persuasi. Kebanyakan pengguna memperbarui otomatis dan tidak pernah membaca catatan sebelum memperbarui; catatan paling penting bagi minoritas yang memeriksa pembaruan secara manual, dan bagi reviewer atau pers yang menyisir riwayat daftar toko. Menulis untuk audiens yang lebih kecil itu tetap terbayar, karena daftar dengan riwayat nyata entri spesifik dan bertanggal terbaca sebagai aplikasi yang aktif dirawat, dan daftar dengan setahun "perbaikan bug dan peningkatan performa" tidak, terlepas dari seberapa banyak yang sebenarnya dirilis dalam waktu itu.

Bagaimana dengan pembaruan paksa, di mana catatan harus menjelaskan kenapa pengguna tidak punya pilihan?

Nyatakan alasan dan tenggat waktu di baris pertama, sebelum yang lain, karena pembaruan paksa adalah satu kasus di mana pembaca sudah kesal sebelum mulai membaca. "Pembaruan ini diperlukan untuk terus menyinkronkan data Anda. Perbarui sebelum [tanggal] untuk menghindari gangguan." menyampaikan apa yang harus dilakukan dan kenapa dalam satu kalimat; mengubur alasan itu di bawah tiga baris catatan fitur yang tidak terkait terbaca seolah aplikasi menyembunyikan bagian yang tidak nyaman.

FAQ

Haruskah release notes mobile cocok dengan changelog web untuk rilis yang sama? Mencakup perubahan mendasar yang sama, tapi bukan kata demi kata. Changelog web bisa memberi penjelasan lengkap; catatan mobile butuh fakta yang sama dipadatkan jadi satu kalimat dengan kata kerja lebih dulu, yang biasanya berarti itu tulisan ulang, bukan salinan.

Apakah sepadan melokalkan release notes mobile untuk setiap bahasa yang didukung? Ya, lebih daripada untuk changelog web, karena daftar toko sering jadi satu-satunya permukaan terlokalkan yang dilihat sebagian pengguna di antara sesi, dan kedua platform mendukung release notes per locale tanpa kerja rekayasa tambahan di luar terjemahan itu sendiri.

Seberapa panjang release note mobile seharusnya jika tidak ada batas yang memaksa keringkasan? Tetap pendek. Batas 4.000 karakter di iOS jarang jadi kendala sebenarnya; yang jadi kendala adalah pratinjau 2-3 baris, dan menulis melebihi apa yang ditampilkan pratinjau itu hanya berarti lebih sedikit orang membaca bagian yang penting.

Apakah release notes butuh nomor versi di teks yang terlihat? Tidak. Toko sudah menampilkan nomor versi di sebelah catatan. Mengulanginya di dalam teks menghabiskan karakter terlihat untuk informasi yang sudah ada di depan pembaca.

Changelog monorepo: satu saja, atau satu per paket?

Mon, 07 Sep 2026 00:00:00 GMT

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.

Bentuk repo	Pembaca tipikal	Changelog yang cocok
Satu aplikasi yang di-deploy	Semua orang yang memakai produk	Satu log, untuk seluruh repo
Workspace pustaka (beberapa paket dipublikasikan)	Yang bergantung pada paket tertentu	Satu log per paket
Aplikasi ditambah alat internal	Dua audiens berbeda tanpa tumpang tindih	Dibagi berdasarkan audiens, bukan folder
Aplikasi ditambah SDK sendiri	Pengguna produk, dan integrator SDK	Dua log: khusus produk, khusus SDK

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.

Cara mengumumkan fitur baru (tanpa keheningan)

Mon, 07 Sep 2026 00:00:00 GMT

Kebanyakan pengumuman fitur mati di kanal yang tak dibaca dua kali siapa pun: tweet yang lewat tergulir, email hari rilis yang terkubur di bawah dua belas lainnya yang diterima pelanggan minggu itu, pesan Slack di kanal yang dibisukan setengah tim berbulan-bulan lalu. Fiturnya sudah dirilis. Hampir tak ada yang akan memakainya yang tahu. Memperbaiki itu lebih berkaitan dengan memilih kanal yang tepat untuk pembaca yang tepat daripada menulis pengumuman yang lebih baik, dan menjangkau langsung orang yang secara eksplisit memintanya alih-alih mengandalkan mereka menyadari pesan umum.

Di mana sebenarnya fitur baru harus diumumkan?

Di lebih dari satu tempat, karena "semua orang membaca kanal yang sama" tak pernah benar. Entri changelog atau feed melayani pembaca yang mengecek sesuai jadwalnya sendiri dan menginginkan catatan permanen dan bertanggal. Notifikasi dalam aplikasi melayani pembaca yang sudah memakai produk dan akan memakai fitur itu hari ini jika tahu keberadaannya. Email melayani pembaca yang saat ini tak berada di produk tapi akan kembali untuk update yang tepat. Media sosial melayani jangkauan di luar pengguna yang ada, dengan hampir tanpa penargetan.

Kanal	Terbaik untuk	Kelemahan
Changelog / feed	Catatan permanen; pembaca yang mengecek sesuai jadwal sendiri	Pasif; tak berguna bagi yang tak pernah mengecek
Notifikasi dalam aplikasi	Pengguna yang sudah ada dan akan bertindak hari ini	Tak menjangkau siapa pun yang saat ini tak masuk
Email	Pengguna tak aktif yang akan kembali untuk ini	Mudah terkubur di bawah surel lain; butuh subjek yang sungguhan
Media sosial	Jangkauan di luar pengguna yang ada	Hampir tanpa penargetan; umur pendek

Tak satu pun dari keempatnya cukup sendirian. Changelog adalah satu-satunya dokumen yang seharusnya membawa setiap rilis apa pun ukurannya, karena itu catatan yang menjadi rujukan balik semua yang lain; tiga lainnya adalah amplifikasi yang ditambahkan di atasnya, dipilih sesuai seberapa besar fitur itu sebenarnya.

Apa yang harus dikatakan pengumuman lebih dulu?

Hasilnya, bukan mekanismenya. "Kami menambahkan lapisan cache ke endpoint laporan" menggambarkan apa yang dibangun tim. "Laporan sekarang dimuat dalam kurang dari satu detik" menggambarkan apa yang berubah bagi pembaca, dan itulah kalimat yang mendapatkan klik, karena menjawab "apa untungnya bagi saya" di klausa pertama alih-alih ketiga. Mekanismenya milik entri changelog atau halaman detail, bukan judul.

Hal konkret sebelum kata sifat. "Pengalaman laporan yang lebih cepat dan lebih kuat" tak memberitahu pembaca apa pun yang bisa ditindaklanjuti; "laporan sekarang dimuat dalam kurang dari satu detik dan bisa difilter berdasarkan status" memberitahu persis apa yang berubah dan apa yang harus dicoba. Versi kedua juga terasa lebih kredibel, karena klaim yang samar terdengar persis seperti bunyi teks pemasaran ketika tak ada yang konkret untuk dikatakan.

Apa bedanya dengan email update produk?

Tumpang tindih tapi tak identik. Email update produk membahas kanal email secara spesifik, termasuk kadensi, subjek, dan kapan digest mengalahkan kiriman tunggal. Pengumuman fitur baru adalah peristiwa yang mendasarinya; email adalah salah satu dari empat kanal di atas yang bisa membawanya, dipilih ketika fitur cukup besar untuk membenarkan kiriman khusus alih-alih ikut naik di digest berikutnya. Fitur kecil pantas mendapat entri changelog dan mungkin notifikasi dalam aplikasi. Yang signifikan pantas mendapat keempat kanal, diselaraskan waktunya.

Bagaimana menjangkau orang spesifik yang memintanya?

Ini pengumuman dengan imbal hasil terbaik, dan hampir semua tim melewatkannya. Jika sepuluh pelanggan meminta fitur dengan nama, sepuluh orang itu pantas mendapat catatan langsung dan personal saat dirilis, terlepas dari pengumuman lebih luas apa pun yang keluar. Menutup lingkaran umpan balik dengan pelanggan membahas mekanismenya secara lengkap; ringkasannya di sini adalah ini hanya berfungsi jika permintaan asli tetap terhubung dengan yang memintanya, yang lebih merupakan masalah pelacakan daripada masalah pengumuman. Di changeloop, ketika masukan widget menjadi issue GitHub dan pull request yang di-merge menutupnya (fixes #142), menyetujui entri changelog memposting komentar "Shipped — " di issue itu, satu kali, yang tertaut kembali ke entri yang aktif, dan orang yang mengirim masukan melihat entri yang dirilis di widget. Tidak ada yang perlu ingat untuk memberi tahu mereka. Issue yang dibuat manual, serta repositori GitLab atau Bitbucket, tidak mendapat komentar itu.</p> <h2>Bagaimana menulis entri itu sendiri?</h2> <p>Disiplin yang sama seperti entri catatan rilis lainnya: mulai dengan apa yang bisa dilakukan pembaca sekarang, lanjutkan dengan pengaturan yang diperlukan, lewati justifikasi internal. <a href="https://changeloop.dev/blog/id/how-to-write-release-notes/">Cara menulis catatan rilis</a> membahas metode lengkapnya; pengumuman fitur baru adalah kasus dengan taruhan tertinggi, karena itu entri yang paling mungkin ditangkap layar, diteruskan, dan dibaca seseorang yang belum pernah melihat changelog produk.</p> <h2>Kapan sebaiknya tak mengumumkan secara luas?</h2> <p>Ketika fitur masih diluncurkan ke sebagian akun, benar-benar beta, atau berharga atau terkunci sedemikian rupa sehingga sembilan dari sepuluh pembaca pengumuman luas belum bisa memakainya. Pengumuman luas untuk fitur yang tak bisa dipakai sembilan dari sepuluh pembaca terbaca seperti umpan, dan membakar kepercayaan pada pengumuman berikutnya lebih daripada membangun antusiasme pada yang ini. Solusinya bukan keheningan, tapi cakupan: beri tahu akun yang memenuhi syarat secara langsung, dan tahan kanal luas sampai ketersediaan menyusul pengumuman.</p> <h2>FAQ</h2> <p><strong>Apakah setiap fitur baru pantas mendapat pengumumannya sendiri?</strong> Setiap fitur pantas mendapat entri changelog. Hanya yang cukup signifikan untuk mengubah cara seseorang memakai produk, atau yang diminta secara eksplisit dengan nama, yang pantas mendapat kanal lebih luas seperti email atau media sosial.</p> <p><strong>Apa kanal terbaik untuk fitur kecil?</strong> Changelog saja, ditambah notifikasi dalam aplikasi jika fitur bisa ditemukan dalam alur yang sudah dijalani pengguna. Email dan media sosial layak dipakai untuk fitur yang membenarkan permintaan perhatian.</p> <p><strong>Bagaimana mengumumkan fitur kepada orang yang secara spesifik memintanya?</strong> Jaga permintaan tetap terhubung dengan yang memintanya sejak saat dicatat, lalu beri tahu secara individu saat dirilis, terpisah dari pengumuman lebih luas apa pun. Label status bersama yang bisa dicek sendiri oleh yang meminta juga mengurangi berapa banyak pesan individu yang dibutuhkan sejak awal.</p> <p><strong>Apakah pengumuman fitur butuh tangkapan layar?</strong> Untuk apa pun yang visual, ya; fitur yang dijelaskan tapi tak terlihat jauh lebih sering dilewatkan daripada yang pembaca bisa lihat pratinjaunya. Untuk API atau kapabilitas backend, contoh kode singkat melakukan pekerjaan yang sama seperti tangkapan layar untuk perubahan UI.</p> </article> <article> <h1>Memprioritaskan permintaan fitur yang menumpuk</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Melacak permintaan fitur menyelesaikan soal di mana mereka hidup. Itu tidak menyelesaikan mana yang jalan lebih dulu, dan pertanyaan kedua itulah yang benar-benar membuat tim tersendat. Backlog tiga ratus permintaan, yang sudah dikelompokkan dan dilabeli, tetap butuh aturan keputusan, karena "bangun yang paling banyak diminta" hanya berhasil sampai dua permintaan berdekatan dan yang ketiga punya pendukung yang paling ribut, yang terjadi hampir setiap minggu. Kerangka di bawah ini bukan jawaban yang saling bersaing untuk pertanyaan yang sama. Masing-masing cocok untuk jenis permintaan berbeda, dan memakai satu saja untuk semuanya biasanya adalah kesalahan sebenarnya.</p> <h2>Apa yang membuat memprioritaskan permintaan fitur berbeda dari memprioritaskan roadmap?</h2> <p>Keputusan roadmap dimulai dari strategi dan bertanya apa yang harus dibangun. Keputusan permintaan fitur dimulai dari permintaan yang sudah ada dan bertanya apakah perlu ditindaklanjuti, dan keduanya cukup sering menarik ke arah berbeda sehingga sebuah permintaan bisa punya permintaan tinggi dan tetap salah untuk dibangun, atau punya permintaan rendah dan tetap layak karena membuka akun strategis. Memperlakukan setiap permintaan sebagai suara roadmap melewatkan pemeriksaan itu.</p> <table> <thead> <tr> <th>Kerangka</th> <th>Yang ditimbang</th> <th>Di mana gagal</th> </tr> </thead> <tbody><tr> <td>Hitungan permintaan mentah</td> <td>Berapa banyak yang meminta</td> <td>Menghargai nama yang mudah diingat, bukan permintaan nyata</td> </tr> <tr> <td>RICE</td> <td>Jangkauan, dampak, keyakinan, upaya</td> <td>Butuh estimasi yang tidak dimiliki siapa pun untuk permintaan baru</td> </tr> <tr> <td>Ditimbang pendapatan</td> <td>Siapa yang meminta, menurut nilai akun</td> <td>Mengabaikan permintaan dari akun yang belum bernilai besar</td> </tr> <tr> <td>Suara publik</td> <td>Sinyal terlihat, upaya rendah</td> <td>Hanya menjangkau pengguna yang sudah tahu ke mana harus melihat</td> </tr> </tbody></table> <h2>Apa itu RICE, dan apakah berhasil untuk permintaan fitur?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> menilai sebuah ide berdasarkan jangkauan, dampak, keyakinan, dan upaya, lalu membagi tiga yang pertama dengan yang keempat untuk mendapatkan angka yang bisa dibandingkan. Ini dibuat untuk ide roadmap yang sudah dipercaya tim, di mana bagian sulitnya adalah membandingkan taruhan yang berbeda satu sama lain. Permintaan fitur sudah datang dengan angka jangkauan, hitungan orang yang meminta, yang lebih konkret daripada jangkauan yang biasanya dimiliki ide roadmap yang baru. Di mana RICE menjadi tegang dengan sebuah permintaan adalah keyakinan dan dampak: tim bisa yakin sebuah permintaan itu nyata dan tetap tidak punya dasar seberapa besar itu akan menggerakkan metrik, karena "dampak" untuk permintaan yang sudah punya nama dan jejak pengguna nyata adalah jenis estimasi yang berbeda dari dampak untuk ide yang belum pernah dilihat siapa pun di luar ruangan.</p> <p>Gunakan RICE untuk permintaan yang benar-benar dipertimbangkan dan belum diputuskan. Jangan terapkan pada setiap permintaan yang masuk; upaya penilaian hanya sepadan untuk yang cukup dekat sehingga butuh pemecah seri.</p> <h2>Haruskah ditimbang berdasarkan pendapatan, atau berdasarkan siapa yang meminta?</h2> <p>Berdasarkan siapa yang meminta, tapi tidak hanya pendapatan. Akun yang mendekati perpanjangan, akun yang sudah pernah eskalasi, dan akun yang permintaannya membuka kesepakatan yang sedang berjalan membawa urgensi yang tidak ditangkap angka pendapatan datar saja, dan permintaan dari pendaftaran uji coba tetap bisa penting jika itu memblokir keputusan yang segera menjadi pendapatan. Penimbangan pendapatan adalah yang paling mudah dihitung dari semua ini, dan justru karena itu paling mudah dipercaya berlebihan: ia dengan tepat menghilangkan bising dari akun tanpa taruhan nyata, dan dengan mudah pula bisa menurunkan peringkat permintaan yang akan membawa akun jauh lebih besar yang masih ada di pipeline.</p> <h2>Peran apa yang sebenarnya dimainkan suara?</h2> <p>Sinyal murah dan berkelanjutan untuk permintaan yang sudah ada, dan cara yang buruk untuk menemukan permintaan mana yang seharusnya ada sejak awal. Hitungan suara hanya menjangkau pengguna yang sudah menemukan permintaan itu dan menganggapnya layak diklik, yang berarti total suara roadmap publik mencerminkan visibilitas sama besarnya dengan permintaan: permintaan lama di dekat puncak daftar terus mengumpulkan suara sebagian karena mudah ditemukan, dan permintaan yang lebih baru dan sama nyatanya mulai dari nol. Artikel <a href="https://changeloop.dev/blog/id/public-roadmap/">roadmap publik</a> berpendapat sebaiknya suara sama sekali tidak ditampilkan di roadmap. Perlakukan suara sebagai sinyal yang perlu dikelompokkan dan ditimbang berdasarkan kebaruan, bukan sebagai peringkat yang dibangun berurutan. <a href="https://changeloop.dev/blog/id/feedback-signal-quality/">Tiket dukungan vs. permintaan fitur</a> membahas titik buta lain dalam jumlah suara: kesenjangan nyata bisa menghasilkan hampir tidak ada suara jika pengguna yang mengalaminya tidak pernah menemukan papannya, sementara tetap muncul dengan ribut di dukungan.</p> <h2>Kapan pelanggan paling ribut menang, dan apakah itu masalah?</h2> <p>Kadang-kadang, dan itu masalah hanya kalau tidak ada yang menyadarinya. Pelanggan yang sering eskalasi, menulis tiket rinci, atau punya jalur langsung ke seseorang di tim akan melihat permintaannya diperiksa lebih cepat daripada pelanggan yang lebih pendiam dengan permintaan yang sama validnya, dan proses prioritisasi yang tidak pernah memeriksanya akan secara sistematis mengutamakan yang paling gigih, bukan yang punya kasus paling kuat. Pelanggan yang ribut bukan masalah yang harus diperbaiki; permintaan mereka sering kali benar-benar penting. Perbaikannya adalah kebiasaan: tinjau backlog berdasarkan sumber secara berkala dan periksa apakah segelintir akun yang sama menjelaskan sebagian besar yang baru dirilis, dan tanyakan apakah itu sesuai dengan di mana permintaan nyata sebenarnya berada.</p> <h2>Bagaimana keputusan prioritisasi berubah menjadi balasan?</h2> <p>Setiap keputusan di sini menghasilkan pemenang dan pecundang, dan keduanya pantas mendapat balasan yang menyebutkan alasan sebenarnya, bukan sekadar perubahan status tanpa penjelasan. <a href="https://changeloop.dev/blog/id/declining-feature-requests/">Cara menolak permintaan fitur</a> membahas apa yang harus dikatakan pada permintaan yang kalah, dengan cara yang menjaga hubungan tetap utuh alih-alih terdengar seperti penolakan generik. Kerja pengelompokan dan pelabelan yang membuat semua ini mungkin dibahas di <a href="https://changeloop.dev/blog/id/feature-request-tracking/">melacak permintaan fitur</a>; prioritisasi hanya berhasil pada permintaan yang sudah tercatat dan dikelompokkan cukup baik untuk dibandingkan.</p> <h2>FAQ</h2> <p><strong>Apa kerangka terbaik untuk memprioritaskan permintaan fitur?</strong> Tidak ada yang berdiri sendiri. Gunakan hitungan mentah untuk menemukan sinyal paling ribut, RICE untuk membandingkan daftar pendek kandidat serius, dan pemeriksaan pendapatan atau akun untuk menangkap kasus di mana permintaan diam dari akun strategis lebih berat daripada kelompok yang lebih ribut tapi kurang penting.</p> <p><strong>Haruskah permintaan fitur diprioritaskan sama seperti ide roadmap?</strong> Tidak. Ide roadmap dimulai dari strategi; permintaan fitur dimulai dari permintaan yang sudah ada. Menilai keduanya bersamaan membuat taruhan strategis yang beralasan baik tapi punya sedikit permintaan yang ada terus-menerus kalah melawan permintaan yang sekadar punya lebih banyak orang yang memintanya.</p> <p><strong>Apakah suara pada roadmap publik mencerminkan permintaan secara akurat?</strong> Hanya di antara orang yang sudah menemukan permintaan itu. Permintaan yang lebih lama dan lebih terlihat mengumpulkan suara lebih cepat, terlepas dari seberapa besar permintaan nyata di balik yang lebih baru, jadi perlakukan total suara sebagai sinyal, dikelompokkan dan ditimbang berdasarkan kebaruan, bukan sebagai peringkat yang dibangun berurutan.</p> <p><strong>Seberapa sering prioritas permintaan fitur harus dievaluasi ulang?</strong> Dalam siklus tetap, bukan hanya saat seseorang eskalasi. Peninjauan bulanan atau triwulanan yang mengelompokkan ulang permintaan dan memeriksa ulang penimbangan menangkap pergeseran, seperti segelintir akun yang mendominasi apa yang dirilis, yang tidak pernah muncul sendiri dari proses yang murni reaktif.</p> </article> <article> <h1>Release notes enterprise: apa yang berubah untuk satu akun</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Produk SaaS publik mengirim release notes yang sama ke semua orang, karena semua orang berada di versi yang sama. Pelanggan enterprise pada versi yang dipasang tetap, instans khusus, atau subset produk dengan feature flag mematahkan asumsi itu: release notes yang menjelaskan apa yang berubah untuknya tidak sama dengan yang ada di blog publik Anda, dan tetap mengirim yang publik akan membingungkan pelanggan itu dengan perubahan yang belum dia miliki, atau, lebih buruk, memberi tahu dia tentang fitur yang secara khusus diminta tim akun pelanggan enterprise lain untuk ditahan dari milik mereka selama sebulan lagi. <a href="https://changeloop.dev/blog/id/release-notes-best-practices/">Praktik terbaik release notes</a> membahas kerajinan umumnya; ini tentang menulis release notes enterprise untuk masalah penyesuaian yang muncul begitu Anda punya pelanggan yang tidak semuanya berada di build yang sama.</p> <h2>Mengapa pelanggan enterprise tidak bisa cukup membaca changelog publik?</h2> <p>Karena itu menjelaskan versi yang mungkin belum dia jalankan, fitur yang mungkin tidak dia akses, dan jadwal yang tidak cocok dengan miliknya. Pelanggan yang terpaku pada siklus rilis kuartalan yang membaca tentang fitur yang keluar untuk tingkat publik minggu lalu tidak punya cara untuk tahu, hanya dari changelog publik, apakah fitur itu akan sampai padanya minggu depan atau kuartal depan. Changelog publik menjawab "apa yang berubah di produk"; pertanyaan sebenarnya pelanggan enterprise adalah "apa yang berubah di versi yang saya jalankan, dan kapan saya dapat sisanya", yang tidak pernah ditulis oleh changelog publik untuk dijawab.</p> <h2>Apa yang dibutuhkan release note privat yang tidak dibutuhkan yang publik?</h2> <p>Pengidentifikasi versi atau lingkungan yang bisa benar-benar diperiksa pelanggan, dan pernyataan eksplisit tentang apa yang belum sampai padanya. "Rilis ini mencakup peningkatan ekspor massal dari rilis publik 4.3 kami, tapi bukan model izin baru, yang akan datang di pembaruan terjadwal berikutnya Anda" memberi tahu admin enterprise persis di mana posisi instansnya relatif terhadap produk secara keseluruhan. Release note publik tidak pernah butuh kerangka ini karena hanya ada satu instans untuk dijadikan acuan relatif; yang privat tidak berarti tanpa itu.</p> <table> <thead> <tr> <th>Release notes publik</th> <th>Release notes privat (enterprise)</th> </tr> </thead> <tbody><tr> <td>Satu versi, satu audiens</td> <td>Banyak versi, audiens tersegmentasi</td> </tr> <tr> <td>Mengasumsikan pembaca punya setiap fitur yang dijelaskan</td> <td>Harus menyatakan apa yang dimiliki dan tidak dimiliki pembaca</td> </tr> <tr> <td>Dijadwalkan sesuai rilis publik</td> <td>Dijadwalkan sesuai jendela pembaruan pelanggan sendiri</td> </tr> <tr> <td>Bisa langsung dibuat sepenuhnya publik</td> <td>Mungkin perlu menahan item yang belum dimiliki pelanggan lain</td> </tr> </tbody></table> <h2>Apakah pernah baik-baik saja untuk hanya menunda pengiriman release notes publik ke pelanggan enterprise alih-alih menulis yang terpisah?</h2> <p>Hanya jika versi mereka benar-benar cocok dengan yang publik pada saat itu, yang lebih jarang daripada kedengarannya begitu Anda punya lebih dari beberapa akun enterprise dengan ritme berbeda. Menunda catatan publik berfungsi sebagai solusi sementara untuk pelanggan yang tertinggal satu versi dan hampir mengejar; itu runtuh pada saat dua pelanggan enterprise berada di versi berbeda satu sama lain, karena saat itu tidak ada lagi satu "catatan" tunggal untuk ditunda, hanya matriks apa yang dimiliki masing-masing. Pada titik itu, menyesuaikan catatan per akun, bahkan jika hanya tampilan terfilter dari entri yang sama, berhenti menjadi opsional.</p> <pre><code>Catatan publik, dikirim ke akun enterprise yang belum punya fiturnya: "New: Bulk export now supports custom column ordering." (Membingungkan: adminnya mencoba dan fiturnya tidak ada.) Catatan enterprise yang disesuaikan untuk akun yang sama: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Siapa di dalam organisasi pelanggan yang benar-benar membacanya, dan apakah itu mengubah cara penulisan?</h2> <p>Biasanya admin TI atau kontak customer success alih-alih pengguna akhir, dan itu mengubah apa yang dianggap berguna. Pengguna akhir ingin tahu apa yang terlihat berbeda di layarnya; admin enterprise ingin tahu apa yang berubah dalam izin, penanganan data, konfigurasi SSO, atau apa pun yang memengaruhi cara dia mengelola penerapan untuk penggunanya sendiri, karena dialah yang akan menjawab pertanyaan internal. Release note privat yang terbaca seperti changelog konsumen, semua tombol baru yang berkilau dan tanpa detail operasional, memaksa admin untuk menggali informasi yang sebenarnya dia butuhkan.</p> <h2>Bagaimana ini berinteraksi dengan roadmap publik atau changelog publik yang sudah mencantumkan fitur yang sama?</h2> <p>Dengan hati-hati, karena pelanggan yang membaca keduanya akan memperhatikan ketidakkonsistenan apa pun. Jika changelog publik Anda sudah mengumumkan fitur yang belum dimiliki akun enterprise tertentu, release note privatnya perlu mengakui kesenjangan itu alih-alih berpura-pura entri publiknya tidak ada; admin yang sudah melihat pengumuman publik dan mendapat catatan privat yang mengabaikannya akan mengasumsikan bahwa Anda melupakannya, atau ada yang rusak. <a href="https://changeloop.dev/blog/id/public-roadmap/">Roadmap publik</a> membahas cara menjaga roadmap tetap jujur tentang apa yang sudah dirilis versus direncanakan; versi enterprise dari kejujuran itu di release notes adalah menyebutkan langsung kesenjangan antara apa yang publik dan apa yang menjadi miliknya.</p> <h2>Apakah perusahaan kecil dengan hanya satu atau dua pelanggan enterprise butuh struktur sebanyak ini?</h2> <p>Bukan sistem yang tersegmentasi penuh, tapi disiplin intinya, menyatakan dengan jelas versi apa yang dijalankan pelanggan dan apa yang dimiliki dan tidak dimilikinya, penting pada skala berapa pun begitu Anda punya bahkan satu pelanggan yang tidak berada di build terbaru Anda. Mode kegagalan yang dicegah ini, admin yang bingung apakah pengumuman publik berlaku untuknya, menghabiskan biaya satu tiket dukungan dan pukulan kepercayaan terlepas apakah Anda punya dua akun enterprise atau dua ratus.</p> <h2>FAQ</h2> <p><strong>Haruskah release notes privat pernah menyebutkan fitur yang sudah dimiliki pelanggan lain tapi ini belum?</strong> Hanya jika relevan dengan jadwalnya sendiri, diungkapkan sebagai "akan datang di pembaruan berikutnya Anda" alih-alih sebagai perbandingan dengan pelanggan lain. Menyebutkan apa yang dimiliki pelanggan lain tertentu melintasi wilayah yang bukan hak Anda untuk diungkapkan; menyebutkan apa yang akan datang khusus untuk pelanggan ini adalah persis informasi yang dia butuhkan.</p> <p><strong>Bisakah entri changelog yang sama mendukung release notes publik dan privat sekaligus?</strong> Bisa, dan itu biasanya pendekatan yang lebih mudah dipelihara: beri label entri dengan versi atau tingkatan mana yang berlaku, lalu filter per audiens saat penerbitan alih-alih menulis dua dokumen yang sepenuhnya terpisah yang pasti akan menyimpang seiring waktu.</p> <p><strong>Bagaimana jika pelanggan enterprise secara eksplisit meminta berada di release notes publik alih-alih feed privat?</strong> Hormati, tapi konfirmasi dia paham bahwa catatan publik mengasumsikan versi publik, dan tandai sendiri kesenjangannya secara tertulis jika versinya berbeda dari yang dijelaskan. Konfirmasi tertulis itulah yang melindungi Anda nanti jika dia bertindak berdasarkan catatan publik yang sebenarnya tidak berlaku untuk build-nya.</p> <p><strong>Berapa jauh sebelumnya pelanggan enterprise harus diberi tahu tentang fitur yang akan diaksesnya di rilis berikutnya?</strong> Segera setelah tanggalnya dikonfirmasi, bukan hanya pada saat rilis, karena admin enterprise sering perlu merencanakan komunikasi internal atau pelatihan mereka sendiri seputar fitur yang akan datang, dan pemberitahuan di hari yang sama tidak memberi mereka ruang untuk itu.</p> </article> <article> <h1>Semantic versioning dan changelog Anda</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Semantic versioning memberi tahu pemanggil seberapa sakit sebuah rilis bisa dirasakannya sebelum membaca satu entri changelog pun. Naik dari <code>2.4.1</code> ke <code>2.5.0</code> berarti: kapabilitas baru, tak ada yang rusak. Naik dari <code>2.5.0</code> ke <code>3.0.0</code> berarti: baca entri ini sebelum update. Changelog dan nomor versi seharusnya menyatakan hal yang sama dalam dua format, dan sebagian besar friksi antara keduanya muncul justru saat keduanya tak sepakat, yang lebih sering terjadi dari yang disarankan spesifikasinya.</p> <h2>Apa sebenarnya yang dijanjikan tiap angka dalam sebuah versi?</h2> <p><a href="https://semver.org/">Semantic versioning</a> mendefinisikan tiga angka, <code>MAJOR.MINOR.PATCH</code>, masing-masing dengan aturan ketat tentang apa yang memicunya. Lompatan MAJOR berarti perubahan yang tak kompatibel: sesuatu yang bisa disadari integrasi yang benar dan sudah ada, dan karenanya harus berubah. Lompatan MINOR berarti fungsionalitas baru yang kompatibel ke belakang: tak ada yang lama rusak, sesuatu yang baru tersedia. Lompatan PATCH berarti perbaikan yang kompatibel ke belakang: perilaku menjadi lebih dekat dengan yang didokumentasikan, dan siapa pun yang sengaja bergantung pada perilaku lama seharusnya tak menyadari apa pun.</p> <table> <thead> <tr> <th>Lompatan</th> <th>Arti</th> <th>Entri seharusnya terbaca seperti</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Perubahan tak kompatibel</td> <td>"Perlu tindakan sebelum update"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Kapabilitas baru yang kompatibel</td> <td>"Tersedia sekarang, tak ada lagi yang berubah"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Perbaikan yang kompatibel</td> <td>"Sekarang berperilaku sesuai dokumentasi"</td> </tr> </tbody></table> <p>Tabel ini juga uji terbalik: jika sebuah entri tak terbaca seperti barisnya, entah nomor versinya salah, atau entri itu terlalu kecil atau terlalu besar dalam menjual apa yang sebenarnya terjadi.</p> <h2>Apa yang dihitung sebagai tak kompatibel untuk tujuan versioning?</h2> <p>Uji yang sama yang menentukan apakah sesuatu termasuk dalam changelog API: apakah pemanggil yang benar, ditulis melawan perilaku lama dan tak tersentuh sejak itu, bisa berperilaku berbeda karena perubahan ini. <a href="https://changeloop.dev/blog/id/breaking-changes/">Apa itu perubahan tak kompatibel, dan cara merilisnya</a> membahas keputusan itu secara lengkap, termasuk kasus yang terlihat tak kompatibel padahal bukan, dan yang terlihat kecil padahal bukan. Singkatnya untuk tujuan versioning: jika jawabannya ya, lompatannya MAJOR terlepas dari berapa banyak kode yang sebenarnya disentuh perubahan itu secara internal. Nomor versi mengikuti konsekuensi bagi pemanggil, bukan usaha tim.</p> <h2>Bagaimana seharusnya entri changelog cocok dengan lompatan versi?</h2> <p>Satu entri, satu kategori lompatan, dinyatakan sejak awal. Pola dari tabel berlanjut langsung: entri tak kompatibel berada di bawah versi yang memperkenalkannya, diformulasikan dulu sebagai peringatan lalu sebagai deskripsi. Entri aditif berada di bawah versi MINOR-nya, diformulasikan sebagai ketersediaan. Perbaikan berada di bawah versi PATCH-nya, diformulasikan sebagai koreksi. Mencampur kategori dalam satu entri, seperti melipat perubahan tak kompatibel ke paragraf yang sama dengan perbaikan yang tak berhubungan, adalah cara pembaca melewatkan justru satu hal yang paling penting.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` sekarang mengembalikan jumlah sebagai integer dalam satuan mata uang terkecil (sen) alih-alih desimal. Perbarui kode yang membaca `amount` secara langsung. ## 2.9.0 (2026-09-01) ### Added - Laporan sekarang bisa difilter berdasarkan `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` mengembalikan halaman kosong alih-alih 400 untuk status yang tidak dikenal. </code></pre> <p>Dibaca dari atas ke bawah, nomor versi dan label bagian mengatakan hal yang sama dua kali, dan itulah tujuannya: pembaca yang hanya memindai judul mendapat pembacaan risiko yang benar sebelum membuka satu baris pun.</p> <h2>Apakah aturan breaking change berlaku sama sebelum 1.0.0?</h2> <p>Tidak, dan di sinilah sebagian besar kebingungan tentang "apakah itu sungguh breaking" berasal. SemVer eksplisit menyatakan versi mayor nol, <code>0.y.z</code>, untuk pengembangan awal: apa pun bisa berubah kapan saja, dan API publik tidak boleh dianggap stabil. Lompatan <code>0.4.0</code> ke <code>0.5.0</code> bisa membawa breaking change tanpa melanggar spec, karena jaminan versi mayor baru berlaku begitu proyek merilis <code>1.0.0</code>. Entri changelog tetap berutang kejujuran yang sama tentang apa yang rusak; yang berubah hanyalah nomor versi itu sendiri bukan sinyal yang bisa diandalkan sebelum 1.0.0 tiba.</p> <h2>Bagaimana jika produk Anda tak merilis versi diskrit?</h2> <p>Kebanyakan produk SaaS melakukan deploy berkelanjutan dan tak pernah menampilkan nomor versi ke pemanggil, yang tak menghilangkan kebutuhan akan disiplin ini, hanya angka yang biasanya membawanya. Entri changelog harus melakukan semua pekerjaan sendiri: menyatakan dengan jelas apakah perubahan itu tak kompatibel, aditif, atau perbaikan, dengan tiga kata yang sama yang dipakai semantic versioning, bahkan tanpa kolom versi untuk menempelkannya. Beberapa tim menjaga versi yang murni internal hanya untuk menjangkarkan entri changelog ke sesuatu yang bisa ditautkan, tanpa pernah menunjukkannya langsung ke pemanggil.</p> <h2>Bagaimana ini berlaku khusus untuk changelog API?</h2> <p>Lebih ketat daripada hampir di mana pun, karena pemanggil API adalah kode, bukan orang yang bisa mengangkat bahu menghadapi perubahan tak terduga. <a href="https://changeloop.dev/blog/id/api-changelog/">Changelog API: apa yang dipublikasikan dan siapa yang membacanya</a> membahas bentuk lengkap dokumen itu; disiplin versioning di sini adalah yang menjaga kejujuran bagian breaking dan aditifnya. API yang menawarkan beberapa versi sekaligus, seperti <code>v1</code> dan <code>v2</code> disajikan bersamaan selama jendela migrasi, secara efektif menerapkan semantic versioning pada skala seluruh antarmuka alih-alih satu paket, dan kosakata tiga kata yang sama masih berlaku untuk setiap entri.</p> <h2>Apa yang dikatakan Keep a Changelog tentang versioning?</h2> <p>Ia terhubung langsung dengan nama ke semantic versioning dan merekomendasikan kosakata kategori yang sama yang dipakai artikel ini: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/id/keep-a-changelog-implemented/">Keep a Changelog, dalam praktik</a> membahas cara mengadopsi spesifikasi itu, termasuk di mana tim biasanya menyimpang. Tumpang tindihnya bukan kebetulan: kedua spesifikasi mencoba memecahkan masalah yang sama dari ujung yang berlawanan, satu menstandarkan nomor versi dan yang lain entri yang menjelaskannya.</p> <h2>FAQ</h2> <p><strong>Apakah setiap entri changelog butuh nomor versi?</strong> Jika produk merilis versi, ya, karena angka itu memungkinkan pembaca langsung melompat ke "seberapa ini memengaruhi saya" tanpa membaca entrinya dulu. Jika produk deploy berkelanjutan tanpa kolom versi, formulasi entri harus membawa sinyal itu sendiri.</p> <p><strong>Apa bedanya lompatan MAJOR dengan entri perubahan tak kompatibel?</strong> Keduanya seharusnya peristiwa yang sama dijelaskan dengan dua cara. Nomor versi adalah sinyal yang bisa dibaca mesin (tooling pemanggil bisa bereaksi terhadapnya); entri changelog adalah penjelasan yang bisa dibaca manusia tentang apa yang berubah secara konkret.</p> <p><strong>Bisakah rilis PATCH bersifat tak kompatibel?</strong> Secara definisi seharusnya tidak. Jika ternyata tetap dirilis, jangan edit atau beri tag ulang versi yang sudah dipublikasikan: <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">SemVer FAQ</a> menyarankan merilis versi baru yang memulihkan kompatibilitas, atau MAJOR baru jika kerusakannya tetap ada, dan mendokumentasikan versi bermasalah itu agar pengguna tahu harus melewatinya.</p> <p><strong>Apakah perubahan yang murni internal butuh lompatan versi?</strong> Tidak. Semantic versioning mengikuti antarmuka publik. Refactor tanpa efek yang bisa diamati bagi pemanggil tak butuh lompatan atau entri changelog, meskipun secara internal itu pekerjaan engineering yang signifikan.</p> </article> <article> <h1>Changelog webhook: breaking change yang tak diminta</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Changelog API REST ada karena pemanggil bisa memilih menolak response yang tidak dia mengerti, atau setidaknya mencatat error cukup keras hingga seseorang menyadarinya. Penerima webhook jarang melakukan salah satu dari itu. Dia menerima POST, membaca field yang diharapkan, dan jika sebuah field pindah, berubah tipe, atau hilang, endpoint itu diam-diam crash di dalam job latar belakang yang tidak diawasi siapa pun atau, lebih buruk, terus berjalan dengan nilai salah yang tidak pernah divalidasinya. <a href="https://changeloop.dev/blog/id/breaking-changes/">Apa itu breaking change</a> membahas definisi umum; payload webhook butuh jawabannya sendiri, karena mode kegagalannya berbeda dari endpoint yang sengaja dipanggil seseorang.</p> <h2>Mengapa perubahan payload webhook rusak berbeda dari perubahan response API?</h2> <p>Karena arah requestnya terbalik. Pemanggil REST memulai panggilan dan bisa menambahkan header versi, mencoba lagi saat 4xx, atau membaca pemberitahuan deprecation di response. Penerima webhook tidak memulai satu pun dari itu: server Anda yang memutuskan mengirim, memutuskan kapan, dan memutuskan bentuk apa yang akan dimiliki body itu. Satu-satunya pengungkit penerima adalah validasi yang ditulisnya saat integrasi dibangun, dan sebagian besar integrasi dibangun sekali, berfungsi, dan tidak pernah ditinjau ulang sampai rusak. Asimetri itulah seluruh alasan mengapa perubahan payload webhook layak mendapat lebih banyak kehati-hatian daripada perubahan yang sama pada body response yang secara aktif diminta pemanggil.</p> <h2>Apa yang sebenarnya dihitung sebagai breaking change dalam payload webhook?</h2> <table> <thead> <tr> <th>Perubahan</th> <th>Breaking bagi kebanyakan penerima</th> </tr> </thead> <tbody><tr> <td>Menambah field baru</td> <td>Tidak, jika penerima mengabaikan field yang tidak dikenal (verifikasi asumsi ini, jangan anggap begitu saja)</td> </tr> <tr> <td>Menghapus field</td> <td>Ya, jika ada yang membacanya</td> </tr> <tr> <td>Mengganti nama field</td> <td>Ya, secara fungsional identik dengan menghapus yang lama</td> </tr> <tr> <td>Mengubah tipe field (string ke object)</td> <td>Ya, hampir selalu</td> </tr> <tr> <td>Menyusun ulang field dalam body JSON</td> <td>Tidak, untuk penerima mana pun yang mengurai berdasarkan key, yang seharusnya semua</td> </tr> <tr> <td>Mengubah nama atau tipe event</td> <td>Ya, jika penerima memfilter atau merutekan berdasarkan itu</td> </tr> </tbody></table> <p>Baris "menambah field itu aman" adalah yang paling diandalkan tim dan yang paling layak diverifikasi, bukan diasumsikan. Parser JSON yang permisif mengabaikan field tidak dikenal secara default, tapi penerima yang deserialize ke skema ketat, beberapa bahasa bertipe melakukan ini tanpa konfigurasi tambahan, bisa menolak seluruh payload begitu field yang tak terduga muncul. Menambah field aman untuk webhook Anda hanya jika Anda tahu bagaimana penerima mengurai, bukan karena JSON sendiri permisif.</p> <h2>Bagaimana cara memberi versi pada payload webhook?</h2> <p>Mirip dengan response API, dengan satu perbedaan: penerima tidak pernah mengirim request, jadi tidak bisa meminta versi, dan pengirimlah yang harus menyatakannya. Versi itu bisa ada di body atau di header request pada pengiriman itu sendiri; <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">pengiriman GitHub</a> membawa <code>X-GitHub-Event</code> dan <code>X-GitHub-Hook-ID</code>, dan <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">spesifikasi Standard Webhooks</a> menaruh metadatanya di header <code>webhook-*</code>. Field versi dalam payload (<code>"payload_version": 2</code>) adalah opsi termurah dan berfungsi ketika penerima bersedia bercabang berdasarkan itu. Tipe event bervers (<code>invoice.updated</code> menjadi <code>invoice.updated.v2</code> sebagai event terpisah yang diikuti sukarela oleh penerima) butuh lebih banyak kerja untuk dibangun tapi berarti bentuk lama terus mengalir ke siapa pun yang tidak pernah migrasi, yang lebih penting di sini daripada di endpoint REST karena Anda tidak bisa menelepon setiap penerima untuk memintanya update. Pengaturan per langganan, dipilih saat pendaftaran endpoint webhook, memajukan keputusan alih-alih bercabang di setiap pengiriman, dan merupakan pilihan tepat saat Anda sudah punya catatan langganan untuk melampirkannya.</p> <pre><code>POST /endpoint-penerima { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Bagaimana Anda bahkan tahu siapa yang mendengarkan?</h2> <p>Lebih buruk dari versi setara masalah ini dalam changelog API, karena webhook tidak punya log request masuk di sisi Anda yang menyebutkan pemanggil; Anda hanya punya log pengiriman keluar Anda sendiri, yang memberi tahu bahwa endpoint menerima 200, bukan apa yang dilakukannya dengan body itu. Lacak setidaknya dua hal: setiap endpoint terdaftar dengan pemiliknya, disiplin yang sama yang direkomendasikan <a href="https://changeloop.dev/blog/id/internal-api-changelog/">changelog API internal</a> untuk konsumen internal, dan tingkat kegagalan pengiriman per endpoint Anda setelah perubahan payload. Lonjakan response 4xx atau 5xx dari sebuah endpoint tepat setelah perubahan adalah hal terdekat dengan stack trace yang akan Anda dapatkan, dan sering kali itu satu-satunya sinyal bahwa penerima rusak, karena tim yang mengoperasikannya mungkin tidak menyadarinya selama berhari-hari.</p> <h2>Haruskah changelog webhook terpisah dari changelog API?</h2> <p>Bagian terpisah di halaman yang sama, bukan publikasi terpisah. <a href="https://changeloop.dev/blog/id/api-changelog/">Changelog API</a> sudah menetapkan siapa yang membacanya dan bagaimana berlangganan; perubahan payload webhook termasuk dalam feed yang sama, dilabeli cukup jelas sehingga developer di sisi penerima yang memindai "apakah ini memengaruhi integrasi saya" bisa menyaringnya, karena konsumen webhook sering tidak punya alasan lain untuk memeriksa changelog API umum dan hanya akan menemukannya jika seseorang mengarahkannya langsung ke sana.</p> <h2>Seperti apa jendela deprecation yang wajar untuk payload webhook?</h2> <p>Lebih panjang dari deprecation REST yang setara, karena migrasi di sisi penerima biasanya berarti tim kedua, yang mungkin tidak Anda hubungi langsung, harus menyadarinya, menjadwalkannya, dan merilisnya tanpa urgensi sendiri. Satu bulan adalah batas bawah yang wajar untuk field yang mungkin masih diurai penerima dengan library yang permisif; tiga bulan atau lebih lebih aman untuk penghapusan field yang akan ditolak sepenuhnya oleh skema ketat. Kirim bentuk lama dan baru bersamaan selama jendela ketika memungkinkan (field lama <code>status</code> dan penggantinya di versi 2 dalam payload yang sama), karena penerima yang membaca field lama terus berfungsi tanpa menyentuh kodenya, dan yang sudah migrasi cukup mengabaikan field yang tidak dibutuhkannya lagi.</p> <h2>FAQ</h2> <p><strong>Apakah konsumen webhook perlu mengonfirmasi perubahan payload sebelum dirilis?</strong> Tidak ada mekanisme konfirmasi secara default, dan justru karena itu jendela deprecation lebih penting di sini daripada di API REST: tidak ada yang mengonfirmasi kesiapan, jadi jendelanya harus cukup panjang agar sebagian besar penerima migrasi dengan jadwal mereka sendiri sebelum bentuk lama menghilang.</p> <p><strong>Apakah pernah aman menambah field yang tidak dikenal tanpa pemberitahuan?</strong> Hanya setelah Anda memverifikasi, bukan mengasumsikan, bahwa penerima Anda mengurai secara permisif. Entri changelog murah dan menghilangkan tebak-tebakan; menambah field diam-diam dengan asumsi "parser JSON mengabaikan yang ekstra" merusak penerima mana pun dengan deserialisasi ketat.</p> <p><strong>Apa cara tercepat mendeteksi penerima webhook yang rusak setelah perubahan payload?</strong> Tingkat kegagalan pengiriman per endpoint, diamati dalam jam-jam segera setelah perubahan. Ini tidak akan memberi tahu apa yang rusak, hanya bahwa sesuatu rusak, tapi itu sinyal paling awal dan sering kali satu-satunya yang akan Anda dapatkan.</p> <p><strong>Apakah logika retry membantu penerima bertahan dari perubahan payload?</strong> Tidak. Retry mengirim ulang payload baru yang sama; ini tidak kembali ke bentuk yang bisa diurai penerima. Perubahan payload merusak penerima pada pengiriman pertama dan setiap retry berikutnya secara identik.</p> </article> <article> <h1>Header sunset API, dan kapan mengirimkannya</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> adalah satu header respons tunggal, didefinisikan dalam <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, yang memberi tahu pemanggil kapan sebuah resource akan berhenti merespons. <a href="https://changeloop.dev/blog/id/api-deprecation/">Deprecation API</a> membahas seluruh linimasa umumkan-ingatkan-brownout-pensiunkan beserta pemberitahuan yang menyertainya; ini tentang satu sinyal yang bisa dibaca mesin dalam linimasa itu, apa sebenarnya yang dikatakannya, dan satu kasus ketika RFC sendiri mengatakan untuk tidak mengirimkannya.</p> <h2>Apa yang dikatakan header Sunset, dan apa yang tidak dikatakannya?</h2> <p>Header ini membawa satu tanggal-HTTP, titik waktu ketika resource diperkirakan berhenti merespons:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>RFC menyebutnya sebagai petunjuk, bukan jaminan: header ini tidak menjanjikan resource akan tetap berfungsi persis sampai stempel waktu itu, dan tidak mengatakan apa pun tentang seperti apa kegagalannya nanti. Pemanggil bisa mendapat 4xx, redirect, atau tidak ada respons sama sekali; header tidak membedakannya. Stempel waktu yang sudah lewat berarti "sekarang, atau kapan saja" alih-alih kesalahan pada nilainya. Tidak satu pun dari ini dipaksakan oleh protokol. Klien yang tidak pernah membaca header ini berperilaku persis seperti biasanya, dan tetap mengetahui resource sudah hilang dengan cara yang sama seperti yang akan terjadi tanpa header ini.</p> <h2>Kapan sebenarnya Anda harus mengirimkannya?</h2> <p>Hanya setelah resource benar-benar akan berhenti merespons, bukan ketika ia sekadar tidak lagi jadi pilihan yang direkomendasikan. RFC secara eksplisit menyatakan deprecation terjadi dalam dua tahap, dan field header Sunset hanya berlaku untuk tahap kedua: API tetap beroperasi penuh selama tahap pertama, yaitu pengumuman bahwa suatu versi tidak lagi diutamakan, dan field header ini tidak berlaku di sana. Ia berlaku begitu versi tersebut benar-benar dijadwalkan berhenti merespons.</p> <p>Itu berpadanan langsung dengan linimasa deprecation: header <code>Deprecation</code> dikirim sejak hari pertama, pada langkah pengumuman; <code>Sunset</code> menjelaskan tanggal perilaku lama akan benar-benar berhenti, yaitu tanggal yang sama yang disebut <a href="https://changeloop.dev/blog/id/api-deprecation/">linimasa empat langkah</a> sebagai pensiun. Mengirim <code>Sunset</code> pada hari pertama tidak salah, karena tanggalnya sudah pasti saat itu, tapi mengirimkannya tanpa juga mengumumkan deprecation, atau menetapkannya untuk versi yang belum benar-benar Anda komit untuk dipensiunkan, memberi tahu pemanggil sesuatu yang belum Anda putuskan.</p> <h2>Apakah ini berinteraksi dengan caching?</h2> <p>Tidak, dan RFC mengatakannya secara langsung: <code>Sunset</code> dan HTTP caching menyelesaikan masalah yang tidak berhubungan dan harus dibaca sebagai saling melengkapi, bukan tumpang tindih. Header caching mengatakan kapan salinan cache aman digunakan ulang; <code>Sunset</code> tidak mengatakan apa pun tentang keadaan resource saat ini, hanya bahwa resource itu sendiri akan berhenti ada. Sebuah respons bisa sepenuhnya bisa di-cache sampai persis saat ia sunset. Jangan gunakan salah satu untuk mendekati yang lain, dan jangan asumsikan <code>max-age</code> yang panjang meniadakan tanggal sunset yang mendekat, atau sebaliknya.</p> <h2>Bisakah satu header men-sunset lebih dari satu endpoint?</h2> <p>Header ini berlaku untuk resource yang mengembalikannya, tapi RFC mengizinkan sebuah layanan mendokumentasikan cakupan yang lebih luas: tanggal Sunset pada resource utama sebuah API bisa didefinisikan berarti seluruh API akan hilang, bukan hanya satu URL itu. Jebakannya adalah ini hanya berfungsi untuk pemanggil yang sudah tahu aturan cakupan Anda. Pemanggil yang membaca header apa adanya hanya melihat sunset pada satu resource yang ia minta dan tidak ada yang lain, jadi cakupan yang lebih luas harus dituliskan di suatu tempat yang bisa ditemukan pemanggil, bukan tersirat.</p> <h2>Apa yang harus menyertai header ini?</h2> <p>Tautan ke tempat pensiun ini dijelaskan. RFC 8594 mendaftarkan relasi tautan <code>sunset</code> miliknya sendiri untuk keperluan ini: menunjuk ke resource yang menjelaskan kebijakan pensiun, tanggal yang akan datang, atau cara bermigrasi, terpisah dari stempel waktu polos pada header.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Mengarahkan tautan itu ke <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> Anda sendiri atau halaman migrasi khusus mengubah header yang nyaris tidak diperiksa kode klien siapa pun menjadi sesuatu yang langsung ditemukan manusia yang benar-benar mencarinya. Gabungkan dengan relasi <code>successor-version</code> dari <a href="https://changeloop.dev/blog/id/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">header deprecation</a> dan pemanggil mendapat baik ke mana harus pergi maupun apa yang menggantikan ini, hanya dari respons itu sendiri.</p> <h2>Seperti apa ini dari ujung ke ujung?</h2> <p>Misalkan <code>v1</code> akan hilang pada 1 Maret 2027. Pengumuman deprecation pada hari pertama menambahkan <code>Deprecation</code> dan <code>Link: rel="successor-version"</code> ke setiap respons <code>v1</code>, sesuai <a href="https://changeloop.dev/blog/id/api-deprecation/">header deprecation</a>, tapi menahan <code>Sunset</code> sampai tanggal pensiun benar-benar pasti, bukan sekadar placeholder. Begitu pasti, setiap respons <code>v1</code> membawa:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Gateway atau monitoring milik pemanggil bisa memicu peringatan pada salah satu header secara independen: <code>Deprecation</code> mengatakan versi yang lebih baru ada, <code>Sunset</code> mengatakan yang ini punya batas waktu. Tidak ada header yang wajib berubah sebelum 1 Maret; yang berubah adalah respons itu sendiri, pada harinya, dan selama jendela brownout mana pun yang dijadwalkan sebelumnya.</p> <h2>Apakah brownout mengubah isi header?</h2> <p>Nilai header itu sendiri tidak perlu berubah untuk brownout yang dijadwalkan: tanggal sunset tetaplah tanggal sunset, terlepas dari apakah resource sesekali gagal sebelum itu. Yang berubah adalah respons, bukan headernya. Menjadwalkan jendela singkat <code>410 Gone</code> di minggu-minggu sebelum tanggal yang diumumkan, seperti dijelaskan <a href="https://changeloop.dev/blog/id/api-deprecation/">Deprecation API</a>, adalah yang mengubah kontak pertama pemanggil dengan kegagalan menjadi gladi bersih alih-alih kejadian sungguhan pada hari tanggal header itu tiba.</p> <h2>FAQ</h2> <p><strong>Apakah ada klien atau tool HTTP nyata yang benar-benar membaca header Sunset?</strong> Jarang, di sisi klien. Nilainya sebagian besar untuk siapa pun yang mengoperasikan infrastruktur di antara Anda dan pemanggil: gateway API atau tool monitoring yang Anda konfigurasi untuk memantau header ini bisa memperingatkan tim Anda sendiri, atau tim mitra, jauh sebelum kode pemanggil menyadarinya. Perlakukan ini sebagai sinyal yang Anda bangun tooling-nya, bukan sesuatu yang bisa Anda asumsikan sudah dimiliki pihak lain.</p> <p><strong>Apakah <code>Sunset</code> sama dengan <code>Cache-Control: max-age</code>?</strong> Tidak. <code>max-age</code> mengatur berapa lama salinan cache tetap valid; <code>Sunset</code> mengatur kapan resource berhenti ada sama sekali. Sebuah respons bisa membawa <code>max-age</code> yang pendek dan tanggal <code>Sunset</code> yang masih bertahun-tahun lagi, atau sebaliknya, dan tidak ada header yang membatasi yang lain.</p> <p><strong>Bisakah saya mengirim Sunset untuk satu field yang hilang, bukan seluruh endpoint?</strong> Tidak, header ini dicakup pada resource, artinya URL, bukan pada field di dalam isi responsnya. Untuk field, parameter, atau nilai enum yang akan hilang sementara endpoint-nya sendiri tetap aktif, gunakan header <code>Deprecation</code> dan entri changelog sebagai gantinya; <a href="https://changeloop.dev/blog/id/api-deprecation/">Deprecation API</a> membahas cara mengumumkan perubahan semacam itu persis.</p> <p><strong>Bagaimana jika tanggal sunset perlu digeser?</strong> Perbarui nilai headernya dan katakan itu di entri changelog yang pertama kali mengumumkannya; mengubah tanggal yang sudah dipublikasikan secara diam-diam adalah cara pemanggil memutuskan bahwa tidak satu pun tanggal Anda nyata. RFC membingkai nilai ini sebagai petunjuk justru karena tanggal memang kadang bergeser, tapi tanggal yang digeser tanpa penjelasan membuat Anda kehilangan kepercayaan untuk tanggal berikutnya juga.</p> </article> <article> <h1>Apa itu changelog? Pengertian dan contohnya</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Changelog adalah catatan bertanggal tentang apa yang berubah dalam sebuah produk, ditulis untuk orang-orang yang terdampak oleh perubahan itu, bukan untuk tim yang merilisnya. Setiap entri menyebutkan satu perubahan, menyatakan kapan itu berlaku, dan menyatakan apa yang harus dilakukan pembaca, yang pada kebanyakan entri adalah tidak ada apa-apa. Bagian terakhir itulah yang membedakan changelog dari log commit: log commit adalah catatan untuk orang yang menulis kode, changelog adalah catatan untuk orang yang memakainya.</p> <h2>Apa itu changelog, sebenarnya?</h2> <p>Daftar entri bertanggal, terbaru di atas, masing-masing menjelaskan satu perubahan dalam istilah yang bisa diperiksa pembaca. Bukan apa yang dibangun tim, tapi apa yang sekarang berbeda. "Merefaktor layanan billing" adalah pesan commit. "Faktur sekarang menampilkan pajak sebagai baris terpisah" adalah entri changelog, karena memberi tahu pembaca sesuatu yang bisa mereka periksa di akun mereka sendiri.</p> <p>Formatnya sudah lama ada dan sengaja dibuat sederhana: judul per rilis atau per hari, daftar singkat di bawahnya, kadang label kategori. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> adalah spesifikasi yang paling banyak dikutip untuk bentuk ini, dan ada karena kebanyakan proyek yang melewatkan spesifikasi berakhir dengan membuang riwayat commit sebagai gantinya, yang menjawab pertanyaan berbeda dari yang dibawa pembaca.</p> <table> <thead> <tr> <th>Dokumen</th> <th>Ditulis untuk</th> <th>Menjawab</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Siapa pun yang memakai produk</td> <td>Apa yang berubah, dan kapan?</td> </tr> <tr> <td>Log commit</td> <td>Tim yang menulis kode</td> <td>Apa yang dikerjakan, dalam urutan apa?</td> </tr> <tr> <td>Catatan rilis</td> <td>Pengguna yang memutuskan untuk update</td> <td>Apa yang bisa saya lakukan sekarang?</td> </tr> <tr> <td>Catatan patch</td> <td>Pemain atau pengguna dari satu perbaikan tertentu</td> <td>Apa yang diperbaiki rilis ini?</td> </tr> <tr> <td>Roadmap</td> <td>Siapa pun yang bertanya-tanya apa selanjutnya</td> <td>Apa yang direncanakan, dan sejauh mana?</td> </tr> </tbody></table> <p>Kelimanya tumpang tindih dalam praktiknya, tapi bukan dokumen yang sama, dan bedanya ada pada siapa yang memegangnya saat membaca. Changelog adalah yang dibangun untuk dicari dan ditautkan kembali nanti, sehingga entrinya lebih butuh tanggal dan URL stabil dibanding yang lain.</p> <h2>Apa sebenarnya isi entri changelog?</h2> <p>Empat hal, dalam urutan ini: apa yang berubah, dinyatakan dalam istilah yang akan disadari pengguna atau pemanggil; kapan itu berlaku; termasuk kategori apa (added, fixed, changed, removed adalah empat yang umum); dan, ketika penting, apa yang harus dilakukan pembaca. Tautan ke detail lebih lanjut dipersilakan. Paragraf justifikasi internal tidak, karena pembaca tidak bertanya mengapa, mereka bertanya apa.</p> <pre><code>## 2026-09-07 ### Added - Faktur sekarang menampilkan pajak sebagai baris terpisah, dalam mata uang akun pelanggan. ### Fixed - Mengekspor laporan sebagai CSV tidak lagi menghilangkan baris terakhir saat laporan melebihi 10.000 baris. </code></pre> <p>Bentuk itu berskala dari update dua baris hingga seratus entri dalam satu rilis tanpa mengubah struktur, dan itulah uji sebenarnya apakah sebuah format berfungsi: apakah terbaca sama pada minggu yang sibuk maupun yang tenang.</p> <h2>Siapa yang menulis changelog, dan kapan?</h2> <p>Siapa pun yang membuat perubahan, pada saat dirilis, bukan penulis teknis yang merekonstruksinya dari tiket seminggu kemudian. Yang menyentuh kode tahu apa yang benar-benar berubah bagi pengguna; ringkasan yang ditulis belakangan cenderung menjelaskan tiketnya alih-alih apa yang sebenarnya dirilis, dan itu biasanya lebih luas atau lebih sempit dari cakupan sebenarnya. Beberapa tim menambahkan langkah review sebelum entri menjadi publik, terutama untuk menangkap bahasa internal yang menyelip, dan review itu harus cukup cepat agar entri tetap rilis di hari yang sama.</p> <h2>Di mana seharusnya changelog berada?</h2> <p>Di halaman sendiri, di URL yang stabil, disebarkan sebagai feed. Terkubur di menu pengaturan atau tag rilis di host kode, hanya menjangkau orang yang sudah tahu ke mana harus mencari. Halaman publik bisa ditautkan dari tiket dukungan, dikutip dalam ulasan, atau dilanggan. Feed sama pentingnya dengan halamannya: pembaca yang mengecek changelog produk sebulan sekali itu jarang, yang berlangganan tidak, dan hanya feed yang melayani kelompok kedua.</p> <h2>Apa bedanya dengan catatan rilis?</h2> <p>Keduanya terus-menerus tertukar, dan cukup berbeda sehingga mencampur keduanya menghasilkan dokumen yang tidak melayani kedua pembaca dengan baik. <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">Changelog vs catatan rilis</a> membahas perbedaannya secara lengkap; singkatnya, changelog adalah catatan lengkap dan kronologis, sementara catatan rilis adalah subset terkurasi, ditulis agar sebuah update terdengar layak untuk dimiliki. Sebuah produk biasanya butuh keduanya, ditujukan untuk momen berbeda dalam hari pembaca.</p> <h2>Apa yang membuat changelog layak dibaca?</h2> <p>Kekhususan dan kejujuran tentang cakupannya sendiri. "Berbagai perbaikan bug" adalah kalimat yang mengajarkan pembaca untuk berhenti membuka halaman itu, karena tidak menjanjikan apa pun yang bisa mereka periksa. Entri yang menyebutkan perilaku persis yang berubah, bahkan untuk perbaikan kecil, adalah yang membuat langganan tetap hidup. Disiplin ini juga berlaku pada apa yang dihilangkan: changelog yang hanya mengumumkan keberhasilan dan tidak pernah perbaikan untuk sesuatu yang rusak terbaca seperti pemasaran yang menyamar sebagai changelog, dan pembaca menyadarinya.</p> <p>Disiplin versioning juga penting. <a href="https://changeloop.dev/blog/id/semantic-versioning-changelog/">Semantic versioning dan changelog Anda</a> membahas bagaimana nomor versi dan entri seharusnya cocok, sehingga pembaca yang menelusuri riwayat versi mendapat sinyal yang sama dua kali, bukan dua sinyal berbeda.</p> <h2>Bagaimana changelog dihasilkan?</h2> <p>Dengan dua cara, dan kebanyakan pengaturan nyata adalah campuran. Generasi otomatis membaca pesan commit, biasanya dalam format <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, dan mengubahnya menjadi entri tanpa ada yang menyentuh hasilnya; <a href="https://changeloop.dev/blog/id/conventional-commits-changelog/">dari conventional commits ke changelog</a> membahas pipeline itu. Generasi terkurasi berarti seseorang menulis atau menyunting setiap entri secara manual. Hasil otomatis lebih cepat dan tidak pernah melewatkan pull request yang digabung, tapi mewarisi setiap pesan commit yang samar apa adanya, sehingga kebanyakan tim yang mengotomatisasi tetap menyimpan langkah penyuntingan ringan sebelum publikasi alih-alih menampilkan hasil mentah.</p> <h2>FAQ</h2> <p><strong>Apakah setiap produk butuh changelog?</strong> Produk mana pun dengan pengguna yang terdampak oleh perubahan membutuhkannya, entah itu aplikasi SaaS, alat internal, atau API publik. Bentuknya menyesuaikan (changelog API terbaca berbeda dari aplikasi konsumen), kebutuhannya tidak.</p> <p><strong>Apa itu changelog dalam istilah software?</strong> Definisi yang sama seperti di atas: daftar bertanggal dan kronologis tentang apa yang berubah dalam software, ditulis untuk yang memakainya, bukan yang membangunnya.</p> <p><strong>Bisakah changelog dihasilkan otomatis dari commit?</strong> Ya, dan banyak tim melakukan persis itu, biasanya dari pesan berformat Conventional Commits. Kompromisnya, entri yang dihasilkan sejelas pesan commit asalnya, sehingga langkah review sebelum publikasi menangkap yang perlu diformulasikan ulang.</p> <p><strong>Apakah changelog sama dengan riwayat versi?</strong> Cukup mirip sehingga istilahnya dipakai bergantian. Riwayat versi kadang hanya daftar nomor versi dan tanggal tanpa deskripsi; changelog selalu menyertakan apa yang berubah.</p> </article> <article> <h1>Changelog API: apa yang dipublikasikan, siapa pembacanya</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Changelog API adalah catatan bertanggal dari setiap perubahan yang mungkin diperhatikan oleh pemanggil, ditulis untuk orang yang mengintegrasikan API tersebut, bukan untuk tim yang merilisnya. Audiens ini membuatnya menjadi dokumen yang berbeda dari changelog produk: pembaca sedang memutuskan apakah kodenya masih akan berfungsi bulan depan. Kebanyakan gagal dengan cara yang sama, menjadi salinan tersaring dari feed rilis internal, sehingga sebuah field yang dihapus berada di sebelah perbaikan teks dengan bobot yang sama, dan keduanya tidak dibaca.</p> <h2>Apa itu changelog API?</h2> <p>Ini adalah log publik dan bertanggal tentang perubahan pada antarmuka yang telah ditulis kodenya oleh orang lain. Tes yang berguna untuk menentukan apakah sesuatu pantas masuk di dalamnya tidak ada hubungannya dengan seberapa besar perubahan itu secara internal. Ia bertanya apakah pemanggil yang benar, ditulis tahun lalu dan tidak pernah disentuh sejak itu, bisa berperilaku berbeda karena itu. Tes ini menerima beberapa perubahan yang sangat kecil dan mengecualikan beberapa yang sangat besar.</p> <p>Semua di bawah ini mengasumsikan pemanggil berada di luar perusahaan dan pada dasarnya tidak terjangkau kecuali lewat dokumen ini. Saat pemanggilnya adalah tim lain di perusahaan yang sama, perhitungannya berubah cukup banyak sehingga butuh perlakuan sendiri; <a href="https://changeloop.dev/blog/id/internal-api-changelog/">changelog API internal</a> membahas apa yang dibutuhkan audiens itu sebagai gantinya.</p> <table> <thead> <tr> <th>Dokumen</th> <th>Audiens</th> <th>Menjawab</th> </tr> </thead> <tbody><tr> <td>Changelog API</td> <td>Developer yang memanggil API</td> <td>Apakah integrasi saya masih berfungsi?</td> </tr> <tr> <td>Release notes</td> <td>Pengguna produk</td> <td>Apa yang bisa saya lakukan sekarang yang tidak bisa sebelumnya?</td> </tr> <tr> <td>Pemberitahuan deprecation</td> <td>Pemanggil satu hal spesifik</td> <td>Kapan ini akan berhenti berfungsi?</td> </tr> <tr> <td>Halaman status</td> <td>Siapa pun yang sedang terdampak</td> <td>Apakah sedang down sekarang?</td> </tr> <tr> <td>Panduan migrasi</td> <td>Pemanggil yang sedang upgrade</td> <td>Bagaimana saya pindah dari A ke B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/id/api-migration-guide/">Cara menulis panduan migrasi API</a> membahas dokumen terakhir itu secara lengkap; singkatnya, itulah yang seharusnya ditautkan entri perubahan tak kompatibel alih-alih mencoba menggantikannya.</p> <p>Kelimanya adalah dokumen terpisah dengan siklus hidup terpisah. Pemberitahuan deprecation adalah janji dengan tanggal, dan juga masuk ke changelog, tapi entri changelog ditulis sekali sementara deprecation dilacak sampai sunset-nya. Menggabungkan keduanya adalah alasan mengapa sunset terlewat.</p> <h2>Apa yang masuk dalam satu entri?</h2> <p>Enam hal, dan tiga yang pertama biasanya yang hilang. Perubahan itu sendiri, dinyatakan dalam istilah request atau response, bukan komponen internal. Apakah itu merusak pemanggil yang benar. Apa yang harus dilakukan pemanggil, termasuk "tidak ada". Tanggal berlakunya. Versi atau versi-versi yang terdampak. Tautan ke panduan migrasi jika ada.</p> <p>Entri yang mengatakan "endpoint accounts ditingkatkan" gagal pada keenamnya. Entri yang mengatakan "field <code>accounts.type</code> sekarang mengembalikan <code>individual</code> di mana sebelumnya mengembalikan <code>personal</code>; nilai yang sudah ada tidak berubah untuk akun yang dibuat sebelum 2 September; tidak perlu tindakan kecuali Anda membandingkan string" menjawab keenamnya dalam satu kalimat.</p> <p>Kategorikan entri berdasarkan konsekuensi, bukan departemen. Tiga label membawa hampir seluruh nilainya: breaking, additive, dan fixed. <a href="https://semver.org/">Semantic Versioning</a> sudah mendefinisikan dua yang pertama secara tepat, dan meminjam definisinya alih-alih menciptakan yang lokal berarti pembaca yang tahu semver tahu label Anda. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> menawarkan set yang lebih panjang jika Anda mau, dan aturan intinya berlaku di sini lebih kuat daripada di tempat lain: log itu untuk manusia, dan tumpukan judul commit bukanlah itu.</p> <h2>Apa bedanya changelog API dengan release notes?</h2> <p>Release notes menjelaskan apa yang bisa dilakukan produk sekarang. Changelog API menjelaskan apa kontraknya sekarang. Pekerjaan yang sama yang dirilis sering menghasilkan entri di keduanya, dirumuskan berbeda, karena audiensnya butuh hal yang berbeda: format ekspor baru adalah fitur bagi pengguna dan nilai enum baru bagi pemanggil yang bergantung pada field itu.</p> <p>Konsekuensi praktisnya adalah keduanya tidak bisa menjadi feed yang sama dengan gaya berbeda. Pemanggil yang berlangganan segala yang Anda rilis akhirnya akan berhenti berlangganan, lalu melewatkan breaking change. Jika Anda menerbitkan satu feed, saring; jika menerbitkan dua, buat yang API lebih sempit dan jangan pernah biarkan entri marketing masuk ke dalamnya. Kami membandingkan kedua bentuk berdampingan di <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">changelog vs release notes</a>.</p> <h2>Di mana changelog API sebaiknya berada?</h2> <p>Di samping dokumentasi referensi, di URL yang stabil, dengan setiap entri dapat dialamatkan secara individual lewat fragment atau path-nya sendiri. Pemanggil menautkan entri dalam tinjauan insiden dan tiket internal, dan entri yang tidak bisa ditautkan akan ditempel sebagai screenshot sebagai gantinya.</p> <p>Terbitkan juga sebagai output yang bisa dibaca mesin, selain sebagai halaman. Feed JSON yang mengikuti <a href="https://www.jsonfeed.org/version/1.1/">spesifikasi JSON Feed</a> atau <a href="https://www.rssboard.org/rss-specification">feed RSS</a> tidak memakan biaya apa pun begitu entri menjadi data terstruktur, dan itulah yang memungkinkan pelanggan memasukkan perubahan Anda ke proses rilis mereka sendiri. Ini juga bagian yang menentukan apakah ada yang membangun di atasnya. GitHub mendokumentasikan <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versi REST API</a>-nya tepat di samping referensi dengan alasan yang sama: kebijakan versi adalah bagian dari antarmuka.</p> <h2>Seperti apa entri yang baik dalam praktiknya?</h2> <p>Tiga entri dari minggu yang sama, dalam bentuk yang dijelaskan di atas:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` sekarang menolak `currency` yang tidak cocok dengan mata uang akun pelanggan, mengembalikan 422 alih-alih mengonversi secara diam-diam. Pemanggil yang mengandalkan konversi harus mengirim mata uang akun. Hanya memengaruhi v2; v1 tidak berubah hingga sunset-nya pada 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` mendapat timestamp `settled_at`, null hingga faktur dilunasi. Tidak perlu tindakan. Client yang menolak field tak dikenal sebaiknya diperbarui. 2026-08-31 Fixed v2 `GET /invoices?status=` mengembalikan halaman kosong alih-alih 400 untuk status yang tidak dikenal. Sekarang mengembalikan 400 dengan nilai yang diterima. Pemanggil dengan salah ketik sebelumnya melihat nol hasil, sekarang melihat error. </code></pre> <p>Yang ketiga adalah jenis yang paling sering dihilangkan, karena secara internal itu adalah perbaikan bug. Bagi pemanggil yang membangun retry di sekitar halaman kosong itu, ini adalah perubahan perilaku, dan entri itulah yang mencegah tiket support. Labelnya mengatakan fixed dan isinya mengatakan apa yang mungkin diperhatikan pemanggil, yang merupakan pembeda yang menjaga log tetap jujur tanpa menggembungkan setiap perbaikan menjadi breaking change.</p> <h2>Bagaimana pemanggil berlangganan?</h2> <p>Berikan mereka lebih dari satu kanal, karena tugas mereka berbeda. Feed untuk developer yang menginginkan semuanya. Email untuk yang hanya menginginkan breaking change. Header response untuk kode itu sendiri, satu-satunya pelanggan yang tidak pernah lupa memeriksa: <a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code> yang didefinisikan di RFC 8594</a> menempatkan tanggal pensiun di response, tempat library client bisa mencatatnya.</p> <p>Kanal yang paling sering dilewatkan kebanyakan tim adalah yang langsung. Jika seorang pemanggil menggunakan field yang sedang Anda ubah minggu lalu, Anda tahu siapa dia, dan email ke akun-akun itu lebih berharga daripada siaran sebanyak apa pun. Ini adalah disiplin yang sama dengan <a href="https://changeloop.dev/blog/id/customer-feedback-loop/">menutup loop feedback pelanggan</a>, diterapkan pada perubahan yang tidak diminta siapa pun: orang yang terdampak diberi tahu satu per satu, dan semua yang lain mendapat feed. Webhook adalah kanal keempat dengan mode kegagalannya sendiri yang layak diketahui sebelum mengandalkannya: <a href="https://changeloop.dev/blog/id/webhook-changelog/">changelog webhook</a> membahas mengapa perubahan payload di sana rusak diam-diam, tanpa pemanggil yang bisa menolak bentuk barunya.</p> <h2>Bagaimana cara menulis entri untuk breaking change?</h2> <p>Mulai dengan kerusakannya, bukan alasannya. Pemanggil yang memindai sepuluh entri perlu tahu di klausa pertama apakah entri ini akan menghabiskan waktunya. Lalu tanggal, versi yang terdampak, migrasi, dan tenggat waktu jika perilaku lama akan hilang alih-alih berubah.</p> <p>Masukkan konten yang sama ke pemberitahuan deprecation, header response, dan email langsung, dirumuskan secara konsisten, dan beri keempatnya tanggal yang sama. Perbedaan di antara mereka adalah kegagalan yang mengubah perubahan terencana menjadi insiden, karena pemanggil yang hanya membaca satu darinya bertindak berdasarkan tanggal yang salah. <a href="https://changeloop.dev/blog/id/breaking-changes/">Apa itu breaking change</a> membahas keputusannya sendiri, dan <a href="https://changeloop.dev/blog/id/api-deprecation/">cara men-deprecate API</a> membahas jadwal yang mengikutinya.</p> <p>Di changeloop, perubahan API menjadi entri saat pull request digabungkan, seseorang mengedit dan menyetujui draf, dan entri diterbitkan ke <a href="https://changeloop.dev/docs">feed dan widget</a> pada saat yang sama pemanggil yang masukan widget-nya menjadi issue GitHub yang ditutup oleh pull request itu diberi tahu di issue tersebut. Langkah peninjauan adalah yang penting di sini: changelog API adalah dokumen kontraktual, dan tidak ada draf yang boleh sampai ke pemanggil tanpa dibaca oleh seseorang.</p> <h2>FAQ</h2> <p><strong>Apakah setiap perubahan API perlu entri changelog?</strong> Setiap perubahan yang mungkin diperhatikan pemanggil yang benar, ya, termasuk yang Anda anggap internal. Perubahan tanpa efek yang bisa diamati pada request atau response tidak, dan menambahkannya melatih pembaca untuk hanya melirik.</p> <p><strong>Sebaiknya changelog API berada di docs atau di situs marketing?</strong> Di docs, tepat di samping referensi. Pembaca biasanya sudah ada di sana, dan changelog di situs marketing cenderung mendapat audiens yang bukan tujuan penulisannya.</p> <p><strong>Seberapa jauh ke belakang seharusnya?</strong> Tanpa batas. Entri dikutip bertahun-tahun kemudian dalam tinjauan insiden, dan log yang dipotong merusak tautan itu. Gunakan paginasi alih-alih memangkas.</p> <p><strong>Apakah saya perlu changelog terpisah per versi API?</strong> Tidak, satu log dengan field versi per entri lebih mudah dibaca dan dicari. Menyaring berdasarkan versi adalah fitur halaman, bukan alasan untuk memisahkan dokumen.</p> </article> <article> <h1>Cara membangun halaman changelog yang diikuti orang</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Halaman changelog layak dibangun ketika seseorang akan kembali ke sana. Itu standar yang lebih tinggi daripada sekadar memilikinya, dan itulah standar yang paling sering gagal dipenuhi: halaman yang ada, ditautkan di footer, diperbarui secara sporadis, dan tidak dikunjungi siapa pun kecuali saat insiden. Keputusan yang memisahkan keduanya dibuat sebelum apa pun ditulis, dan sebagian besar tentang di mana halaman itu berada dan apa lagi yang dihasilkan dari konten yang sama.</p> <h2>Apa itu halaman changelog?</h2> <p>Ini adalah daftar publik dan bertanggal tentang apa yang berubah pada sebuah produk, di URL milik Anda. Ini salah satu dari lima permukaan tempat entri yang sama bisa muncul, dan pertanyaan yang berguna bukan mana yang dipilih, melainkan mana yang kanonik dan mana yang dihasilkan darinya.</p> <table> <thead> <tr> <th>Permukaan</th> <th>Terbaik untuk</th> <th>Biaya</th> </tr> </thead> <tbody><tr> <td>Halaman hosted</td> <td>Pencarian, penautan, catatan panjang</td> <td>Sebuah URL dan template</td> </tr> <tr> <td>Widget in-app</td> <td>Menjangkau pengguna yang tak pernah mengunjungi halaman</td> <td>Sebuah embed, dan kehati-hatian</td> </tr> <tr> <td>Bagian docs</td> <td>Audiens API dan developer</td> <td>Menjaganya di samping referensi</td> </tr> <tr> <td>Feed JSON</td> <td>Pelanggan yang membangun di atas perubahan Anda</td> <td>Struktur yang sudah Anda miliki</td> </tr> <tr> <td>Feed RSS</td> <td>Developer yang berlangganan sekali</td> <td>Hampir tidak ada apa-apa</td> </tr> </tbody></table> <p>Pilih satu sumber kanonik, terbitkan sekali, dan hasilkan sisanya. Tim yang memelihara halaman dan widget secara terpisah dengan tangan akan berakhir dengan dua teks yang tidak cocok, dan ketidakcocokan itu ditemukan oleh pelanggan.</p> <h2>Di mana sebaiknya halaman changelog berada?</h2> <p>Di domain Anda sendiri, di path yang stabil, dengan setiap entri dapat dialamatkan secara individual. Tiga lokasi umum adalah path di situs utama, subdomain, dan bagian dari dokumentasi. Path di situs utama adalah pilihan default yang seharusnya diperdebatkan penolakannya, bukan dukungannya: ia mewarisi otoritas situs, tidak butuh sertifikat atau DNS tambahan, dan menjaga halaman dalam navigasi yang sama dengan yang lain.</p> <p>Subdomain adalah jawaban yang tepat ketika halaman dilayani oleh sistem yang berbeda dari situs marketing dan Anda kalau tidak akan melakukan proxy. Biayanya adalah ia mengumpulkan otoritas secara terpisah. Menempatkan changelog di docs itu tepat ketika audiensnya developer, dengan alasan yang dibahas di <a href="https://changeloop.dev/blog/id/api-changelog/">changelog API</a>: pembaca biasanya sudah ada di sana.</p> <p>Yang lebih penting daripada pilihan itu adalah entri harus bisa ditautkan secara individual. Orang menautkan entri dalam tinjauan insiden dan tiket internal, dan entri yang hanya bisa ditautkan sebagai "changelog, scroll ke bawah" akan ditempel sebagai screenshot sebagai gantinya.</p> <h2>Apa yang dibutuhkan halaman changelog?</h2> <p>Lima hal, dan pada dua yang pertama sebagian besar halaman gagal. Entri bertanggal per perubahan, yang terbaru dulu. Kategori atau label per entri agar bisa dipindai berdasarkan jenis yang diminati. Permalink per entri. Jalur berlangganan. Pencarian atau filter setelah sekitar lima puluh entri.</p> <p>Selebihnya opsional. Screenshot membantu dan memakan biaya pemeliharaan. Nama penulis membangun kepercayaan di beberapa produk dan menjadi noise di produk lain. Nomor versi penting bagi pemanggil sebuah API dan hampir tidak ada orang lain. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> adalah pilihan default yang masuk akal untuk label jika Anda tidak punya alasan menciptakan sendiri, dan aturan intinya adalah yang layak dipertahankan bahkan jika Anda membuang sisanya: log ditulis untuk manusia.</p> <p>Kelompokkan berdasarkan tanggal, bukan versi, ketika produk Anda merilis secara berkelanjutan. Pembaca yang memindai "apakah ini sebelum atau sesudah insiden kami tanggal sembilan" mencari tanggal, dan halaman yang diorganisasi berdasarkan nomor versi memaksanya menghitung.</p> <h2>Halaman atau widget in-app?</h2> <p>Keduanya, dari satu sumber. Halaman adalah tempat pencarian, tautan, dan catatan panjang berada. Widget adalah cara Anda menjangkau mayoritas pengguna yang tidak akan pernah mengunjungi halaman, dan ia berfungsi karena muncul di produk yang sudah mereka gunakan.</p> <p>Kegagalan widget adalah gangguan. Badge yang menuntut perhatian untuk setiap entri akan diabaikan secara permanen dalam seminggu, yang membuat Anda kehilangan kanal untuk entri yang benar-benar penting. Hitung yang belum dibaca sejak terakhir kali pembaca melihat, semai penghitung secara diam pada kunjungan pertama agar tidak ada yang disambut badge riwayat satu tahun, dan biarkan pembaca membukanya sendiri alih-alih Anda membukanya untuk mereka.</p> <h2>Bagaimana membuat halaman changelog bisa dibaca mesin?</h2> <p>Terbitkan entri yang sama sebagai feed. <a href="https://www.jsonfeed.org/version/1.1/">Feed JSON</a> adalah pilihan dengan gesekan paling rendah bagi apa pun yang mengonsumsinya lewat kode, dan <a href="https://www.rssboard.org/rss-specification">feed RSS</a> adalah yang diharapkan developer yang berlangganan di reader. Keduanya murah begitu entri menjadi data terstruktur alih-alih HTML yang ditulis tangan, yang merupakan alasan sebenarnya untuk menjaga salinan kanonik tetap terstruktur.</p> <p>Beri markup pada halaman juga. Entri adalah karya dengan tanggal dan judul, dan <a href="https://schema.org/CreativeWork">schema.org</a> menyediakan kosakatanya. Ini layak dilakukan dengan alasan yang sama seperti permalink: membuat halaman bisa digunakan oleh hal-hal yang bukan browser, termasuk proses rilis pelanggan sendiri. Tidak satu pun ini berfungsi jika entri yang mendasarinya tidak pernah menjadi data terstruktur sejak awal; <a href="https://changeloop.dev/blog/id/changelog-file-formats/">format berkas changelog</a> membahas berapa biaya masing- masing dari Markdown, JSON, dan YAML sebagai sumber kebenaran tempat feed dan markup ini sebenarnya dihasilkan.</p> <h2>Apakah halaman changelog membantu SEO?</h2> <p>Secara tidak langsung dan lambat. Entri individual jarang meranking, karena tidak menargetkan query apa pun yang diketik orang. Halaman mendapatkan tempatnya lewat tautan: entri dikutip dalam balasan support, forum, dan analisis insiden, dan tautan itu menumpuk di URL milik Anda. Halaman yang diperbarui setiap minggu selama dua tahun juga menjadi sinyal kesegaran yang kredibel bagi produk yang dimilikinya.</p> <p>Yang tidak berhasil adalah memperlakukan entri sebagai content marketing. Entri yang digelembungkan menjadi tiga paragraf demi panjang lebih buruk dalam tugas sebenarnya, yaitu memberi tahu pembaca dalam satu kalimat apakah sesuatu yang mereka gunakan berubah. Jika Anda ingin changelog mendukung pencarian, tempatkan usaha pada permalink, feed, dan tautan internal ke sana, dan biarkan entri tetap singkat. Halaman <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> kami sendiri mengumpulkan halaman yang menangkap keseimbangan ini dengan tepat.</p> <h2>Bagaimana orang berlangganan?</h2> <p>Berikan mereka jalur yang sudah mereka gunakan: feed RSS atau JSON untuk developer, email untuk yang hanya ingin mendengar hal penting, dan widget in-app untuk semua yang tidak akan pernah melakukan keduanya. Tanyakan apa yang ingin mereka dengar alih-alih mengasumsikannya, karena pembaca yang menginginkan breaking change dan menerima perbaikan teks akan berhenti berlangganan dari keduanya.</p> <p>Jalur yang sebaiknya ditambahkan terakhir adalah yang menutup loop. Ketika sebuah entri menyelesaikan apa yang diminta seseorang secara spesifik, beri tahu mereka langsung alih-alih berharap mereka membaca halaman. Di changeloop, entri diterbitkan sekaligus di <a href="https://changeloop.dev/docs">halaman, feed, dan widget</a>, dan orang yang masukan widget-nya menjadi issue GitHub yang ditutup oleh pull request diberi tahu di issue itu dengan tautan ke entri, dan melihat entri tersebut di widget. Mekanismenya sama seperti langganan apa pun; bedanya, penerima sudah bertanya. Itulah argumen yang dijelaskan di <a href="https://changeloop.dev/blog/id/customer-feedback-loop/">menutup loop feedback dari sisi changelog</a>.</p> <h2>FAQ</h2> <p><strong>Sebaiknya halaman changelog di subdomain atau path?</strong> Secara default, path di situs utama, karena mewarisi otoritas situs dan tidak butuh infrastruktur tambahan. Subdomain dibenarkan ketika sistem berbeda melayani halaman itu.</p> <p><strong>Berapa banyak entri yang sebaiknya ditampilkan halaman sekaligus?</strong> Cukup untuk mengisi layar dan tidak lebih, dengan paginasi setelahnya. Memuat riwayat dua tahun ke satu dokumen itu lambat dan membuat entri terbaru lebih sulit ditemukan.</p> <p><strong>Apakah entri lama pernah perlu dihapus?</strong> Tidak. Entri dikutip dari luar situs Anda dan tautan akan rusak. Perbaiki entri di tempatnya dengan catatan, dan jaga URL tetap hidup.</p> <p><strong>Apakah setiap perubahan harus muncul di halaman?</strong> Hanya yang mungkin diperhatikan pengguna. Halaman yang mencatat refactor internal melatih pembaca untuk hanya melirik, dan halaman yang dilirik gagal pada hari ia membawa sesuatu yang mendesak.</p> </article> <article> <h1>Template email update produk yang dibaca orang</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Email update produk yang dibaca adalah yang dikirim ke seseorang yang meminta persis apa yang diumumkannya. Segalanya bersaing dengan sisa kotak masuk soal seberapa menarik, kompetisi yang kalah dari pengumuman rilis di kebanyakan minggu. Fakta tunggal ini seharusnya menentukan bentuk email sebelum kata apa pun dirumuskan: siapa yang menerimanya, dan apa yang dilakukan orang itu hingga masuk daftar.</p> <h2>Apa itu email update produk?</h2> <p>Ini adalah pesan yang memberi tahu pengguna yang ada tentang apa yang berubah pada produk yang sudah mereka gunakan. Ada empat jenis berbeda, dan memperlakukannya sebagai satu daftar adalah alasan mengapa tingkat buka menurun. Masing-masing punya pemicu berbeda, audiens berbeda, dan frekuensi yang bisa diterima berbeda.</p> <table> <thead> <tr> <th>Jenis</th> <th>Pemicu</th> <th>Audiens</th> <th>Frekuensi</th> </tr> </thead> <tbody><tr> <td>Notifikasi bertarget</td> <td>Permintaan spesifik seseorang dirilis</td> <td>Satu orang</td> <td>Setiap kali terjadi</td> </tr> <tr> <td>Pemberitahuan breaking change</td> <td>Perubahan yang membebani pekerjaan pembaca</td> <td>Hanya akun terdampak</td> <td>Setiap kali terjadi</td> </tr> <tr> <td>Digest</td> <td>Berlalunya waktu</td> <td>Pengguna opt-in</td> <td>Maksimal bulanan</td> </tr> <tr> <td>Pengumuman peluncuran</td> <td>Peluncuran yang layak menginterupsi</td> <td>Segmen atau semua</td> <td>Jarang, dan harus terasa jarang</td> </tr> </tbody></table> <p>Kebanyakan tim hanya membangun yang ketiga, mengirim ke semua orang, lalu menyimpulkan bahwa email update produk tidak berhasil. Dua yang pertama membawa hampir seluruh nilainya, karena pembaca punya alasan sebelumnya untuk peduli, dan pesan tiba selagi alasan itu masih hidup.</p> <p>Keempat baris di sini semuanya ditulis untuk pelanggan. Sales, support, dan customer success juga perlu tahu apa yang dirilis, biasanya dalam bentuk berbeda dari keempat ini; <a href="https://changeloop.dev/blog/id/internal-release-notes/">release notes internal</a> membahas apa yang seharusnya dikatakan dokumen itu dan mengapa harus keluar sebelum catatan untuk pelanggan.</p> <p>Email adalah salah satu dari beberapa kanal yang bisa dipakai pengumuman peluncuran, bukan satu-satunya. <a href="https://changeloop.dev/blog/id/new-feature-announcement/">Cara mengumumkan fitur baru</a> membahas yang lain, dan cara memilih di antaranya berdasarkan seberapa besar fitur itu sebenarnya.</p> <h2>Apa yang masuk template?</h2> <p>Enam blok, dalam urutan ini. Yang pertama biasanya yang paling sering hilang, dan itulah yang melakukan pekerjaan.</p> <pre><code>Subjek: <apa yang berubah, dengan kata-kata pembaca> 1. Mengapa Anda menerima ini "Anda meminta ekspor CSV bulan Maret." atau "Integrasi Anda memanggil /v1/invoices, yang berubah 15 Januari." 2. Apa yang berubah Satu kalimat. Apa yang sekarang mungkin, atau apa yang sekarang rusak. 3. Apa yang harus Anda lakukan Sering "tidak ada". Katakan secara eksplisit, jangan biarkan tersirat. 4. Di mana melihatnya Tautan ke entri changelog, bukan ke homepage. 5. Kapan Tanggal rilis, atau sejak kapan berlaku. 6. Cara berhenti berlangganan Satu klik, dan langsung dihormati. </code></pre> <p>Blok 1 adalah perbedaan antara pesan dan siaran umum. Pembaca yang diberi tahu, di baris pertama, bahwa ini adalah penyelesaian dari sesuatu yang secara pribadi ia minta, akan membaca sisanya. Tanpa itu, blok 2 sampai 5 adalah newsletter, sebagus apa pun tulisannya.</p> <p>Jaga keseluruhannya di bawah sekitar 150 kata. Email adalah penunjuk ke entri changelog, dan entrilah tempat detail berada. Email yang mereproduksi seluruh entri tidak memberi pembaca alasan untuk klik, dan tidak memberi Anda sinyal apakah ada yang peduli.</p> <h2>Subjek apa yang berhasil?</h2> <p>Sebutkan perubahannya, bukan rilisnya. "Ekspor CSV sudah live" mengalahkan "update September" karena yang pertama adalah fakta yang bisa dinilai pembaca dan yang kedua adalah wadah. Nomor versi di subjek berguna bagi pemanggil sebuah API dan noise bagi semua orang lain, alasan lain untuk memisahkan audiens.</p> <p>Hindari mengklaim manfaat yang belum disetujui pembaca. "Laporan Anda sekarang lebih cepat" mengklaim sesuatu tentang pengalamannya; "Laporan di atas 10.000 baris sekarang dimuat dalam kurang dari satu detik" melaporkan perubahan dan membiarkan dia memutuskan apakah itu penting.</p> <h2>Kapan mengirimnya, dan kepada siapa?</h2> <p>Kirim notifikasi bertarget pada saat hal itu dirilis, kepada orang-orang yang memintanya, secara individual. Kirim pemberitahuan breaking change segera setelah tanggal pasti dan sekali lagi mendekati tanggal itu, kepada akun yang benar-benar terdampak alih-alih seluruh daftar. Kirim digest hanya jika Anda punya cukup perubahan hingga pembaca akan melewatkan sesuatu jika tidak, dan biarkan orang mendaftar secara terpisah.</p> <p>Daftar yang hampir tidak pernah sebaiknya Anda gunakan adalah "semua pengguna". Itu mengubah pesan spesifik menjadi generik, dan melatih orang berhenti berlangganan. Segmentasikan berdasarkan perilaku yang sudah Anda simpan: siapa yang memintanya, siapa yang menggunakan endpoint ini, siapa yang ada di paket ini.</p> <h2>Apakah butuh persetujuan untuk mengirimnya?</h2> <p>Bagi pelanggan yang ada, update tentang layanan yang mereka gunakan biasanya adalah pertanyaan hukum yang berbeda dari marketing ke calon pelanggan, dan jawabannya tergantung di mana mereka berada dan apa yang Anda katakan saat pendaftaran. Di UE, pertanyaan relevannya adalah dasar hukum mana dari <a href="https://gdpr-info.eu/art-6-gdpr/">Pasal 6 GDPR</a> yang berlaku, dan di Amerika Serikat pesan komersial membawa persyaratan spesifik yang ditetapkan dalam <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">panduan kepatuhan CAN-SPAM FTC</a>. Keduanya menuntut hal yang sama dalam praktik: katakan siapa Anda, perjelas tujuannya, dan biarkan orang bisa berhenti.</p> <p>Apa pun dasarnya, jaga aliran transaksional dan marketing tetap terpisah di tingkat pengiriman. Pemberitahuan breaking change yang berhenti dilanggan pelanggan karena berbagi daftar dengan digest promosi adalah insiden support yang menunggu tanggalnya.</p> <h2>Seperti apa jika diisi?</h2> <p>Notifikasi bertarget, email update produk paling berharga dan yang paling jarang dibangun tim:</p> <pre><code>Subjek: Ekspor CSV sudah live Hai Dana, kamu meminta ekspor CSV bulan Maret. Sudah live pagi ini. Laporan sekarang punya tombol Ekspor yang menghasilkan CSV dari tampilan saat ini, termasuk filter. Tidak ada yang perlu kamu lakukan. Sudah aktif di akunmu. Detail: example.com/changelog#csv-export Dirilis: 2 September 2026 Kamu menerima ini karena memintanya. Berhenti berlangganan update permintaan: <tautan> </code></pre> <p>Sembilan puluh kata, dan pembaca tahu di baris pertama mengapa ini datang. Bandingkan dengan perubahan yang sama dalam digest bulanan, di mana ia muncul sebagai satu dari sembilan poin dan Dana tidak punya alasan menyadari permintaannya sendiri sudah keluar.</p> <h2>Apa yang harus diukur?</h2> <p>Bukan hanya tingkat buka. Untuk notifikasi bertarget, pertanyaannya adalah apakah orang yang meminta kembali dan menggunakan hal itu, jadi angka yang perlu diamati adalah klik ke entri dan apakah akun itu menggunakan fitur dalam seminggu. Untuk pemberitahuan breaking change, itu cakupan: berapa persen akun terdampak yang membuka sebelum tanggal, dan dengan siapa Anda menindaklanjuti secara individual.</p> <p>Digest adalah satu-satunya dari keempatnya di mana tingkat buka berarti banyak, dan bahkan di sana lebih berguna sebagai tren terhadap riwayatnya sendiri daripada terhadap benchmark industri. Jenis email update produk yang berbeda punya tugas yang berbeda, jadi angka yang dirata-rata di semuanya tidak menggambarkan apa pun yang bisa ditindaklanjuti.</p> <h2>Apa bedanya dengan release notes?</h2> <p>Release notes adalah dokumen yang tetap tersedia. Email adalah mekanisme pengiriman yang terjadi sekali. Perubahan yang sama menghasilkan keduanya, dan email sebaiknya lebih pendek daripada entri yang ditunjuknya. <a href="https://changeloop.dev/blog/id/release-notes-best-practices/">Praktik terbaik release notes</a> membahas dokumennya, dan <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">changelog vs release notes</a> membahas yang mana yang sedang Anda tulis.</p> <p>Hubungan yang layak dibenarkan: entri changelog adalah teks kanonik dan email mengutipnya. Ketika keduanya menyimpang, pembaca yang klik menemukan deskripsi berbeda tentang perubahan itu dan berhenti mempercayai keduanya. Menerbitkan entri lebih dulu dan menghasilkan email darinya menghilangkan penyimpangan itu secara konstruksi. changeloop bekerja dengan cara yang sama di sisinya: entri ditinjau sekali dan diterbitkan di <a href="https://changeloop.dev/docs">halaman, feed, dan widget</a>, dan orang yang memintanya melalui widget diberi tahu di issue GitHub yang berasal dari masukannya, dan di widget itu sendiri. changeloop tidak mengirim email; alat email Anda mengutip entri yang diterbitkan.</p> <h2>FAQ</h2> <p><strong>Seberapa sering email update produk sebaiknya keluar?</strong> Sesering ada sesuatu yang spesifik yang ingin diketahui penerima, yang untuk notifikasi bertarget berarti setiap kali permintaannya dirilis, dan untuk digest maksimal bulanan.</p> <p><strong>Haruskah email berisi seluruh entri changelog?</strong> Tidak. Satu kalimat dan satu tautan. Entri adalah versi kanonik, dan salinan lengkap di email berarti dua teks yang harus dijaga tetap selaras.</p> <p><strong>Tingkat buka berapa yang harus saya harapkan?</strong> Bandingkan setiap jenis dengan dirinya sendiri, bukan dengan benchmark. Notifikasi bertarget dan digest bulanan adalah produk yang berbeda, dan merata-ratakannya menyembunyikan satu-satunya angka yang layak diamati.</p> <p><strong>Apakah saya perlu daftar terpisah untuk breaking change?</strong> Ya, dan itu sebaiknya daftar yang orang tidak bisa berhenti berlangganan begitu saja tanpa memahami konsekuensinya, karena itulah daftar yang membuat mereka kehilangan layanan.</p> </article> <article> <h1>Cara men-deprecate API tanpa kehilangan developer</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Men-deprecate API berarti mengumumkan bahwa sesuatu masih berfungsi hari ini dan akan berhenti berfungsi pada tanggal yang dinyatakan, lalu menepati kedua bagian janji itu. Kebanyakan deprecation gagal di bagian kedua: tanggalnya bergeser diam-diam, atau tiba dan pemanggil yang tidak pernah melihat pemberitahuan mengetahuinya dari sebuah error. Deprecation selesai ketika setiap pemanggil yang terdampak sudah bermigrasi atau diberi tahu, secara individu, bahwa mereka belum.</p> <h2>Apa itu deprecation API?</h2> <p>Deprecation adalah periode antara mengumumkan bahwa endpoint, field atau versi akan menghilang dan benar-benar menghapusnya. Selama periode itu perilaku lama tetap berfungsi, dokumentasi mengatakan itu akan pergi, dan setiap respons membawa peringatan yang bisa dibaca mesin. Penghapusan adalah peristiwa terpisah, lebih belakangan, sering disebut sunset. Keduanya tercampur, dan pencampuran itu tempat kerusakan terjadi: "deprecated" mulai berarti "mungkin sudah hilang", dan pemanggil berhenti mempercayai kedua kata itu.</p> <table> <thead> <tr> <th>Istilah</th> <th>Arti</th> <th>Yang bisa diandalkan pemanggil</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Diumumkan akan hilang, masih berfungsi</td> <td>Perilaku penuh sampai tanggal sunset</td> </tr> <tr> <td>Sunset</td> <td>Tanggal berhentinya berfungsi</td> <td>Tidak ada apa pun setelah tanggal ini</td> </tr> <tr> <td>Retired / dihapus</td> <td>Hilang; permintaan gagal</td> <td>Error, idealnya yang menyebutkan penggantinya</td> </tr> <tr> <td>Legacy</td> <td>Tidak jelas. Hindari kata ini</td> <td>Tidak ada apa pun, yang menjadi masalahnya</td> </tr> </tbody></table> <h2>Berapa lama periode deprecation seharusnya?</h2> <p>Cukup lama bagi pemanggil untuk mengetahuinya dan melakukan pekerjaan, diukur dari saat pemberitahuan mencapai mereka, bukan dari saat Anda menulisnya. Sembilan puluh hari adalah batas bawah umum untuk API web publik. Dua belas bulan itu normal untuk apa pun yang tertanam dalam perangkat lunak yang diinstal pengguna akhir, karena perbaikannya juga harus melalui proses rilis mereka. Panduan versioning Google, <a href="https://google.aip.dev/185">AIP-185</a>, meminta masa transisi yang wajar dan merekomendasikan 180 hari bahkan sebelum menghapus fungsionalitas beta, dan Kubernetes mendokumentasikan <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">kebijakan deprecation-nya</a> dalam jumlah rilis alih-alih bulan, yang merupakan satuan yang tepat ketika pemanggil Anda memperbarui berdasarkan versi.</p> <p>Pilih satu periode, tuliskan sebagai kebijakan, dan berhenti memutuskannya per perubahan. Kebijakan yang diterbitkan mengubah setiap deprecation dari negosiasi menjadi penerapan aturan.</p> <p>Menuliskan kebijakan deprecation mencakup awal jendela waktu; <a href="https://changeloop.dev/blog/id/sunsetting-api-version/">mengakhiri versi API</a> membahas pemberitahuan terpisah yang dibutuhkan di akhir, saat periode itu benar-benar habis dan versi berhenti bekerja.</p> <h2>Jadwal deprecation</h2> <p>Empat tanggal, diumumkan bersama pada hari pertama. Masing-masing adalah entri changelog terpisah saat tiba, jadi ceritanya diceritakan empat kali kepada siapa pun yang hanya membaca changelog.</p> <ol> <li><strong>Umumkan.</strong> Entri menyatakan apa yang di-deprecate, mengapa, apa penggantinya, dan tanggal sunset. Dokumentasi untuk hal lama mendapat banner yang menautkan ke migrasi. Respons mendapat header yang dijelaskan di bawah.</li> <li><strong>Ingatkan, di tengah jalan.</strong> Entri kedua, dan pesan langsung ke setiap pemanggil yang masih menggunakan perilaku lama. Ini langkah yang membutuhkan data penggunaan: jika Anda tidak bisa mendaftar siapa yang masih memanggil endpoint yang di-deprecate, Anda tidak bisa melakukannya, dan layak diperbaiki sebelum deprecation berikutnya.</li> <li><strong>Brownout, sesaat sebelum tanggalnya.</strong> Kembalikan error untuk perilaku lama selama jendela singkat, satu jam atau satu hari, lalu pulihkan. Pemanggil yang melewatkan setiap pemberitahuan mengetahuinya sekarang, selagi masih ada waktu. GitHub menggunakan brownout terjadwal sebelum <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">mempensiunkan autentikasi kata sandi untuk API</a>, dan ini langkah tunggal paling efektif dalam daftar ini.</li> <li><strong>Sunset.</strong> Hapus. Error yang menggantikannya menyebutkan penggantinya dan menautkan panduan migrasi. Pertahankan error itu di tempatnya untuk waktu yang lama; 404 tidak memberi tahu pemanggil apa-apa.</li> </ol> <h2>Apa yang harus dikatakan pemberitahuan deprecation?</h2> <p>Pemberitahuan deprecation mengatakan apa yang akan hilang, kapan berhenti, apa yang digunakan sebagai gantinya, dan siapa yang terdampak. Berikut bentuknya, terisi:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> di-deprecate dan berhenti berfungsi pada 1 Maret 2027.</strong> Digantikan oleh <code>GET /v2/reports?granularity=day</code>, yang mengembalikan data yang sama dengan skema stabil dan penomoran halaman. Memengaruhi 214 integrasi yang memanggil endpoint v1 dalam 30 hari terakhir; jika milik Anda salah satunya, Anda juga akan menerima pemberitahuan ini melalui email. Panduan migrasi: [tautan]. Tidak ada yang berubah hingga 1 Maret 2027. Sejak tanggal itu endpoint v1 mengembalikan <code>410 Gone</code> dengan tautan ke entri ini.</p> </blockquote> <p>Setiap kalimat membawa sesuatu yang dibutuhkan pembaca. Jumlah integrasi yang terdampak memberi tahu setiap pembaca apakah harus terus membaca. "Tidak ada yang berubah hingga" adalah kalimat yang membiarkan yang tidak terdampak menutup tab-nya. Halaman <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> mengumpulkan entri dari tim yang menulis bentuk ini secara konsisten, dan layak membaca tiga sebelum menulis yang pertama sendiri.</p> <h2>Header apa yang harus dikirim endpoint yang di-deprecate?</h2> <p>Kirim <code>Deprecation</code>, <code>Sunset</code> dan <code>Link</code> ke penggantinya, di setiap respons dari endpoint yang di-deprecate, sejak hari pengumuman. <a href="https://datatracker.ietf.org/doc/html/rfc9745">Header <code>Deprecation</code></a> membawa tanggal deprecation berlaku efektif; <a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code></a> membawa tanggal endpoint berhenti merespons; <code>Link: <url>; rel="successor-version"</code> menunjuk ke apa yang digunakan sebagai gantinya.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>Kebanyakan pemanggil tidak akan pernah membaca header itu sendiri. Nilainya adalah bahwa klien HTTP, gateway atau pemantauan milik pemanggil bisa, yang mengubah deprecation Anda menjadi peringatan di sisi mereka alih-alih halaman di sisi Anda. SDK yang Anda kirimkan seharusnya mencatat peringatan ketika melihat satu.</p> <h2>Siapa yang diberi tahu, dan bagaimana Anda tahu?</h2> <p>Ini langkah yang menentukan apakah sunset itu tenang atau menjadi insiden dukungan, dan ini yang paling sulit dilakukan hanya dengan changelog. Entri changelog memberi tahu semua orang yang membaca changelog. Deprecation harus mencapai orang-orang spesifik yang kodenya akan gagal, dan cara biasa menemukan mereka adalah data penggunaan yang sama yang dibutuhkan pengingat di tengah jalan: kunci API, aplikasi atau akun yang memanggil perilaku yang di-deprecate baru-baru ini.</p> <p>Lingkaran yang kami jalankan: entri disusun dari pull request yang menambahkan deprecation, seseorang meninjau kata-kata dan tanggalnya, dan setelah diterbitkan entri itu sendiri adalah notifikasinya. Siapa pun yang masukan widget-nya tentang masalah itu, atau permintaan penggantinya, menjadi issue GitHub yang ditutup oleh pull request tersebut mendapat komentar di issue itu yang mengatakan itu sudah dirilis, dengan tautan ke entrinya. <a href="https://changeloop.dev/docs">Feed dan widget</a> melayani entri yang sama kepada semua orang lainnya, bersama setiap entri lain di <a href="https://changeloop.dev/blog/id/api-changelog/">changelog API</a>. Yang tidak kami lakukan adalah membiarkan deprecation menjadi "dirilis" sebelum seseorang menerbitkannya; pemberitahuan dengan tanggal yang salah lebih buruk daripada tidak ada pemberitahuan.</p> <p>Apa pun alat Anda, pertanyaan yang harus bisa Anda jawab pada hari sunset adalah: pemanggil mana yang masih menggunakan ini minggu lalu, dan yang mana dari mereka yang kami beri tahu langsung? Jika jawabannya "kami memposting tentang itu", sunset-nya belum siap.</p> <h2>Apa perbedaan antara men-deprecate dan memversikan?</h2> <p>Memversikan adalah bagaimana Anda menjaga perilaku lama tetap tersedia sementara yang baru ada; deprecation adalah bagaimana Anda mempensiunkan yang lama. Versi API baru tanpa kebijakan deprecation untuk yang sebelumnya adalah komitmen untuk menjalankan keduanya selamanya. Deprecation tanpa versi adalah <a href="https://changeloop.dev/blog/id/breaking-changes/">breaking change</a> dengan penundaan. Anda membutuhkan keduanya, dan versi adalah bagian yang lebih mudah. GraphQL adalah pengecualian yang layak disebut: biasanya tidak ada nomor versi sama sekali untuk dinaikkan, dan <a href="https://changeloop.dev/blog/id/graphql-schema-deprecation/">deprecation skema GraphQL</a> membahas bagaimana satu skema bersama mempensiunkan field dengan directive sebagai gantinya.</p> <h2>FAQ</h2> <p><strong>Haruskah endpoint yang di-deprecate terus berfungsi persis seperti sebelumnya?</strong> Ya, hingga tanggal sunset. Satu-satunya perubahan yang diizinkan adalah header yang ditambahkan dan, mendekati akhir, brownout terjadwal yang Anda umumkan sebelumnya.</p> <p><strong>Kode status apa yang harus dikembalikan endpoint yang dipensiunkan?</strong> <code>410 Gone</code>, dengan badan dan header <code>Link</code> yang menunjuk ke penggantinya dan entri changelog. <code>404</code> mengatakan URL-nya tidak pernah ada, yang salah dan tidak membantu.</p> <p><strong>Bisakah periode deprecation dipersingkat?</strong> Hanya untuk keamanan. Jika perilaku lama bisa dieksploitasi, katakan begitu, persingkat periodenya, dan beri tahu setiap pemanggil yang terdampak secara langsung alih-alih mengandalkan changelog.</p> <p><strong>Perlukah saya men-deprecate sebuah field, atau hanya seluruh endpoint?</strong> Field, parameter, nilai enum, default dan header semuanya membutuhkan perlakuan yang sama, karena masing-masing bisa merusak pemanggil yang benar. Field yang dihapus adalah deprecation paling umum dan paling sering dilewati.</p> </article> <article> <h1>Praktik terbaik versi API, demi kepentingan pemanggil</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Versi API adalah praktik menjaga kontrak lama tetap berfungsi setelah Anda mengubahnya, sehingga pemanggil bisa maju sesuai jadwal mereka sendiri alih-alih jadwal Anda. Kalimat itu berisi dua keputusan yang penting: apa yang terhitung sebagai mengubah kontraknya, dan berapa lama yang lama tetap berfungsi. Di mana nomor versi berada, yang menjadi topik kebanyakan perdebatan versi, adalah yang paling tidak penting dari ketiganya dan paling mudah dibenarkan.</p> <h2>Kapan sebuah API seharusnya diversikan?</h2> <p>Versikan API hanya ketika sebuah perubahan akan merusak pemanggil yang benar. Perubahan aditif, field baru, endpoint baru, parameter opsional baru, tidak membutuhkan versi; pemanggil yang ditulis terhadap kontrak lama tetap berfungsi dan kemampuan baru itu ada begitu saja. Sebuah <a href="https://changeloop.dev/blog/id/breaking-changes/">breaking change</a> membutuhkannya, karena alternatifnya adalah pemanggil mengetahuinya dari error. Memversikan setiap rilis, termasuk yang aditif, mengajarkan pemanggil bahwa versi adalah kebisingan, dan mereka berhenti membaca pemberitahuan yang penting.</p> <p>Tes praktisnya sama dengan artikel tentang breaking change: jika pemanggil yang hanya mengandalkan perilaku terdokumentasi harus mengubah sesuatu untuk tetap berfungsi, perubahan itu membutuhkan versi. Jika tidak, rilis di bawah versi saat ini dan tulis entri changelog.</p> <h2>Skema versi API mana yang seharusnya digunakan?</h2> <p>Gunakan skema yang paling mudah dilihat dan ditetapkan pemanggil Anda, yang untuk kebanyakan API publik adalah versi di jalur URL atau header versi bertanggal. Empat skema umum berbeda lebih sedikit dalam kemampuan daripada dalam apa yang mereka minta dari pemanggil, dan itu dasar yang tepat untuk memilih.</p> <table> <thead> <tr> <th>Skema</th> <th>Contoh</th> <th>Yang harus dilakukan pemanggil</th> <th>Siapa yang menggunakan</th> </tr> </thead> <tbody><tr> <td>Jalur URL</td> <td><code>/v2/invoices</code></td> <td>Mengubah URL saat bermigrasi</td> <td>Kebanyakan API REST publik</td> </tr> <tr> <td>Header versi</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Mengirim header, atau menerima default</td> <td>GitHub</td> </tr> <tr> <td>Versi akun bertanggal</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Menetapkan tanggal per permintaan atau per akun</td> <td>Stripe</td> </tr> <tr> <td>Parameter query</td> <td><code>/invoices?version=2</code></td> <td>Menambahkan parameter</td> <td>API lama; sekarang jarang dipilih</td> </tr> <tr> <td>Media type</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Bernegosiasi jenis konten</td> <td>Purist; sedikit pemanggil bisa mengelola</td> </tr> </tbody></table> <p><strong>Jalur URL</strong> paling terlihat dan paling tidak fleksibel. Setiap pemanggil bisa melihat versi mereka dengan membaca baris log, dan lompatan versi adalah cari-dan-ganti. Biayanya: seluruh permukaan bergerak sekaligus, Anda tidak bisa mengubah kontrak satu endpoint tanpa mencetak versi baru untuk semuanya, jadi versi jalur cenderung jarang dan besar.</p> <p><strong>Header versi</strong> menjaga URL tetap stabil dan membiarkan server memilih default untuk pemanggil yang tidak mengirim apa pun, seperti cara kerja <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versi API REST GitHub</a>: versi bernama tanggal dalam <code>X-GitHub-Api-Version</code>, dengan versi yang didukung tertua sebagai default agar pemanggil tanpa versi tidak rusak. Biayanya: versinya tidak terlihat dalam URL dan mudah dilupakan dalam klien baru.</p> <p><strong>Versi akun bertanggal</strong> adalah skema header ditambah satu tambahan: versinya disimpan terhadap akun, sehingga setiap permintaan mendapatkannya tanpa mengirim apa pun. <a href="https://docs.stripe.com/api/versioning">Versi API Stripe</a> menetapkan setiap akun ke versi saat dibuat dan membiarkan permintaan menimpanya dengan <code>Stripe-Version</code>. Ini skema paling ramah pemanggil dan paling banyak pekerjaan untuk dijalankan, karena server harus menerjemahkan antara setiap versi yang didukung dan yang saat ini. Skema Stripe adalah contoh paling terkenal dari pendekatan tanggal, dan <a href="https://changeloop.dev/blog/id/stripe-api-versioning/">cara Stripe memberi versi pada API-nya</a> membahasnya langkah demi langkah.</p> <p><strong>Parameter query</strong> dan <strong>media type</strong> keduanya berfungsi dan keduanya gagal dalam tes visibilitas dengan cara berbeda: parameter query mudah hilang saat membangun URL, dan versi media type tidak terlihat oleh hampir semua alat yang digunakan pemanggil untuk debug.</p> <h2>Bagaimana versi API dilakukan dalam praktik?</h2> <p>Dalam praktik versi adalah kumpulan perilaku bernama, dan server memetakan setiap permintaan ke salah satunya. Langkah-langkahnya sama apa pun skema yang membawa namanya.</p> <ol> <li><strong>Namai versi berdasarkan tanggal atau bilangan bulat, bukan versi semantik.</strong> API web bukan paket. Pemanggil tidak bisa menetapkan versi minor dari URL, jadi <code>v2</code> atau <code>2026-08-26</code> mengatakan semua yang dibutuhkan pemanggil, dan <a href="https://semver.org/">versi semantik</a> menyiratkan janji kompatibilitas yang tidak bisa dipenuhi skema tersebut.</li> <li><strong>Jaga versinya di luar jalur kode yang tidak peduli.</strong> Versi seharusnya memilih lapisan terjemahan di tepi, bukan mencabangkan logika bisnis. Dua salinan penuh dari kode basis adalah bagaimana versi berakhir tidak terpelihara.</li> <li><strong>Beri setiap versi default dan dokumen.</strong> Pemanggil yang tidak mengirim versi mendapat yang paling lama didukung, tidak pernah yang terbaru, sehingga klien yang tidak ditetapkan tidak rusak pada hari rilis. Setiap versi punya halaman yang mengatakan apa yang berubah dari yang sebelumnya.</li> <li><strong>Tetapkan jendela dukungan dan terbitkan.</strong> Panduan versioning Google, <a href="https://google.aip.dev/185">AIP-185</a>, meminta masa transisi yang wajar dan dikomunikasikan dengan baik, serta merekomendasikan 180 hari bahkan untuk fungsionalitas beta. Pilih jendela, tulis, dan terapkan tanpa negosiasi ulang per versi.</li> <li><strong>Pensiunkan versi seperti Anda mempensiunkan endpoint.</strong> Versi yang melewati jendelanya mendapat perlakuan yang sama dengan <a href="https://changeloop.dev/blog/id/api-deprecation/">API yang di-deprecate</a>: sebuah pengumuman, header <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) di setiap respons, pengingat di tengah jalan kepada pemanggil yang tersisa, dan tanggal penghapusan yang dipegang teguh.</li> </ol> <h2>Apa itu v1 dan v2 dalam API REST?</h2> <p><code>v1</code> dan <code>v2</code> adalah nama untuk dua kontrak yang didukung server yang sama pada saat bersamaan. <code>v2</code> ada karena sesuatu di <code>v1</code> tidak bisa diubah tanpa merusak pemanggilnya, jadi perubahannya masuk ke kontrak baru dan yang lama tetap berfungsi. Angka-angka itu tidak menyiratkan bahwa <code>v2</code> lengkap atau <code>v1</code> mati; keduanya hanya benar jika dokumentasi mengatakannya. <code>v3</code> yang muncul setiap kuartal adalah tanda bahwa perubahan aditif sedang diversikan, atau bahwa kontraknya tidak pernah dirancang untuk menyerap perubahan. gRPC menyelesaikan masalah yang sama secara berbeda: <a href="https://changeloop.dev/blog/id/grpc-protobuf-api-changes/">perubahan API gRPC dan Protobuf</a> membahas versi lewat nama paket dalam berkas <code>.proto</code> alih-alih jalur URL, dan format wire di mana mengganti nama field gratis tapi menomorinya ulang adalah breaking change yang tidak akan dikenali pemanggil REST mana pun sebagai berisiko.</p> <h2>Apa yang harus diumumkan perubahan versi?</h2> <p>Perubahan versi harus mengumumkan apa yang rusak, siapa yang terdampak, cara bermigrasi, dan berapa lama versi sebelumnya tetap berfungsi. Entrinya punya bentuk yang sama dengan entri breaking change lainnya, ditambah satu baris menyatakan jendela dukungan. Berikut satu untuk API yang diversikan dengan header:</p> <blockquote> <p><strong>Versi API 2026-11-01 tersedia. Versi 2025-06-15 didukung hingga 1 November 2027.</strong> Baru di 2026-11-01: <code>GET /invoices</code> mengembalikan <code>amount</code> dalam unit terkecil sebagai bilangan bulat alih-alih string desimal, dan field yang di-deprecate <code>customer_name</code> dihapus demi objek <code>customer</code>. Memengaruhi pemanggil di 2025-06-15 yang mengurai <code>amount</code> sebagai string, yang merupakan default untuk klien tidak ditetapkan yang dibuat sebelum Juni 2025. Migrasi: uraikan <code>amount</code> sebagai bilangan bulat dan baca namanya dari <code>customer.name</code>. Tetapkan <code>X-Api-Version: 2026-11-01</code> saat Anda siap. Tidak ada yang berubah untuk pemanggil yang tidak menetapkan versi.</p> </blockquote> <p>Kalimat terakhir itu yang memungkinkan kebanyakan pembaca berhenti membaca, dan itu milik setiap pengumuman versi. Halaman <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> menyertakan entri dari API yang memversikan seperti ini, dan perbedaan antara yang baik dan sisanya sebagian besar ada di kalimat terakhir itu.</p> <h2>Siapa yang diberi tahu ketika versi berubah?</h2> <p>Semua orang di versi lama, secara individu, dan changelog untuk semua orang lainnya. Perubahan versi adalah satu-satunya kasus di mana "kami memposting tentang itu" dijamin akan melewatkan tepat pemanggil yang penting: mereka yang menetapkan versi dua tahun lalu dan belum membaca catatan rilis sejak itu. Data penggunaan menjawab siapa mereka; pemberitahuannya harus mencapai mereka di mana kode mereka berada, dalam header respons dan dalam pesan kepada pemilik akun.</p> <p>Dalam lingkaran yang kami jalankan, entri yang mengumumkan versi disusun dari pull request yang merilisnya, ditinjau oleh seseorang, dan diterbitkan di <a href="https://changeloop.dev/docs">feed dan widget</a>, tempat klien berversi bisa membacanya sebagai JSON. Siapa pun yang masukan widget-nya meminta perubahan itu, atau melaporkan bug yang diselesaikannya, dan menjadi issue GitHub yang ditutup oleh pull request, diberi tahu di issue tersebut segera setelah entrinya live. Mekanismenya sama dengan entri mana pun; lompatan versi hanyalah entri dengan taruhan tertinggi.</p> <h2>FAQ</h2> <p><strong>Haruskah setiap perubahan API mendapat versi baru?</strong> Tidak. Hanya breaking change. Perubahan aditif dirilis di bawah versi saat ini dengan entri changelog. Memversikan perubahan aditif melatih pemanggil untuk mengabaikan versi.</p> <p><strong>Apakah versi URL lebih baik daripada versi header?</strong> Versi URL lebih mudah dilihat pemanggil dan lebih sulit bagi Anda untuk berkembang sedikit demi sedikit; versi header sebaliknya. Untuk API publik dengan banyak klien kecil, versi URL gagal lebih sedikit. Untuk API besar dengan lapisan terjemahan, versi bertanggal berbasis header berskala lebih baik.</p> <p><strong>Berapa banyak versi yang seharusnya didukung sekaligus?</strong> Sesedikit yang diizinkan jendela dukungan Anda, dan tidak pernah jumlah tak terbatas. Dua atau tiga versi bersamaan itu normal; lebih dari itu biasanya berarti versi tidak dipensiunkan.</p> <p><strong>Apa yang seharusnya diterima permintaan tanpa versi?</strong> Versi yang paling lama didukung, sehingga klien yang ada dan tidak ditetapkan tetap berfungsi, dengan header respons yang memberi tahu mereka versi mana yang mereka terima.</p> </article> <article> <h1>Breaking change: apa yang terhitung dan cara merilisnya</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Breaking change adalah perubahan yang tidak bisa dilalui pemanggil yang ditulis dengan benar. Definisi ini penting karena kebanyakan perdebatan tentang apakah sesuatu "terhitung" sebenarnya adalah perdebatan tentang siapa yang salah pegang. Jika pemanggil mengikuti dokumentasi Anda dan perubahan Anda membuat kodenya berhenti bekerja, perubahan itu breaking. Apa yang Anda maksudkan tidak ada hubungannya dengan itu.</p> <p>Itu seluruh tesnya. Sisa artikel ini adalah apa yang muncul darinya: apa yang gagal tes, apa yang lolos, cara menangkap kegagalan sebelum di-merge, dan apa yang harus dilakukan begitu Anda tahu sedang merilis satu.</p> <h2>Apa yang terhitung sebagai breaking change?</h2> <p>Terapkan tes ke pemanggil, bukan ke diff. Perubahan bersifat breaking ketika pemanggil yang hanya mengandalkan perilaku terdokumentasi harus mengubah kode, konfigurasi atau datanya untuk tetap berfungsi. Menghapus field, mengganti nama endpoint, memperketat validasi, mengubah default dan mengubah jenis nilai semuanya memenuhi syarat. Menambahkan field opsional tidak. Memperbaiki bug biasanya tidak, dengan satu pengecualian penting di bawah.</p> <table> <thead> <tr> <th>Perubahan</th> <th>Breaking?</th> <th>Mengapa</th> </tr> </thead> <tbody><tr> <td>Menghapus atau mengganti nama field, endpoint, flag atau opsi</td> <td>Ya</td> <td>Pemanggil yang benar merujuknya</td> </tr> <tr> <td>Menambahkan field opsional atau endpoint baru</td> <td>Tidak</td> <td>Panggilan yang ada tidak berubah</td> </tr> <tr> <td>Membuat input opsional menjadi wajib</td> <td>Ya</td> <td>Panggilan yang melewatkannya sekarang gagal</td> </tr> <tr> <td>Memperketat validasi yang sebelumnya diterima</td> <td>Ya</td> <td>Input yang berhasil sekarang ditolak</td> </tr> <tr> <td>Mengubah nilai default</td> <td>Ya</td> <td>Pemanggil yang tidak mengaturnya mendapat perilaku baru</td> </tr> <tr> <td>Mengubah jenis (string ke angka, nilai tunggal ke array)</td> <td>Ya</td> <td>Parser yang ditulis untuk jenis terdokumentasi gagal</td> </tr> <tr> <td>Mengurutkan ulang kunci sebuah objek</td> <td>Tidak</td> <td>Kecuali Anda mendokumentasikan urutannya</td> </tr> <tr> <td>Memperbaiki bug yang diandalkan pemanggil</td> <td>Praktiknya ya</td> <td>Lihat bagian tentang kontrak tak sengaja</td> </tr> <tr> <td>Menaikkan batas laju atau batas ukuran</td> <td>Tidak</td> <td>Tidak ada yang berhasil berhenti berfungsi</td> </tr> <tr> <td>Menurunkan batas laju atau batas ukuran</td> <td>Ya</td> <td>Lalu lintas yang baik-baik saja sekarang dibatasi</td> </tr> <tr> <td>Mengubah kata-kata pesan error</td> <td>Tergantung</td> <td>Breaking jika Anda mendokumentasikannya atau pemanggil mencocokkan itu</td> </tr> </tbody></table> <h2>Apa yang bukan breaking change?</h2> <p>Perubahan bersifat non-breaking ketika setiap panggilan yang berhasil sebelumnya tetap berhasil, tanpa berubah, dan tetap bermakna sama. Menambahkan endpoint baru, menambahkan parameter permintaan opsional, menambahkan field ke respons, membuat input wajib menjadi opsional, menaikkan batas dan memperbaiki pesan error yang tidak dicocokkan siapa pun semuanya lolos tes. Perubahan aditif ini bisa dirilis dalam rilis minor dengan entri changelog biasa.</p> <p>Perubahan aditif tetap bisa merusak pemanggil dalam tiga situasi. Klien yang deserializer-nya menolak field tak dikenal gagal pada field respons baru pertama, jadi dokumentasikan sejak awal bahwa pemanggil harus mengabaikan field yang tidak mereka kenali. Nilai enum baru merusak setiap pemanggil dengan switch yang menyeluruh (lebih lanjut di bawah). Dan respons yang membesar bisa mendorong pemanggil melewati batas ukuran, timeout atau lebar kolom yang tidak pernah harus mereka pikirkan.</p> <p>Empat baris tabel layak dilihat lebih dekat, karena di situlah ketidaksepakatan terjadi.</p> <h2>Empat breaking change yang terlewat tim</h2> <p><strong>Kontrak tak sengaja.</strong> Jika API Anda telah mengembalikan field yang sama, tidak terdokumentasi, selama tiga tahun, seorang pemanggil telah membangun di atasnya. <a href="https://www.hyrumslaw.com/">Hukum Hyrum</a> adalah versi singkatnya: dengan cukup banyak pengguna, setiap perilaku yang bisa diamati dari sistem Anda akan diandalkan seseorang. Itulah mengapa "itu perbaikan bug" bukan pembelaan. Perbaikannya mungkin benar dan tetap saja breaking. Rilis itu sebagai satu.</p> <p><strong>Perubahan perilaku tanpa perubahan skema.</strong> Field-nya masih ada, jenisnya sama, dan nilainya sekarang berarti sesuatu yang berbeda. <code>status</code> yang dulunya <code>active</code> atau <code>inactive</code> dan sekarang juga mengembalikan <code>suspended</code> merusak setiap pemanggil dengan switch yang menyeluruh. Timestamp yang pindah dari waktu lokal ke UTC merusak siapa pun yang tidak membaca dokumen dua kali. Tidak ada di diff berkas OpenAPI yang menunjukkan ini.</p> <p><strong>Validasi yang diperketat.</strong> Anda mulai menolak email tanpa TLD, atau spasi di akhir, atau nama lebih dari 80 karakter. Setiap pemanggil yang mengirim tepat itu sekarang mendapat 400 untuk permintaan yang berhasil minggu lalu. Perubahan validasi adalah yang paling umum dirilis sebagai perbaikan "pengerasan".</p> <p><strong>Default yang berubah.</strong> Tidak ada yang menyetel nilai secara eksplisit yang menyadari apa pun. Semua yang tidak melakukannya, yang merupakan kebanyakan pemanggil, mendapat perilaku baru tanpa mengubah satu baris pun. Default yang berubah merusak mayoritas pengguna Anda tepatnya karena mereka tidak pernah melihat pengaturannya.</p> <h2>Bagaimana cara mendeteksi breaking change sebelum dirilis?</h2> <p>Bandingkan kontrak pada pull request dengan kontrak pada branch utama, di CI, dan gagalkan build jika ada perbedaan yang breaking. Alat diff skema tersedia untuk sebagian besar format antarmuka, dan masing-masing tahu aturan breaking dari formatnya sendiri:</p> <table> <thead> <tr> <th>Antarmuka</th> <th>Alat</th> <th>Yang dibandingkan</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Dua spesifikasi OpenAPI, dengan laporan breaking change</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>Berkas <code>.proto</code>, pada tingkat wire atau sumber</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Dua skema, menandai perubahan breaking dan berbahaya</td> </tr> <tr> <td>Crate Rust</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>API publik terhadap versi terbitan terakhir</td> </tr> <tr> <td>Paket TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Laporan API publik paket yang di-commit</td> </tr> </tbody></table> <p>Alat-alat ini menangkap field yang dihapus, operasi yang diganti nama dan jenis yang berubah dengan andal. Mereka tidak bisa melihat dua jenis pertama dari empat di atas, kontrak tak sengaja atau perubahan perilaku, karena keduanya tidak muncul di skema. Gunakan alatnya untuk menghentikan yang jelas dan pertanyaan tinjauan "bisakah pemanggil yang benar menyadari ini?" untuk sisanya. Job CI yang sama adalah tempat alami untuk mewajibkan entri changelog, seperti dijelaskan di <a href="https://changeloop.dev/blog/id/changelog-ci-enforcement/">menegakkan entri changelog di CI</a>, dan <a href="https://changeloop.dev/blog/id/grpc-protobuf-api-changes/">perubahan API gRPC dan Protobuf</a> membahas kasus tingkat wire.</p> <h2>Bagaimana cara menandai breaking change di commit?</h2> <p>Dengan <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, breaking change ditandai dengan <code>!</code> sebelum titik dua (<code>feat(api)!: remove the legacy export endpoint</code>) atau dengan footer yang diawali <code>BREAKING CHANGE:</code> diikuti deskripsi. Keduanya dipetakan ke versi major. Tulis footer sebagai draf pertama entri changelog, dengan menyebut siapa yang terdampak dan apa yang harus mereka lakukan. <a href="https://changeloop.dev/blog/id/conventional-commits-changelog/">Conventional commits dan changelog</a> membahas sejauh mana konvensi itu membantu Anda.</p> <p>Aturan yang sama berlaku untuk pustaka. Fungsi publik yang dihapus, jenis parameter yang dipersempit atau nilai kembalian yang berubah adalah versi major di bawah versi semantik. Pustaka tidak selalu mengikutinya: sebuah <a href="https://arxiv.org/abs/2110.07889">studi atas 119.879 peningkatan versi di Maven Central</a> menemukan 16,6% melanggar versi semantik, namun hanya 7,9% proyek klien yang terdampak, karena sebagian besar perubahan itu menyentuh kode yang tidak dipanggil klien mana pun. Kerusakan diukur di pemanggil.</p> <h2>Bagaimana cara merilis breaking change?</h2> <p>Anda merilisnya secara terbuka, dengan tanggal, dengan jalur. Langkah-langkah di bawah ini berurutan, dan yang terakhir adalah yang paling sering dilewati tim: memberi tahu orang yang terdampak bahwa hal yang mereka tunggu sekarang telah terjadi.</p> <ol> <li><strong>Putuskan apakah itu satu.</strong> Gunakan tes di atas, bukan diff. Jika dua insinyur tidak sepakat, itu breaking; ketidaksepakatan itu bukti bahwa pemanggil bisa saja secara wajar mengandalkan perilaku lama.</li> <li><strong>Versikan.</strong> Di bawah <a href="https://semver.org/">versi semantik</a> breaking change adalah versi major. Jika Anda menjalankan API bertanggal atau berversi, itu masuk ke versi baru dan yang lama tetap berfungsi hingga tanggal yang dinyatakan. Jika Anda tidak bisa memversi, Anda tidak merilis breaking change, Anda merilis gangguan dengan entri changelog. Skema mana yang membawa versinya adalah subjek dari <a href="https://changeloop.dev/blog/id/api-versioning-best-practices/">praktik terbaik versi API</a>.</li> <li><strong>Tulis entri sebelum kode di-merge.</strong> Entri punya bentuk tetap: apa yang berubah, siapa yang terdampak, apa yang harus mereka lakukan, dan sampai kapan. Jika Anda tidak bisa mengisi keempatnya, perubahan belum siap. <a href="https://changeloop.dev/release-notes-template">Template release notes</a> meletakkan entri ini pertama, dengan tanggal alih-alih nomor versi, tepatnya karena ini.</li> <li><strong>Berikan tenggat waktu, bukan nomor rilis.</strong> "Dihapus di v5" tidak berarti apa-apa bagi yang tidak melacak rilis Anda. "Berhenti berfungsi pada 1 November 2026" berarti hal yang sama untuk semua orang.</li> <li><strong>Sediakan migrasinya.</strong> Contoh kode dari panggilan lama di samping yang baru. Jika perubahannya adalah penggantian nama, sebutkan kedua nama di kalimat yang sama. Jika field yang dihapus, katakan ke mana datanya pergi.</li> <li><strong>Umumkan di mana pun perilaku lama didokumentasikan.</strong> Changelog, halaman dokumen yang menjelaskan endpoint, release notes SDK, dan header deprecation di respons jika Anda punya satu.</li> <li><strong>Tutup lingkarannya.</strong> Jika pelanggan meminta perubahan, atau melaporkan bug yang menyebabkannya, beri tahu mereka saat dirilis.</li> </ol> <h2>Seperti apa entri breaking change yang baik?</h2> <p>Entri yang baik menyebutkan pemanggil yang terdampak di baris pertama, menyatakan tanggalnya, dan menyertakan perbaikannya. Berikut satu untuk kasus validasi yang diperketat, dalam bentuk yang kami gunakan:</p> <blockquote> <p><strong>Alamat email tanpa domain ditolak mulai 1 November 2026.</strong> <code>POST /users</code> dan <code>PATCH /users/:id</code> saat ini menerima nilai <code>email</code> seperti <code>alice@localhost</code>. Mulai 1 November, ini mengembalikan <code>400 invalid_email</code>. Memengaruhi integrasi mana pun yang membuat pengguna dari direktori internal. Migrasi: kirim alamat yang sepenuhnya memenuhi syarat, atau lewatkan field-nya dan atur kemudian. Tidak perlu perubahan jika alamat Anda sudah punya domain, yang berlaku untuk 99,4% akun yang dibuat tahun ini.</p> </blockquote> <p>Di mana pemberitahuan ini seharusnya berada, dan apa lagi yang seharusnya menyertainya, dibahas di <a href="https://changeloop.dev/blog/id/api-changelog/">changelog API</a>.</p> <p>Persentase di akhir bukan hiasan. Itu memberi tahu pembaca apakah mereka harus khawatir, yang merupakan pertanyaan saat mereka membuka entri.</p> <h2>Mengapa tidak menghindarinya saja?</h2> <p>Karena alternatifnya lebih buruk. API yang tidak pernah merusak apa pun menumpuk setiap kesalahan yang pernah dibuatnya: field yang salah nama, default yang salah, timestamp dalam waktu lokal. Masing-masing adalah pajak bagi setiap pemanggil baru selamanya, untuk melindungi pemanggil yang bisa saja bermigrasi dalam satu sore. Tim dengan reputasi stabilitas terbaik merusak sesuatu jarang, sesuai jadwal, dengan jalur migrasi dan peringatan yang mencapai orang-orang yang dituju.</p> <p>Mekanisme peringatan itu dibahas di <a href="https://changeloop.dev/blog/id/api-deprecation/">men-deprecate API</a>. Entri itu sendiri disusun seperti entri lain mana pun di <a href="https://changeloop.dev/docs">feed changelog</a>: dari pull request yang di-merge, ditahan untuk manusia, lalu diterbitkan di tempat pemanggil yang terdampak sudah membaca.</p> <h2>FAQ</h2> <p><strong>Apa perbedaan antara perubahan breaking dan non-breaking?</strong> Perubahan breaking memaksa pemanggil yang benar mengubah kode, konfigurasi atau datanya agar tetap berfungsi. Perubahan non-breaking membiarkan setiap panggilan yang ada tetap berfungsi dengan makna yang sama, itulah mengapa penambahan biasanya aman dan penghapusan, penggantian nama serta aturan yang diperketat biasanya tidak.</p> <p><strong>Apakah menambahkan field wajib terhitung?</strong> Ya. Setiap panggilan yang ada melewatkannya, jadi setiap panggilan yang ada sekarang gagal. Tambahkan sebagai opsional dengan default yang masuk akal, atau versikan endpoint-nya.</p> <p><strong>Apakah perbaikan bug terhitung?</strong> Bisa jadi. Jika pemanggil mengandalkan perilaku yang bug, memperbaikinya merusak mereka, apa pun yang dikatakan dokumentasi. Perlakukan perbaikan apa pun yang mengubah keluaran yang bisa diamati sebagai breaking kecuali Anda bisa menunjukkan tidak ada yang mengandalkannya.</p> <p><strong>Apakah versi semantik berlaku untuk API web?</strong> Aturannya iya: breaking change mendapat versi major baru dan yang lama tetap berfungsi selama periode yang dinyatakan. Nomornya sering berada di URL atau header tanggal alih-alih versi paket.</p> <p><strong>Berapa banyak pemberitahuan yang cukup?</strong> Cukup bagi pemanggil untuk menemukan pemberitahuan dan melakukan pekerjaannya. Sembilan puluh hari adalah batas bawah umum untuk API publik; lebih lama untuk apa pun yang digunakan dalam kode yang dikirim ke pengguna akhir dan tidak bisa diperbarui dari jarak jauh.</p> </article> <article> <h1>Menutup lingkaran umpan balik dari sisi changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Lingkaran umpan balik pelanggan tertutup ketika orang yang memberi umpan balik diberi tahu apa yang terjadi padanya. Bukan saat itu dicatat. Bukan saat diprioritaskan. Bahkan bukan saat dirilis. Saat diberi tahu kepadanya. Kebanyakan tim melakukan tiga langkah pertama dengan baik dan langkah terakhir sama sekali tidak, lalu bertanya-tanya mengapa orang yang mengirim umpan balik berhenti mengirimnya.</p> <p>Artikel ini membahas langkah terakhir itu, dan sebuah klaim konkret: changelog adalah tempat yang tepat untuk menutup lingkaran, karena itu satu-satunya artefak yang sudah ada tepat di saat lingkaran itu bisa ditutup.</p> <h2>Apa itu lingkaran umpan balik pelanggan?</h2> <p>Lingkaran umpan balik pelanggan adalah jalur dari pengguna yang memberi tahu Anda sesuatu hingga pengguna itu mengetahui apa yang Anda lakukan tentang itu. Ada empat langkah: mengumpulkan umpan balik, memutuskan apa yang harus dilakukan dengannya, merilis hasilnya, dan memberi tahu orang yang meminta. Lingkarannya terbuka hingga langkah keempat terjadi. Tim yang mengumpulkan umpan balik dan merilis perbaikan tapi tidak pernah memberi tahu siapa pun punya kotak masuk, bukan lingkaran.</p> <table> <thead> <tr> <th>Langkah</th> <th>Apa yang terjadi</th> <th>Di mana biasanya rusak</th> </tr> </thead> <tbody><tr> <td>Mengumpulkan</td> <td>Umpan balik datang: widget, dukungan, penjualan, wawancara</td> <td>Tidak ada; setiap tim melakukan ini</td> </tr> <tr> <td>Memutuskan</td> <td>Ditriase, digabung dengan duplikat, diterima atau ditolak</td> <td>Penolakan tidak pernah dikomunikasikan</td> </tr> <tr> <td>Merilis</td> <td>Seseorang membangunnya dan menjadikannya live</td> <td>Tautan ke permintaan hilang saat merge</td> </tr> <tr> <td>Memberi tahu</td> <td>Peminta mengetahui itu sudah dirilis</td> <td>Dilewati, atau hanya dilakukan untuk peminta paling berisik</td> </tr> </tbody></table> <p>Baris keempat itulah yang dibahas artikel ini. Rusak karena alasan struktural, bukan budaya: pada saat sebuah fitur dirilis, permintaan yang menyebabkannya hidup di sistem yang berbeda dari hal yang dirilis, dan menghubungkan keduanya bukan tugas siapa pun. Lingkaran itu dimulai lebih awal, dengan cara permintaan diajukan sejak awal; <a href="https://changeloop.dev/blog/id/how-to-ask-for-customer-feedback/">cara meminta umpan balik pelanggan</a> membahas kalimat dan waktunya.</p> <h2>Mengapa lingkaran umpan balik tetap terbuka?</h2> <p>Lingkaran umpan balik tetap terbuka karena permintaan dan perubahan yang dirilis hidup di tempat yang berbeda dan tautan di antara keduanya dibuat secara manual, jika dibuat. Permintaan ada di alat umpan balik, kotak dukungan atau spreadsheet. Perubahannya ada di pull request. Pengumumannya ada di changelog atau email. Tiga sistem, tiga pemilik, dan tautan dari yang ketiga kembali ke yang pertama adalah seseorang yang mengingat, berbulan-bulan kemudian, siapa yang meminta.</p> <p>Ada alasan kedua. Langkah memberi tahu biasanya dibingkai sebagai tugas pemasaran ("mengumumkan fitur") daripada tugas dukungan ("membalas orangnya"). Pengumuman pergi ke semua orang dan tidak mencapai siapa pun secara khusus. Orang yang meminta fitur pada Maret membaca pengumumannya pada Juni, jika mereka membacanya, sebagai berita, bukan sebagai balasan. Lingkarannya hanya tertutup jika pesannya ditujukan kepada mereka.</p> <h2>Mengapa menutup lingkaran dari sisi changelog?</h2> <p>Karena entri changelog adalah satu-satunya artefak yang ada tepat pada momen yang benar, mengandung kata-kata yang tepat, dan ditulis oleh orang yang tepat. Ada saat perubahan itu live dan tidak sebelumnya. Mengatakan apa yang berubah dalam bahasa pembaca, yang merupakan pesan yang dibutuhkan peminta. Dan ditulis oleh seseorang yang baru saja membaca pull request, yang merupakan satu-satunya momen di mana tautan ke permintaan asli masih terlihat.</p> <p>Bandingkan alternatifnya. Menutup lingkaran dari alat umpan balik berarti alat umpan balik perlu tahu kapan fitur dirilis, yang berarti seseorang memperbarui status secara manual. Menutupnya dari pull request berarti memberi tahu pelanggan saat merge, sebelum perubahannya live, sebuah janji yang rusak dengan stempel waktu segera setelah deployment tertunda. Menutupnya dari pengumuman pemasaran berarti menunggu satu, dan kebanyakan perubahan yang dirilis tidak pernah mendapatkannya.</p> <p>Changelog berada di tengah: setelah merge, pada saat rilis, dengan formulasi sudah siap.</p> <h2>Bagaimana lingkarannya tertutup, langkah demi langkah</h2> <p>Ini mekanisme yang kami jalankan. Digambarkan di sini sebagai spesifikasi alih-alih tur produk, karena setiap langkah bisa dilakukan secara manual atau dengan alat lain; yang penting adalah urutannya.</p> <ol> <li><strong>Umpan balik menjadi issue di repositori yang akan memperbaikinya.</strong> Pengiriman widget dicatat sebagai issue GitHub berlabel (<code>feature-request</code> atau <code>bug</code>, satu prioritas, dan <code>from-widget</code>), dengan alamat email pengirim tidak dimasukkan ke badan issue. Issue-nya hidup di sebelah kode, sehingga langkah tiga bisa menemukannya. Issue yang dibuat manual, misalnya dari <a href="https://changeloop.dev/blog/id/feature-request-template/">template permintaan fitur</a>, berada di luar jalur ini: langkah lima tidak mengomentarinya, jadi tutup lingkaran itu sendiri.</li> <li><strong>Perbaikannya merujuk ke issue.</strong> Pull request mengatakan <code>Fixes #142</code>, kata kunci penutupan milik GitHub sendiri. Tidak ada yang baru untuk dipelajari, dan itu kalimat yang sama yang sudah ditulis developer.</li> <li><strong>Entri changelog disusun dari pull request yang di-merge dan membawa tautannya.</strong> Saat merge, draf dibuat dan <code>#142</code> dibaca dari badan PR dan dilampirkan ke draf. Tautannya dibuat selagi masih murah, oleh mesin, dari data yang sudah ada di sana.</li> <li><strong>Seseorang meninjau entrinya.</strong> Formulasi, audiens, apakah itu perlu diterbitkan sama sekali. Draf yang dibuang tidak menutup apa-apa, yang benar: refactor internal yang kebetulan merujuk issue bukanlah berita.</li> <li><strong>Saat disetujui, peminta diberi tahu.</strong> Komentar diterbitkan di issue yang berasal dari umpan baliknya, "Shipped —" diikuti judul entri dan tautan ke entri yang diterbitkan, dan widget menampilkan entri rilis yang sama kepada pengirimnya. Sekali, tidak pernah dua kali, dan hanya setelah seseorang menerbitkan entrinya. Entri yang sama keluar melalui <a href="https://changeloop.dev/docs">feed dan widget</a> ke semua orang yang tidak meminta.</li> </ol> <p>Urutan di langkah lima itulah seluruh desainnya. Memberi tahu peminta saat merge akan lebih awal dan lebih mudah, dan akan salah sekitar sesering deployment tertunda. Feature flag merusak bahkan urutan ini, karena disetujui dan dipublikasikan bisa terjadi sementara fitur itu masih tidak terlihat bagi akun peminta; <a href="https://changeloop.dev/blog/id/feature-flags-feature-requests/">feature flag dan permintaan fitur</a> membahas pemeriksaan tambahan yang dibutuhkan langkah ini begitu ada flag terlibat.</p> <h2>Seperti apa lingkaran tertutup bagi pelanggan?</h2> <p>Terlihat seperti balasan. Pelanggan mengirim permintaan melalui widget, dan suatu hari widget menampilkannya sebagai sudah dirilis, dengan tautan ke entri yang menjelaskannya dalam bahasa mereka; di GitHub, issue-nya menerima kabar yang sama sebagai komentar. Mereka tidak berlangganan newsletter, tidak memeriksa roadmap, tidak mencari di changelog. Mereka diberi tahu.</p> <p>Itulah pengalaman yang membuat potongan umpan balik berikutnya terjadi. Orang mengirim umpan balik ke produk yang membalas. Halaman <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> menyertakan entri dari tim yang penggunanya terlihat terus kembali dengan permintaan, dan benang merahnya bukan alatnya; itu karena entrinya terbaca seperti balasan.</p> <h2>Bagaimana cara mengukur lingkaran umpan balik?</h2> <p>Ukur fraksi perubahan yang dirilis yang memberi tahu setidaknya satu peminta, dan waktu dari rilis hingga pemberitahuan. Dua angka, keduanya mudah begitu tautannya ada dan mustahil sebelumnya.</p> <ul> <li><strong>Tingkat penutupan</strong>: dari entri changelog yang diterbitkan bulan ini, berapa banyak yang menautkan setidaknya satu permintaan, dan dari itu, berapa banyak yang memberi tahu peminta. Jika angka kedua jauh lebih rendah dari yang pertama, notifikasi gagal; jika yang pertama rendah, permintaan tidak dirujuk dari pull request, dan perbaikannya adalah satu kalimat di template PR.</li> <li><strong>Waktu dari rilis hingga pemberitahuan</strong>: berapa lama antara entrinya menjadi live dan pemberitahuan ke peminta. Dengan mekanisme di atas itu detik. Secara manual biasanya minggu, atau tidak pernah, dan "tidak pernah" adalah angka yang penting.</li> </ul> <p>Jangan mengukur lingkaran berdasarkan volume umpan balik yang dikumpulkan. Mengumpulkan adalah langkah mudah, dan tim yang mengukurnya akan mengoptimalkannya, yang menghasilkan lebih banyak lingkaran terbuka.</p> <h2>Di mana roadmap cocok?</h2> <p>Roadmap publik adalah cara menutup lingkaran lebih awal: memberi tahu peminta bahwa permintaan mereka didengar, sebelum dirilis. Ini berguna, dan tidak menggantikan langkah terakhir. "Direncanakan" adalah janji tentang masa depan; "Dirilis" adalah fakta tentang masa kini. Jalankan <a href="https://changeloop.dev/blog/id/public-roadmap/">roadmap publik</a> dari issue yang sama, dengan satu label per kolom, sehingga permintaan yang sama bergerak dari direncanakan ke dirilis tanpa dimasukkan ulang di mana pun. Perpindahan ke dirilis adalah perubahan label (<code>roadmap:shipped</code>) yang tidak dilakukan siapa pun untuk Anda saat entri disetujui, jadi lakukan di tinjauan yang sama.</p> <h2>FAQ</h2> <p><strong>Apa saja empat langkah lingkaran umpan balik pelanggan?</strong> Mengumpulkan, memutuskan, merilis, memberi tahu. Lingkarannya terbuka hingga langkah keempat terjadi. Kebanyakan kerangka kerja menambahkan langkah analisis dan prioritisasi di tengah; itu adalah penyempurnaan dari "memutuskan", dan tidak ada satu pun yang menutup apa pun.</p> <p><strong>Haruskah pelanggan diberi tahu ketika permintaan ditolak?</strong> Ya, dan itu pesan yang paling diabaikan dalam lingkaran. "Kami tidak akan melakukan ini, dan ini alasannya" yang jelas mengakhiri penantian. Kesunyian membiarkan lingkaran terbuka selamanya dan pelanggan terus memeriksa.</p> <p><strong>Bagaimana menutup lingkaran berbeda dari mengumumkan fitur?</strong> Pengumuman pergi ke semua orang. Menutup lingkaran adalah balasan kepada orang-orang yang meminta, di kanal tempat mereka meminta. Lakukan keduanya; ini pesan yang berbeda untuk pembaca yang berbeda.</p> <p><strong>Bagaimana jika peminta tidak ada di GitHub?</strong> Kebanyakan memang tidak, dan itu tidak masalah. Widget terus menampilkan status dari apa yang mereka kirim, termasuk entri yang dirilis dan tautannya, jadi mereka tidak butuh apa pun selain halaman tempat mereka menulis. Komentar di issue ditujukan untuk orang yang bisa melihat repositori.</p> <p><strong>Apakah loop ini bekerja di GitLab atau Bitbucket, bukan GitHub?</strong> Widget dan changelog bekerja; komentar otomatis di langkah lima belum, untuk saat ini. Tim di GitLab atau Bitbucket tetap mendapat setiap pengiriman, tetap mencatatnya sebagai issue, dan tetap menampilkan status ke peminta di widget, tapi menutup loop spesifik itu kembali ke issue itu sendiri adalah langkah yang Anda lakukan secara manual sampai integrasi itu ada.</p> </article> <article> <h1>Template permintaan fitur yang menjadi changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Template permintaan fitur adalah formulir dengan empat pertanyaan: apa yang sedang dicoba dilakukan orang tersebut, apa yang menghalanginya, apa yang dicobanya sebagai gantinya, dan bagaimana dia ingin diberi tahu saat selesai. Semua yang lain yang biasanya muncul di formulir tersebut, pemilih prioritas, estimasi usaha, skor nilai bisnis, ditujukan untuk tim yang menerima permintaan, dan diisi dengan salah oleh yang mengirimnya.</p> <p>Permintaan yang rapi adalah tes yang salah untuk sebuah template. Yang benar: enam bulan kemudian, saat fiturnya dirilis, bisakah seseorang menemukan permintaannya, memahaminya, dan memberi tahu orang yang menulisnya? Kebanyakan template dirancang untuk penerimaan. Ini dirancang untuk hari lingkarannya ditutup.</p> <h2>Apa yang harus dicakup template permintaan fitur?</h2> <p>Harus mencakup tujuan, penghalang, solusi sementara, dan cara kembali ke peminta. Empat kolom, dalam urutan itu, masing-masing menjawab pertanyaan yang akan ditanyakan tim nanti.</p> <table> <thead> <tr> <th>Kolom</th> <th>Pertanyaan yang dijawab nanti</th> <th>Mengapa ada di formulir</th> </tr> </thead> <tbody><tr> <td>Apa yang kamu coba lakukan?</td> <td>Apakah fitur yang dibangun itu yang dibutuhkan?</td> <td>Tujuan bertahan lebih lama dari proposal konkret mana pun</td> </tr> <tr> <td>Apa yang menghalangimu hari ini?</td> <td>Seperti apa "selesai" itu?</td> <td>Menyebutkan celahnya tanpa menentukan perbaikannya</td> </tr> <tr> <td>Apa yang kamu lakukan sebagai gantinya?</td> <td>Seberapa mendesak ini sebenarnya?</td> <td>Solusi sementara yang menyakitkan adalah sinyal yang lebih kuat daripada pemilih prioritas</td> </tr> <tr> <td>Bagaimana kami harus memberitahumu?</td> <td>Siapa yang menerima pesan "dirilis"?</td> <td>Kolom yang paling sering dilewatkan template</td> </tr> </tbody></table> <p>Yang dengan sengaja hilang: solusi yang diusulkan sebagai kolom wajib (diterima sebagai komentar, salah sebagai kerangka), pemilih prioritas (semua yang mengirim memilih tinggi), dan estimasi usaha atau nilai apa pun (tugas tim, setelah triase). Template yang meminta solusi mendapatkan permintaan untuk tombol; template yang meminta tujuan mendapatkan permintaan untuk hasil, dan tentang hasil itulah entri changelog ditulis.</p> <h2>Templatenya</h2> <p>Ini template issue GitHub yang kami gunakan, sebagai formulir. Tempel ke <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> dan itu akan dirender sebagai formulir terstruktur di halaman issue baru. Permintaan yang diajukan melaluinya mendarat sebagai issue dengan kolom yang sama dengan yang diajukan dari widget umpan balik, yang penting untuk bagian berikutnya.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Dua detail melakukan pekerjaannya. <code>labels: ["feature-request"]</code> berarti permintaan diklasifikasi saat dibuat alih-alih menunggu seseorang mentriasenya. Dan kolom terakhir ada karena "kami akan memberi tahumu" adalah janji, dan janji butuh alamat.</p> <h2>Label apa yang harus dibawa permintaan fitur?</h2> <p>Permintaan fitur harus membawa satu label untuk apa itu, satu untuk seberapa mendesak, dan satu untuk dari mana asalnya. Tiga label, tiga sumbu, dan masing-masing dibaca oleh pembaca yang berbeda.</p> <table> <thead> <tr> <th>Label</th> <th>Nilai</th> <th>Siapa yang membacanya</th> </tr> </thead> <tbody><tr> <td>Jenis</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Yang memutuskan antrean mana yang dimasukinya</td> </tr> <tr> <td>Prioritas</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Yang merencanakan siklus berikutnya</td> </tr> <tr> <td>Sumber</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Yang mengukur dari mana permintaan berasal</td> </tr> </tbody></table> <p>Widget menerapkan dua sumbu pertama dan <code>from-widget</code> saat mengajukan pengiriman sebagai issue; <code>from-form</code> dan <code>from-support</code> adalah saran untuk permintaan yang datang lewat jalur lain. Label widget adalah: jenis (<code>bug</code> atau <code>feature-request</code>, diputuskan pengklasifikasi hanya dari pesannya), prioritas (laporan kerusakan yang tenang dan spesifik adalah tinggi; duplikat dari sesuatu yang sudah ditanyakan adalah rendah; apa pun yang bahkan mengisyaratkan masalah keamanan adalah <code>bug</code> dan tinggi, apa pun kata-katanya), dan <code>from-widget</code>. Ketiga sumbu yang sama berlaku untuk permintaan yang datang secara manual melalui template di atas, dan itulah intinya: permintaan adalah permintaan, di mana pun ia masuk.</p> <p>Satu konvensi lagi: widget menghapus alamat email pengirim dari badan issue sebelum mengajukannya, karena issue-nya hidup di repositori yang mungkin publik, dan menggantinya dengan referensi pengiriman. Alamatnya tetap di luar issue; pengirim mengikuti hasilnya di widget itu sendiri. Lakukan hal yang sama dengan kolom kontak jika tracker Anda terlihat oleh orang di luar tim.</p> <h2>Bagaimana permintaan fitur menjadi entri changelog?</h2> <p>Permintaan fitur menjadi entri changelog ketika pull request menutup issue-nya dan entri yang disusun dari pull request itu menautkan kembali. Mekanismenya adalah kata kunci penutupan milik GitHub sendiri: PR yang deskripsinya mengatakan <code>Fixes #142</code> menutup issue 142 saat merge. Jika entri changelog Anda disusun dari pull request yang di-merge, drafnya bisa membawa nomor issue-nya, dan entrinya tahu siapa yang meminta.</p> <p>Itulah alasan mengapa template meminta tujuan alih-alih solusi. Saat entri ditulis, tujuan adalah kalimat yang dibutuhkan penulis: "Sekarang Anda bisa mengekspor satu bulan faktur sebagai satu PDF" adalah entri changelog. "Menambahkan ekspor PDF" adalah pesan commit. <a href="https://changeloop.dev/changelog-tools">Alat changelog</a> yang menyusun dari pull request bisa melakukan pengumpulan dan tautannya; formulasinya masih membutuhkan seseorang, dan orang itu membutuhkan tujuannya.</p> <h2>Apa yang terjadi saat dirilis?</h2> <p>Peminta diberi tahu, dengan tautan ke entri. Dalam setup kami itu otomatis untuk permintaan yang masuk melalui widget: komentar yang mengatakan "Shipped — <judul entri>" dengan tautan ke entri yang diterbitkan, diposting di issue begitu seseorang menyetujui entrinya, sementara widget menampilkan entri yang sama kepada pengirimnya. Issue yang diajukan manual dari template ini tidak mendapat komentar otomatis; tutup lingkaran itu sendiri, dengan aturan yang sama. Komentarnya sengaja diposting saat persetujuan bukan saat merge: komentar yang mengatakan sesuatu itu live sebelum benar-benar live adalah janji yang rusak dengan stempel waktu. Setiap permintaan diberi tahu paling banyak sekali; persetujuan kedua dari entri yang sama tidak menghasilkan komentar kedua.</p> <p>Jika Anda melakukan ini secara manual, aturan yang sama berlaku. Jangan tutup lingkaran dari pull request. Tutup dari entri yang diterbitkan, dan tutup sekali. <a href="https://changeloop.dev/docs">Feed dan widget</a> membawa entri yang sama kepada semua orang yang tidak meminta, yang merupakan kebanyakan orang; komentarnya untuk yang meminta.</p> <h2>Mengapa kebanyakan template permintaan fitur gagal</h2> <p>Mereka dirancang untuk memudahkan triase dan berhasil, dengan mengorbankan satu momen yang penting bagi peminta. Template dengan dua belas kolom menerima lebih sedikit permintaan, dan yang diterimanya berasal dari orang-orang dengan kesabaran untuk mengisi dua belas kolom, yang bukan populasi yang sama dengan yang membutuhkan fiturnya. Template dengan empat kolom, salah satunya "bagaimana kami menghubungimu", menerima lebih banyak permintaan dan bisa menghormati semuanya.</p> <h2>FAQ</h2> <p><strong>Haruskah template permintaan fitur menanyakan prioritas?</strong> Tidak. Tanyakan solusi sementara sebagai gantinya. "Saya mengekspor ke spreadsheet dan mengetik ulang setiap Jumat" mengatakan lebih banyak tentang prioritas daripada dropdown yang diatur tinggi oleh pengirim.</p> <p><strong>Haruskah peminta mengusulkan solusi?</strong> Bisa, di teks bebas. Jangan jadikan itu sebagai kerangka. Permintaan yang ditulis sebagai solusi lebih sulit digabungkan satu sama lain dan lebih sulit diubah menjadi entri changelog.</p> <p><strong>Haruskah permintaan fitur muncul di roadmap publik?</strong> Setelah direncanakan, ya: label di issue yang sama menempatkannya di kolom direncanakan, dan peminta bisa melihat bagaimana pergerakannya. Artikel <a href="https://changeloop.dev/blog/id/public-roadmap/">roadmap publik</a> adalah mekanismenya.</p> <p><strong>Bagaimana cara menangani duplikat?</strong> Tautkan permintaan baru ke issue yang ada dan beri label prioritas rendah; jangan tutup. Setiap duplikat adalah satu orang lagi untuk diberi tahu saat dirilis. Dengan komentar otomatis Changeloop, orang itu hanya diberi tahu jika pull request juga menyebut issue mereka (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Di mana template seharusnya berada?</strong> Di repositori yang akan menerima pull request, sehingga kata kunci penutupannya berfungsi. Permintaan di tracker terpisah harus ditautkan secara manual saat merge, dan itulah langkah yang dilewatkan.</p> </article> <article> <h1>Roadmap publik dari issue tracker Anda, tiga kolom</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Roadmap publik adalah daftar apa yang Anda niatkan untuk dibangun, diterbitkan di tempat yang bisa dilihat pelanggan. Kata yang melakukan pekerjaan itu adalah <em>niatkan</em>: roadmap adalah kumpulan janji tentang masa depan, dan setiap item di dalamnya adalah yang akan Anda tepati atau akan terlihat tidak Anda tepati. Itulah alasan untuk menerbitkannya, dan itu juga alasan mengapa kebanyakan roadmap publik menjadi usang dalam satu kuartal. Versi yang bertahan itu kecil, diturunkan dari data yang sudah Anda pelihara, dan terhubung di ujung lain ke changelog, sehingga janji menjadi fakta tanpa ada yang memasukkannya kembali.</p> <h2>Untuk apa roadmap publik?</h2> <p>Roadmap publik memberi tahu pelanggan dengan permintaan bahwa permintaan mereka didengar, sebelum dirilis. Itu setengah awal dari menutup lingkaran: "Direncanakan" menjawab pertanyaan "apakah ada yang membaca ini", dan "Sedang dibangun" menjawab "apakah ini benar-benar terjadi". Tidak ada yang menggantikan langkah terakhir, memberi tahu peminta saat dirilis, tapi keduanya mengurangi jumlah orang yang bertanya sementara itu.</p> <p>Ini juga melakukan sesuatu untuk tim: memaksa komitmen publik, yang merupakan obat termurah yang diketahui melawan backlog yang diam-diam menyimpan empat ratus item yang tidak akan dibangun siapa pun.</p> <table> <thead> <tr> <th>Kolom</th> <th>Janji yang dibuatnya</th> <th>Yang memindahkan item ke dalamnya</th> </tr> </thead> <tbody><tr> <td>Direncanakan</td> <td>Kami berniat membangun ini</td> <td>Keputusan, dicatat sebagai label di issue</td> </tr> <tr> <td>Sedang dibangun</td> <td>Seseorang sedang mengerjakannya sekarang</td> <td>Label <code>roadmap:building</code> di issue</td> </tr> <tr> <td>Dirilis</td> <td>Sudah live</td> <td>Label <code>roadmap:shipped</code>, atau menutup issue selagi label itu terpasang</td> </tr> </tbody></table> <p>Tiga kolom, dalam urutan tetap, sudah cukup. Kolom keempat ("dipertimbangkan", "sedang ditinjau", "backlog") adalah tempat niat baik berubah menjadi museum, dan itu yang pertama dipelajari pelanggan untuk diabaikan.</p> <h2>Haruskah roadmap Anda publik?</h2> <p>Buat publik jika Anda bisa menjaganya tetap kecil dan jujur; jaga tetap privat jika alternatifnya adalah daftar panjang mungkin-mungkin. Biaya roadmap publik tidak ada hubungannya dengan menerbitkannya: setiap item di dalamnya sekarang menjadi pertanyaan yang akan ditanyakan seseorang, dalam dukungan, dalam panggilan penjualan dan dalam percakapan perpanjangan. Sepuluh item yang akan Anda bangun adalah aset. Enam puluh item yang mungkin Anda bangun adalah enam puluh percakapan masa depan tentang mengapa tidak.</p> <p>Dua alasan jujur untuk tidak menerbitkan: rencana Anda berubah lebih cepat dari satu kuartal, atau kompetisi Anda membaca roadmap Anda lebih hati-hati daripada pelanggan Anda. Keduanya nyata, dan keduanya dijawab dengan menerbitkan lebih sedikit alih-alih tidak sama sekali: hanya "sedang dibangun", dengan "direncanakan" disimpan secara internal, tetap memberi tahu peminta bahwa issue mereka bergerak.</p> <h2>Bagaimana cara membangun roadmap publik dari issue GitHub?</h2> <p>Letakkan satu label per kolom pada issue yang sudah Anda lacak, dan render issue berlabel sebagai roadmap-nya. Tidak ada yang dimasukkan ulang, roadmap-nya tidak bisa menyimpang dari pekerjaannya, dan issue yang sama yang dimulai sebagai permintaan pelanggan bergerak melalui kolom tanpa mengubah identitasnya.</p> <p>Mekanismenya, seperti yang kami jalankan:</p> <ol> <li><strong>Satu label per kolom, dengan awalan tetap</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Issue mana pun di repositori yang terhubung yang membawa salah satunya muncul di kolom itu. Issue tanpa salah satu dari itu tidak ada di roadmap, yang merupakan kebanyakan issue, yang benar.</li> <li><strong>Kolom-kolomnya adalah array terurut, selalu dalam urutan yang sama.</strong> Direncanakan, sedang dibangun, dirilis. Bukan peta yang diindeks berdasarkan nama, sehingga pembaca (atau widget) tidak pernah harus menebak urutannya.</li> <li><strong>Jika issue membawa dua label, yang paling maju yang menang.</strong> Seseorang akan menambahkan <code>roadmap:shipped</code> sebelum menghapus <code>roadmap:planned</code>; mesin status yang dipandu oleh "webhook mana yang tiba terakhir" akan menempatkan item di kolom berbeda tergantung urutan pengiriman. Memutuskan hanya dari kumpulan label membuat jawabannya sama terlepas dari bagaimana peristiwa tiba.</li> <li><strong>Dirilis adalah status label seperti yang lain.</strong> Kartu berpindah saat issue mendapat <code>roadmap:shipped</code>, atau ditutup selagi membawa label itu. Kartu itu sendiri tidak menautkan ke entri changelog; detailnya ada di entri, yang disusun dari pull request yang menutup issue.</li> <li><strong>Sajikan sebagai data.</strong> Roadmap-nya adalah dokumen JSON dengan tiga kolom itu, diterbitkan di samping feed changelog dengan header cache yang sama, sehingga situs dokumen, widget atau halaman status bisa merendernya tanpa integrasi kedua. <a href="https://changeloop.dev/docs">Dokumentasi feed</a> punya bentuk pastinya.</li> </ol> <p>Label itu hal kecil yang diminta dari maintainer, dan itu seluruh integrasinya. Tidak ada papan untuk dijaga tetap sinkron, tidak ada alat terpisah untuk login, dan permintaan yang diajukan pelanggan adalah item di roadmap; saat dirilis, itu item yang sama.</p> <h2>Apa yang tidak boleh dimuat roadmap publik?</h2> <p>Tidak boleh memuat tanggal, estimasi, atau apa pun yang akan membuat Anda malu jika ditanyakan sembilan bulan kemudian. Tanggal adalah kesalahan klasik: satu kuartal di roadmap menjadi komitmen di dek penjualan menjadi tiket bernama "kalian bilang Q3". Kolom-kolom sudah cukup mengatakan. "Sedang dibangun" sudah berarti "cukup segera sehingga ada yang mengerjakannya".</p> <p>Juga tidak boleh memuat backlog internal. Roadmap dengan tiga ratus item adalah masalah pencarian, bukan janji, dan pelanggan yang menemukan permintaannya di posisi 212 sudah mempelajari sesuatu yang tidak ingin Anda katakan kepadanya.</p> <h2>Bagaimana roadmap terhubung ke changelog?</h2> <p>Roadmap dan changelog menggambarkan issue yang sama dari dua sisi, satu untuk masa depan dan satu untuk masa lalu. Tidak ada yang memindahkan kartu di papan terpisah. Maintainer mengubah label di issue yang memang sedang dikerjakannya, entrinya disusun dari pull request, dan saat seseorang menyetujui entri itu, peminta yang umpan balik widget-nya menjadi issue tersebut diberi tahu di sana. Memindahkan kartu ke dirilis tetap langkah tersendiri, label <code>roadmap:shipped</code>, jadi jadikan bagian dari tinjauan yang sama; menyetujui entri tidak melakukannya untuk Anda.</p> <p>Ini lingkaran yang sama yang dijelaskan <a href="https://changeloop.dev/blog/id/customer-feedback-loop/">artikel lingkaran umpan balik</a> dari sisi changelog; roadmap adalah apa yang dilihat pelanggan di tengah-tengahnya. Rangkuman <a href="https://changeloop.dev/changelog-tools">alat changelog</a> mencakup produk mana yang menawarkan tampilan roadmap dan mana yang memperlakukannya sebagai papan terpisah, yang merupakan perbedaan yang menentukan apakah tetap akurat.</p> <h2>Seperti apa roadmap publik yang baik?</h2> <p>Terlihat singkat, dan setiap item di dalamnya adalah issue yang bisa dibuka siapa pun. Tesnya adalah apakah pelanggan bisa pergi dari sebuah item ke diskusi di baliknya, dan dari item yang dirilis ke entri yang menjelaskan apa yang benar-benar berubah. Roadmap yang berupa daftar nama fitur tanpa jalan masuk adalah brosur.</p> <p>Contoh yang dikerjakan, sebagai JSON yang akan diambil widget:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Tiga item di tiga kolom adalah roadmap publik yang sangat baik. Mengatakan apa yang akan datang, apa yang sedang terjadi, dan apa yang sudah terjadi, dan setiap barisnya bisa diperiksa. Lima tata letak lain, dari Now/Next/Later sampai berbasis hasil, ditampilkan dengan item contoh di <a href="https://changeloop.dev/blog/id/product-roadmap-examples/">contoh roadmap produk</a>.</p> <h2>FAQ</h2> <p><strong>Berapa banyak item yang seharusnya dimiliki roadmap publik?</strong> Sesedikit yang bisa Anda pertahankan. Di bawah sepuluh secara total itu normal untuk produk kecil; lebih dari tiga puluh di "direncanakan" biasanya backlog yang menyamar sebagai roadmap.</p> <p><strong>Haruskah roadmap publik punya tanggal?</strong> Tidak. Kolom-kolom mengomunikasikan urutan tanpa menciptakan tenggat waktu. Jika pelanggan membutuhkan tanggal, itu percakapan, bukan item roadmap.</p> <p><strong>Haruskah pelanggan memilih item roadmap?</strong> Voting mengukur siapa yang muncul, bukan apa yang penting. Komentar di issue yang menjelaskan solusi sementara yang mereka gunakan hari ini bernilai lebih dari lima puluh suara, dan itu memberi biaya bagi pemberi suara, yang menjadi intinya.</p> <p><strong>Apa yang terjadi pada item roadmap yang dibatalkan?</strong> Hapus labelnya dan katakan alasannya di issue. "Kami tidak akan melakukan ini" yang publik adalah bagian dari lingkaran, dan itu pesan yang tidak pernah dikirim kebanyakan tim.</p> </article> <article> <h1>Otomatisasi changelog, dan batasannya</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Otomatisasi changelog berhasil ketika mengotomatisasi pengumpulan, klasifikasi dan penerbitan, dan berhenti di seleksi dan formulasi. Otomatisasi semuanya dan Anda mengirimkan git log yang diformat; jangan otomatisasi apa pun dan changelog ditulis dalam ledakan, dari ingatan, sebelum rilis. Pertanyaan yang berguna adalah bagian mana yang harus diotomatisasi, bukan seberapa banyak.</p> <p>Proyek otomatisasi changelog gagal dalam salah satu dari dua arah, dan keduanya bisa diprediksi sejak rapat desain pertama. Otomatisasi terlalu sedikit dan changelog menjadi dokumen yang seharusnya diperbarui seseorang, yang berarti diperbarui dalam ledakan, oleh siapa pun yang kebagian tugas termalang. Otomatisasi terlalu banyak dan berubah menjadi git log yang diformat: lengkap, akurat, dan tidak dibaca siapa pun.</p> <h2>Bagian mana dari changelog yang harus diotomatisasi?</h2> <p>Tiga dari empat langkah. Pengumpulan dan penerbitan sepenuhnya; klasifikasi sebagai langkah pertama dengan penggantian manusia; seleksi dan formulasi tidak pernah.</p> <table> <thead> <tr> <th>Langkah</th> <th>Otomatisasi?</th> <th>Mengapa</th> </tr> </thead> <tbody><tr> <td>Pengumpulan: perubahan dari commit, PR, tiket ke daftar</td> <td>Sepenuhnya</td> <td>Membosankan, dilewati saat tenggat waktu, mesin melakukannya dengan sempurna</td> </tr> <tr> <td>Klasifikasi: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Langkah pertama, penggantian manusia</td> <td>Sekitar 80% benar hanya dari metadata; 20% yang salah adalah entri yang penting</td> </tr> <tr> <td>Seleksi dan formulasi: apa yang disampaikan ke pembaca, dan bagaimana</td> <td>Tidak pernah</td> <td>Ini seluruh nilai dari artefak</td> </tr> <tr> <td>Penerbitan: halaman, feed, email, widget, Slack</td> <td>Sepenuhnya, dari satu sumber</td> <td>Tempat sebagian besar upaya manual sebenarnya dihabiskan</td> </tr> </tbody></table> <p><strong>Pengumpulan.</strong> Mengeluarkan perubahan dari tempat mereka terjadi (commit, PR, tiket) dan memasukkannya ke daftar. Otomatisasi ini sepenuhnya. Manusia buruk dalam hal ini, membosankan, dan merupakan langkah yang dilewati saat tenggat waktu. <a href="https://changeloop.dev/blog/id/conventional-commits-changelog/">Conventional commits</a> atau label PR biasanya bahan mentahnya.</p> <p><strong>Klasifikasi.</strong> Memutuskan apakah sesuatu itu Added, Fixed, Changed, Deprecated, Removed atau Security. Otomatisasi langkah pertama dari jenis commit atau label PR, dan biarkan manusia menggantinya. Akurasi di sini sekitar delapan puluh persen hanya dari metadata, dan dua puluh persen yang salah terkonsentrasi tepat di entri yang penting, karena ambiguitas berkorelasi dengan pentingnya.</p> <p><strong>Seleksi dan formulasi.</strong> Memutuskan apa yang harus diketahui pembaca dan bagaimana menyampaikannya. <strong>Jangan otomatisasi ini.</strong> Ini seluruh nilai dari artefak. Semua yang lain adalah logistik.</p> <p><strong>Penerbitan.</strong> Membawa entri yang selesai ke halaman, feed, email, widget in-app, kanal Slack. Otomatisasi sepenuhnya, dan dari satu sumber. Ini tempat sebagian besar upaya manual sebenarnya dihabiskan, dan hampir tidak ada yang menghitungnya. Ini juga langkah yang bisa memberi tahu orang yang meminta perubahan bahwa itu sudah dirilis, yang merupakan seluruh isi dari <a href="https://changeloop.dev/blog/id/customer-feedback-loop/">menutup lingkaran umpan balik dari sisi changelog</a>. Separuh email dari langkah itu punya bentuknya sendiri, di <a href="https://changeloop.dev/blog/id/product-update-email/">template email update produk</a>.</p> <p>Poin terakhir itu layak dipikirkan. Tim cenderung melihat changelog sebagai masalah penulisan, lalu menghabiskan sebagian besar waktu pada distribusi: menyalin entri ke alat email, memformat ulang untuk in-app, menempel ke Slack, memperbarui halaman dokumen. Menulis butuh satu jam. Menyalin butuh satu jam setiap rilis, selamanya, dan itu bagian yang seharusnya dimiliki mesin.</p> <h2>Apa yang terjadi ketika batasnya bergeser?</h2> <p><strong>Geser ke atas dan Anda dapat dump git.</strong> Otomatisasi penuh dari commit menghasilkan <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> dan <code>address review comments</code> di depan pelanggan. Setiap tim yang melakukan ini kemudian menambahkan filter, dan filter tersebut adalah langkah seleksi yang diperkenalkan kembali dengan nama lain, dengan ergonomi yang lebih buruk.</p> <p><strong>Geser ke bawah dan Anda dapat ledakan.</strong> Pengumpulan sepenuhnya manual berarti entri ditulis dari ingatan saat rilis. Itu mode yang diperingatkan <a href="https://changeloop.dev/blog/id/keep-a-changelog-implemented/">Keep a Changelog</a> sejak awal, dan memburuk diam-diam: changelog terlihat terpelihara sampai tepat minggu ketika tidak ada yang punya waktu.</p> <h2>Seperti apa pipeline otomatisasi changelog?</h2> <p>Empat langkah, dengan tepat satu gerbang manusia, diletakkan di tempat draf menjadi publik.</p> <ol> <li>Saat merge, turunkan entri draf dari PR: jenis dari label atau prefiks commit, judul sebagai draf pertama, tautan kembali ke PR, penulis tercatat. Letakkan di bak yang belum dirilis.</li> <li>Siapa pun bisa mengedit draf apa pun kapan saja, dan mengedit itu murah. Kebanyakan mendapat satu baris ditulis ulang.</li> <li>Memotong rilis mengharuskan setiap entri di bak sudah diedit atau ditandai secara eksplisit sebagai internal. Gerbang ini adalah seluruh desainnya. Tanpanya, draf dirilis tanpa disunting di minggu yang sibuk.</li> <li>Menerbitkan adalah fan-out dari set yang dirilis: halaman publik, feed, email, widget, posting Slack. Satu sumber, beberapa rendering, tidak ada penyalinan.</li> </ol> <p>Langkah 3 satu-satunya tempat yang membutuhkan seseorang, dan butuh sekitar sepuluh menit per rilis begitu draf-nya layak. Di mana permintaan pelanggan terlibat, draf juga membawa issue yang ditutupnya, yang memungkinkan langkah 4 memberi tahu peminta; <a href="https://changeloop.dev/blog/id/feature-request-template/">template permintaan fitur</a> dirancang agar tautan itu bertahan. Posisi langkah ini dalam alur rilis yang lebih luas adalah topik <a href="https://changeloop.dev/blog/id/release-management-process/">proses manajemen rilis</a>.</p> <h2>Apa yang dibutuhkan otomatisasi dari data Anda?</h2> <p>Tidak ada yang di atas berfungsi jika changelog adalah berkas Markdown, karena berkas tidak bisa dirender ke lima permukaan tanpa diurai ulang, dan mengurai prosa adalah cara Anda berakhir dengan widget yang menampilkan setengah judul.</p> <p>Entri perlu terstruktur: jenis, tanggal, versi atau pengenal rilis, audiens, badan dan tautan. Lalu berkas, halaman, feed dan email semuanya adalah tampilan. Poin struktural itu satu-satunya hal yang layak dibenarkan sebelum memilih alat, karena itu yang tidak bisa Anda tambahkan dengan murah setelahnya. Tidak ada satu pun dari itu berfungsi selama entri tidak benar-benar dibuat untuk setiap perubahan yang membutuhkannya; <a href="https://changeloop.dev/blog/id/changelog-ci-enforcement/">mewajibkan entri changelog di CI</a> membahas cara membuat pipeline menolak merge tanpa entri, alih-alih menyerahkan langkah itu pada ingatan.</p> <p>Kami membangun <a href="https://changeloop.dev/">changeloop</a>, di mana changelog dulu adalah feed baru kemudian halaman, jadi bacalah itu sebagai kepentingan alih-alih rekomendasi netral; <a href="https://changeloop.dev/pricing">harga</a> adalah satu repositori gratis tanpa kartu, cukup untuk melihat bentuknya. <a href="https://changeloop.dev/changelog-tools">Alat changelog</a> adalah rangkuman kami tentang apa lagi yang ada, termasuk produk yang kami saingi, dan <a href="https://changeloop.dev/changelog-generator">generator changelog</a> melakukan langkah pengumpulan dan klasifikasi di browser jika Anda ingin melihat penurunannya sebelum berkomitmen pada pipeline.</p> <h2>Tesnya</h2> <p>Hitung menit antara perubahan yang di-merge dan perubahan itu terlihat bagi pelanggan yang tidak membaca repo Anda. Jika sebagian besar menit itu adalah seseorang menyalin teks antar alat, otomatisasi yang Anda butuhkan ada di penerbitan, bukan penulisan.</p> <h2>FAQ</h2> <p><strong>Bisakah AI menulis changelog?</strong> Bisa menyusun draf. Model yang diberi pull request yang di-merge kebanyakan menghasilkan draf pertama judul dan badan yang bisa digunakan, yang merupakan langkah pengumpulan dan klasifikasi yang dilakukan lebih baik. Seleksi, apakah pembaca harus diberi tahu sama sekali, dan formulasi akhir, masih membutuhkan orang yang tahu audiensnya, dan pipeline yang menerbitkan draf tanpa gerbang itu telah mengotomatisasi langkah yang salah.</p> <p><strong>Apa bedanya generator changelog dengan otomatisasi changelog?</strong> Generator mengubah commit menjadi daftar yang diformat sekali, sesuai permintaan. Otomatisasi berjalan di setiap merge, memelihara bak yang belum dirilis, mensyaratkan tinjauan manusia untuk rilis, dan menerbitkan ke setiap permukaan dari satu sumber. Generator adalah langkah pertama pipeline, dijalankan secara manual.</p> <p><strong>Haruskah changelog diotomatisasi dari commit atau dari pull request?</strong> Dari pull request, di mana unit perubahannya adalah PR: judul dan deskripsi ditulis sekali, untuk seluruh perubahan, dan PR menautkan issue yang ditutupnya. Penurunan berbasis commit berhasil ketika commit adalah unitnya dan mengikuti konvensi.</p> <p><strong>Bagaimana cara mencegah otomatisasi menerbitkan perubahan internal?</strong> Klasifikasikan <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> dan pembaruan dependensi sebagai internal secara default, dan jadikan promosi ke publik tindakan yang disengaja. Default yang terbalik, publik kecuali seseorang menyembunyikannya, adalah cara <code>bump deps</code> sampai ke pelanggan.</p> </article> <article> <h1>Changelog vs release notes: apa bedanya?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Changelog adalah catatan berkelanjutan dan kumulatif dari semua yang berubah, ditulis untuk seseorang yang sedang mencari sesuatu. Release notes adalah pesan terkurasi tentang satu rilis, ditulis untuk seseorang yang memutuskan apakah itu penting baginya. Perbedaannya ada pada audiens, bukan format, dan kebanyakan tim membutuhkan keduanya: satu sebagai referensi, satu sebagai pengumuman, diturunkan dari entri yang sama.</p> <p>Kebanyakan tim berakhir dengan salah satunya secara tidak sengaja dan yang lain atas permintaan. Anda mulai dengan changelog karena seorang developer ingin catatan tentang apa yang dirilis. Berbulan-bulan kemudian seseorang dari dukungan bertanya mengapa pelanggan tidak tahu tentang fitur yang sudah aktif sejak April, dan sekarang Anda butuh release notes.</p> <h2>Changelog vs release notes, berdampingan</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Pembaca</td> <td>Seseorang yang mencari sesuatu</td> <td>Seseorang yang memutuskan apakah itu penting</td> </tr> <tr> <td>Cakupan</td> <td>Semua yang berubah</td> <td>Apa yang layak disampaikan tentang rilis ini</td> </tr> <tr> <td>Kadensi</td> <td>Berkelanjutan, per merge atau per rilis</td> <td>Per rilis, dan hanya yang layak diumumkan</td> </tr> <tr> <td>Nada</td> <td>Ringkas, faktual, sering imperatif</td> <td>Menjelaskan, kadang persuasif</td> </tr> <tr> <td>Masa hidup</td> <td>Permanen, dibaca bertahun-tahun kemudian</td> <td>Dibaca minggu pertama, lalu diarsipkan</td> </tr> <tr> <td>Berada di</td> <td>Repo, situs dokumen, halaman <code>/changelog</code></td> <td>Email, in-app, postingan blog, halaman rilis</td> </tr> <tr> <td>Gagal karena</td> <td>Tidak lengkap</td> <td>Membosankan, atau datang terlambat</td> </tr> </tbody></table> <h2>Apa itu changelog?</h2> <p>Changelog adalah catatan kronologis, hampir lengkap, tentang apa yang berubah, terbaru dulu, dengan setiap entri diberi jenis (added, changed, deprecated, removed, fixed, security) dan tanggal. Pembacanya sudah memutuskan bahwa mereka peduli. Mereka sedang mencari sesuatu: kapan sebuah perilaku berubah, apakah sebuah bug sudah diperbaiki, versi mana yang memperkenalkan flag. Kelengkapan adalah seluruh nilainya, itulah mengapa konvensi <a href="https://changeloop.dev/blog/id/keep-a-changelog-implemented/">Keep a Changelog</a> menghabiskan sebagian besar satu halamannya untuk struktur dan hampir tidak ada untuk prosa.</p> <h2>Apa itu release notes?</h2> <p>Release notes adalah pesan selektif, ditulis dalam prosa, tentang satu rilis. Pembacanya belum memutuskan apa pun. Mereka sedang memutuskan apakah rilis ini penting bagi mereka, dan apakah mereka harus melakukan sesuatu tentang itu. Seleksi adalah seluruh nilainya: release note yang mendaftar semuanya adalah changelog dengan paragraf, dan mengecewakan pembaca dengan cara yang sama seperti changelog yang melewatkan sesuatu mengecewakan pembacanya. <a href="https://changeloop.dev/blog/id/how-to-write-release-notes/">Cara menulis release notes</a> membahas tentang seleksi dan formulasi.</p> <h2>Apakah Anda membutuhkan changelog dan release notes?</h2> <p>Anda membutuhkan keduanya begitu kedua audiens Anda menginginkan hal yang berbeda; sebelum itu, satu artefak yang melakukan kedua tugas adalah benar. Tim kecil menerbitkan satu halaman <code>/changelog</code> dengan paragraf singkat di atas setiap entri, dan untuk sementara itu melayani baik developer yang mencari perbaikan maupun pelanggan yang sekilas mencari berita. Membagi terlalu dini memberi Anda dua hal untuk dipelihara dan salah satunya akan membusuk.</p> <p>Pembagian menjadi layak ketika ini mulai terjadi:</p> <ul> <li>Entri changelog Anda telah berkembang menjadi paragraf penjelasan yang dilewati developer.</li> <li>Atau sebaliknya: pengumuman rilis Anda mulai mendaftar pembaruan dependensi.</li> <li>Dukungan menyalin entri ke email dan menulis ulang di tengah jalan.</li> <li>Seseorang meminta "hanya breaking change" dan Anda tidak bisa memfilternya.</li> </ul> <p>Yang terakhir itu tanda sebenarnya. Jika tidak ada yang bisa menjawab "apa yang berubah yang memengaruhi saya" tanpa membaca semuanya, Anda punya satu artefak yang melakukan dua tugas dengan buruk.</p> <h2>Satu sumber, dua tampilan</h2> <p>Kesalahannya adalah memperlakukan keduanya sebagai dua dokumen. Keduanya adalah dua tampilan atas kumpulan perubahan yang sama.</p> <p>Tulis changelog seiring waktu, satu entri per perubahan yang berarti, masing-masing diberi label apa itu: fixed, added, changed, removed, deprecated, security. Jaga entri cukup singkat sehingga menulis satu bukan keputusan besar. Kemudian, saat rilis, release notes adalah seleksi dan penulisan ulang: ambil entri yang penting bagi manusia, kelompokkan berdasarkan apa yang memungkinkan seseorang lakukan, dan letakkan alasannya di atas.</p> <p>Ini punya konsekuensi praktis. Jika changelog adalah sumbernya, ia perlu menjadi data terstruktur, bukan halaman yang dikelola manual. Sebuah entri butuh jenis, tanggal, versi, dan cara menyatakan untuk siapa itu. Begitu punya itu, halaman publik, widget in-app dan feed RSS atau JSON adalah tiga rendering dari satu hal, dan tidak ada yang menulis ulang apa pun di tengah jalan menuju pelanggan. Email release notes bisa mengutip entri yang sama, dari alat apa pun yang mengirim email Anda. <a href="https://changeloop.dev/blog/id/changelog-automation/">Otomatisasi changelog</a> membahas mana dari langkah-langkah ini yang seharusnya dimiliki mesin. Itulah seluruh argumen untuk memperlakukan changelog sebagai feed daripada halaman. Ini juga, secara transparan, apa yang kami bangun, jadi bacalah ini sebagai kepentingan daripada survei netral.</p> <h2>Jika Anda hanya punya waktu untuk satu</h2> <p>Tulis changelog. Lebih murah per entri, berguna di hari Anda menulisnya, dan release notes bisa diturunkan darinya kemudian. Sebaliknya tidak benar: Anda tidak bisa merekonstruksi setahun perubahan dari dua belas email pengumuman, dan orang akan memintanya dari Anda.</p> <p>Simpan dalam format tetap sehingga penurunan tetap mungkin. Halaman <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> kami mengumpulkan entri dari tim yang melakukan ini dengan baik, dan <a href="https://changeloop.dev/release-notes-template">template release notes</a> adalah bentuk yang kami gunakan saat mengubah sekumpulan entri menjadi sesuatu yang layak dikirim.</p> <h2>Catatan tentang penamaan</h2> <p>Tidak ada yang distandardisasi dari semua ini, dan Anda akan menemukan "release notes" digunakan untuk daftar berkelanjutan dan "changelog" digunakan untuk pengumuman triwulanan. Berdebat tentang kata-katanya tidak sepadan. Putuskan tugas mana dari keduanya yang dilakukan setiap artefak Anda, namai sesuai apa yang sudah dipanggil tim Anda, dan pastikan tidak ada satu pun yang diam-diam melakukan keduanya.</p> <p>Di permukaan mana hasilnya berakhir adalah keputusan terpisah, dibahas di <a href="https://changeloop.dev/blog/id/changelog-page/">cara membangun halaman changelog</a>.</p> <h2>FAQ</h2> <p><strong>Apakah changelog sama dengan release notes?</strong> Tidak. Changelog adalah catatan lengkap, dibaca oleh yang mencari sesuatu; release notes adalah pengumuman terpilih, dibaca oleh yang memutuskan apakah mereka peduli. Perubahan yang sama muncul di keduanya, diformulasikan berbeda untuk setiap pembaca.</p> <p><strong>Bisakah release notes dihasilkan dari changelog?</strong> Ya, dan itu arah yang benar. Pilih entri yang penting bagi manusia, kelompokkan berdasarkan hasil, tulis ulang judulnya. Sebaliknya, merekonstruksi changelog dari pengumuman, kehilangan semua yang dilewatkan pengumuman.</p> <p><strong>Di mana changelog seharusnya berada?</strong> Di suatu tempat permanen dan bisa ditautkan yang bisa dicapai pembaca tanpa repositori: halaman <code>/changelog</code>, situs dokumen, atau feed yang dirender di beberapa tempat. <code>CHANGELOG.md</code> sendiri menjangkau kontributor, bukan pelanggan.</p> <p><strong>Haruskah changelog mencakup perubahan internal?</strong> Ya, di bawah, satu baris masing-masing. Changelog adalah catatan lengkap. Release notes juga bisa menyimpannya, di bagian terakhir yang singkat, asalkan perubahan yang akan diperhatikan pembaca muncul lebih dulu.</p> </article> <article> <h1>Dari conventional commits ke changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Conventional commits memberi changelog tiga hal secara gratis: jenis setiap perubahan, bagian sistem yang tersentuh, dan apakah itu merusak sesuatu. Tidak memberi apa pun lagi. Formulasi, pengelompokan dan seleksi, yang merupakan changelog itu sendiri, tetap sepenuhnya terbuka, dan pipeline yang berpura-pura sebaliknya mengirimkan git log yang diformat.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Tiga commit dalam format <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. Dari ini, mesin bisa memberi tahu Anda bahwa satu adalah fitur, satu perbaikan, satu perawatan, dan bagian sistem mana yang tersentuh masing-masing. Itu sungguh berguna, dan itu seluruh janji konvensi: riwayat commit yang bisa dibaca oleh sesuatu selain manusia. Kesalahannya adalah mengira itu memberi Anda changelog. Itu memberi Anda bahan mentah.</p> <h2>Apa yang ditentukan konvensi?</h2> <p>Jenis, scope opsional, dan deskripsi: <code>type(scope): description</code>. Jenis-jenisnya secara konvensional adalah <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Dua hal menandai breaking change: <code>!</code> sebelum titik dua, atau footer <code>BREAKING CHANGE:</code>. Alat mengandalkan <code>feat</code> dan <code>fix</code> untuk kenaikan versi minor dan patch, dan penanda breaking untuk major.</p> <table> <thead> <tr> <th>Commit memberi Anda</th> <th>Changelog membutuhkan</th> <th>Siapa yang mengisi celah</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / internal</td> <td>Pemetaan, otomatis</td> </tr> <tr> <td><code>(scope)</code></td> <td>Pengelompokan yang dikenali pembaca</td> <td>Seseorang, sekali per scope</td> </tr> <tr> <td><code>!</code> atau <code>BREAKING CHANGE:</code></td> <td>Siapa yang rusak, sampai kapan, dan apa yang harus dilakukan</td> <td>Seseorang, setiap kali</td> </tr> <tr> <td>Deskripsi, ditulis untuk peninjau</td> <td>Hasil, ditulis untuk pelanggan</td> <td>Seseorang, setiap entri</td> </tr> <tr> <td>Satu commit</td> <td>Satu perubahan, yang bisa jadi banyak commit</td> <td>Aturan squash, atau seseorang</td> </tr> </tbody></table> <p>Penanda memberi tahu alatnya; tidak memberi tahu pemanggilnya, yang menjadi subjek <a href="https://changeloop.dev/blog/id/api-deprecation/">cara men-deprecate API</a> dan <a href="https://changeloop.dev/blog/id/breaking-changes/">apa itu breaking change</a>. Ini spesifikasi kecil dan layak diikuti bahkan jika Anda tidak pernah menghasilkan apa pun darinya, karena memaksa satu keputusan per commit: apakah ini perubahan yang dilihat pengguna, atau tidak.</p> <h2>Di mana conventional commits berhenti?</h2> <p>Berhenti di kalimat. Semua yang ditangkap konvensi adalah metadata tentang perubahan; perubahan itu sendiri masih dijelaskan dalam kosakata peninjau.</p> <p><strong>Pesan commit ditulis untuk peninjau.</strong> <code>fix(auth): reject expired refresh tokens</code> benar dan tidak memberi tahu apa pun kepada pelanggan. Pembaca changelog ingin "Anda akan diminta login ulang saat sesi benar-benar kedaluwarsa, alih-alih melihat 401 sesekali".</p> <p><strong>Scope bersifat internal.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> adalah nama modul. Stabil, yang membuat mereka baik untuk pengelompokan, dan tidak bermakna bagi siapa pun di luar kode basis.</p> <p><strong>Satu perubahan sering kali banyak commit.</strong> Fitur yang di-merge dalam sebelas commit menghasilkan sebelas entri, sepuluh di antaranya kebisingan, dan meng-squash untuk menyembunyikan itu kehilangan riwayat peninjauan.</p> <p><strong><code>chore</code> adalah tempat sampah, bukan kategori.</strong> Pembaruan dependensi, perubahan CI dan penggantian nama semuanya jatuh di sana, dan beberapa penting bagi pengguna sementara kebanyakan tidak.</p> <p>Jadi: konvensi memberi Anda jenis, scope dan status breaking secara gratis, dan membiarkan formulasi, pengelompokan dan seleksi sepenuhnya terbuka. Ketiganya adalah changelog. <a href="https://changeloop.dev/blog/id/changelog-entry-ownership/">Siapa sebenarnya pemilik entri changelog</a> membahas siapa yang seharusnya menangani formulasi, pengelompokan, dan seleksi itu, karena konvensinya sendiri tidak punya pendapat soal itu.</p> <h2>Bagaimana changelog dihasilkan dari conventional commits?</h2> <p>Dalam dua lapisan, dan yang kedua harus wajib.</p> <p><strong>Lapisan satu, otomatis.</strong> Saat merge, turunkan entri draf dari commit: jenis dipetakan ke jenis changelog (<code>feat</code> ke Added, <code>fix</code> ke Fixed, penanda breaking ke Changed plus flag), scope disimpan sebagai metadata alih-alih teks, tautan ke PR. Letakkan di bagian Unreleased yang diminta <a href="https://changeloop.dev/blog/id/keep-a-changelog-implemented/">Keep a Changelog</a>.</p> <p><strong>Lapisan dua, manusia, dan diwajibkan.</strong> Sebelum rilis keluar, setiap entri draf mendapat penulisan ulang satu baris dalam kosakata pengguna, atau ditandai internal dan dihapus dari tampilan publik. Ini langkah yang dicoba dilewatkan orang, dan melewatkannya menghasilkan changelog yang terbaca seperti diff.</p> <p>Detail desain yang penting adalah lapisan dua tidak opsional dalam pipeline. Jika rilis bisa dipotong dengan draf yang tidak diedit, itu akan terjadi, di minggu yang sibuk. Langkah mana yang milik mesin dan mana milik orang adalah seluruh isi <a href="https://changeloop.dev/blog/id/changelog-automation/">otomatisasi changelog</a>.</p> <p>Memotong rilis juga saat tag git, rilis, dan entri changelog ini bisa selaras atau mulai tidak sinkron; <a href="https://changeloop.dev/blog/id/git-tags-releases-changelog/">tag git, rilis, dan changelog Anda</a> membahas cara menjaga ketiganya tetap sinkron.</p> <h2>Tiga jebakan</h2> <p><strong>Squash merge memakan footer.</strong> Jika platform Anda meng-squash dengan judul PR sebagai pesan, footer <code>BREAKING CHANGE:</code> dari commit di dalam branch itu menghilang, dan alat Anda diam-diam berhenti melihat breaking change. Periksa apa yang sebenarnya disimpan template squash Anda.</p> <p><strong>Commit revert menghasilkan entri hantu.</strong> <code>fix</code> yang di-revert keesokan harinya menghasilkan entri untuk sesuatu yang tidak pernah dirilis, kecuali penurunannya merekonsiliasi revert. Kebanyakan alat tidak melakukan itu.</p> <p><strong>Kenaikan versi dan changelog jadi tidak sinkron.</strong> Jika versi dihitung dari commit dan changelog ditulis manual setelahnya, keduanya menyimpang dalam sekitar dua rilis. Hitung keduanya dalam satu langkah yang sama atau terima salah satunya salah.</p> <h2>Jika Anda ingin bagian mekanisnya tanpa pipeline</h2> <p><a href="https://changeloop.dev/changelog-generator">Generator changelog</a> kami melakukan langkah penurunan di browser: tempel commit, dapatkan entri yang dikelompokkan dan berjenis. Ini sengaja deterministik dan sepenuhnya sisi klien, jadi commit yang Anda tempel tidak pernah meninggalkan mesin Anda, yang penting saat pesan berasal dari repositori privat. Melakukan separuh pengumpulan dengan jujur dan tidak mencoba lapisan dua, karena lapisan dua adalah penilaian dan alat yang memalsukannya menghasilkan tepatnya changelog yang diperdebatkan artikel ini.</p> <p>Untuk versi pipeline, <a href="https://changeloop.dev/changelog-tools">alat changelog</a> mencakup apa yang ada.</p> <h2>Ringkasan</h2> <p>Conventional commits menjawab "jenis perubahan apa ini" secara andal dan murah. Tidak menjawab "apa yang harus kita katakan kepada orang-orang", dan tidak ada jumlah alat di atas pesan commit yang akan melakukannya, karena informasinya tidak pernah ada di pesan commit. Anggarkan untuk penulisan ulang.</p> <h2>FAQ</h2> <p><strong>Apakah conventional commits menghasilkan changelog secara otomatis?</strong> Mereka menghasilkan draf secara otomatis: entri berjenis, dengan scope, tertaut. Formulasi untuk pelanggan, pengelompokan dan keputusan apa yang dihilangkan masih membutuhkan seseorang, dan pipeline yang melewatkan langkah itu menerbitkan pesan commit.</p> <p><strong>Jenis conventional commit mana yang muncul di changelog?</strong> <code>feat</code> dan <code>fix</code> selalu, sebagai Added dan Fixed. <code>perf</code> biasanya, sebagai Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> dan <code>ci</code> bersifat internal secara default dan hanya muncul jika seseorang mempromosikan salah satunya.</p> <p><strong>Bagaimana conventional commits menandai breaking change?</strong> Sebuah <code>!</code> setelah jenis atau scope (<code>feat(api)!: ...</code>), atau footer <code>BREAKING CHANGE:</code> di badan commit. Keduanya hilang jika squash merge hanya menyimpan judul PR.</p> <p><strong>Apakah Anda perlu conventional commits untuk mengotomatisasi changelog?</strong> Tidak. Label PR, template PR dan tautan issue membawa metadata yang sama untuk tim yang merge lewat pull request. Conventional commits adalah opsi termurah ketika unit perubahannya adalah commit.</p> </article> <article> <h1>Cara menulis release notes yang benar-benar dibaca orang</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Untuk menulis release notes yang dibaca orang, jawab satu pertanyaan per entri: apa yang bisa dilakukan pembaca sekarang yang sebelumnya tidak bisa, dan apa yang harus mereka lakukan. Letakkan apa pun yang punya tenggat waktu di paling atas, sebutkan siapa yang terdampak, katakan "tidak ada tindakan yang diperlukan" jika itu benar, dan lewati rilis yang tidak punya apa-apa untuk disampaikan. Semua hal lain di halaman ini adalah penerapan aturan itu.</p> <blockquote> <p>Perbaikan bug dan peningkatan performa.</p> </blockquote> <p>Setiap produk pernah merilis ini. Penyebabnya jarang kemalasan: ini yang terjadi ketika release notes ditulis dari dalam, oleh seseorang yang sudah dua minggu tenggelam dalam diff dan tidak bisa lagi melihat bagian mana yang akan dipedulikan orang luar. Gaya bahasa yang lebih baik tidak akan memperbaikinya; menjawab pertanyaannya yang akan.</p> <h2>Apa yang harus dicakup release notes?</h2> <p>Release notes harus mencakup, untuk setiap perubahan yang layak disebut: apa yang bisa dilakukan pembaca sekarang, siapa yang terdampak, apa yang harus mereka lakukan (termasuk "tidak ada"), dan kapan sesuatu yang punya tenggat waktu berlaku. Release notes tidak boleh mencakup nomor tiket internal, nama komponen yang hanya digunakan tim, atau nomor versi sebagai satu-satunya judul.</p> <table> <thead> <tr> <th>Sertakan</th> <th>Hilangkan</th> </tr> </thead> <tbody><tr> <td>Hasil, dalam bahasa pembaca</td> <td>Implementasi, dalam bahasa tim</td> </tr> <tr> <td>Siapa yang terdampak, berdasarkan paket, peran atau versi API</td> <td>"Beberapa pengguna"</td> </tr> <tr> <td>Tindakan yang diperlukan, atau "tidak ada tindakan yang diperlukan"</td> <td>Kesunyian, yang diisi pembaca dengan skenario terburuk</td> </tr> <tr> <td>Tanggal untuk apa pun yang punya tenggat waktu</td> <td>Nomor versi yang menggantikan tanggal</td> </tr> <tr> <td>Tautan ke dokumen yang menjelaskan</td> <td>Tautan ke pull request</td> </tr> <tr> <td>Bug yang dilaporkan orang, dan batas yang dinaikkan</td> <td>Id tiket internal</td> </tr> <tr> <td>Bagian yang membosankan, satu baris masing-masing, di bawah</td> <td>Bagian yang membosankan bercampur dengan berita</td> </tr> </tbody></table> <p>Pemisahan antara release note dan <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">entri changelog</a> adalah yang membuat daftar ini mungkin: changelog menyimpan semuanya, jadi catatan bisa melewatkan sesuatu. Contoh beranotasi untuk setiap jenis entri dikumpulkan di <a href="https://changeloop.dev/blog/id/release-notes-examples/">contoh release notes</a>.</p> <h2>Pertanyaan yang dijawab setiap entri</h2> <p><strong>Apa yang bisa dilakukan pembaca sekarang yang sebelumnya tidak bisa, dan apa yang harus mereka lakukan?</strong></p> <p>Jika sebuah entri tidak bisa menjawab itu, entri tersebut milik changelog, bukan release notes. Kedua bagian penting. Bagian pertama adalah nilai. Bagian kedua adalah yang dilupakan tim, dan itu yang menghasilkan tiket dukungan ketika hilang.</p> <p>Dua contoh bagian kedua yang benar-benar bekerja:</p> <ul> <li>"Webhook yang ada tetap berfungsi hingga 1 November. Setelah itu, payload yang tidak ditandatangani akan ditolak."</li> <li>"Tidak ada tindakan yang diperlukan. Ekspor yang ada akan dienkode ulang secara otomatis saat Anda membukanya lagi."</li> </ul> <p>Yang kedua secara eksplisit mengatakan "tidak ada tindakan yang diperlukan". Kalimat itu layak ditulis setiap kali, karena pembaca yang tidak menemukannya akan mengasumsikan yang terburuk.</p> <h2>Bagaimana release notes harus diurutkan?</h2> <p>Urutkan berdasarkan konsekuensi bagi pembaca, jangan pernah berdasarkan bagian sistem yang berubah. Mengelompokkan berdasarkan API, dasbor, seluler dan infrastruktur adalah bagan organisasi Anda, bukan masalah pembaca.</p> <ol> <li><strong>Breaking change dan apa pun yang punya tenggat waktu.</strong> Selalu pertama, meski kecil. Jika pembaca berhenti membaca setelah satu baris, ini baris yang harus mereka baca. Jika tenggat waktunya adalah sunset, entri tersebut harus terdengar seperti <a href="https://changeloop.dev/blog/id/api-deprecation/">pemberitahuan deprecation</a>.</li> <li><strong>Apa yang baru dan akan mereka inginkan.</strong> Satu per paragraf, dengan hasil di klausa pertama.</li> <li><strong>Apa yang membaik.</strong> Bug yang dilaporkan, batas yang dinaikkan, hal-hal yang lambat.</li> <li><strong>Semua yang lain, sebagai daftar.</strong> Pembaruan dependensi, refactor internal, salinan kecil. Satu baris masing-masing. Tidak ada yang membaca bagian ini, dan tetap harus ada, karena orang yang mencarinya benar-benar membutuhkannya.</li> </ol> <h2>Penulisan ulang</h2> <p>Sebelum:</p> <blockquote> <p><strong>v4.2.0</strong> Memperbaiki masalah di mana endpoint <code>POST /exports</code> sesekali mengembalikan 500 saat beban tinggi. Merefaktor worker ekspor. Memperbarui <code>node-pg</code> ke 8.11. Meningkatkan penanganan error di serializer CSV.</p> </blockquote> <p>Sesudah:</p> <blockquote> <p><strong>Ekspor tidak lagi gagal pada akun besar.</strong> Akun dengan lebih dari sekitar 50.000 baris bisa mendapatkan 500 saat memulai ekspor, lebih sering di akhir bulan. Ini sudah diperbaiki, dan ekspor ukuran apa pun sekarang mencoba lagi sendiri alih-alih gagal. Tidak ada tindakan yang diperlukan, dan ekspor mana pun yang gagal minggu lalu bisa langsung dijalankan ulang.</p> <p>Juga di 4.2.0: <code>node-pg</code> 8.11, error yang lebih jelas di serializer CSV.</p> </blockquote> <p>Rilis yang sama. Yang kedua menyebutkan akun yang terdampak, saat kondisinya terburuk, apa yang berubah, dan apa yang harus dilakukan. Pembaruan dependensi tidak menghilang, hanya berhenti menjadi judul. Artikel <a href="https://changeloop.dev/blog/id/release-notes-best-practices/">praktik terbaik release notes</a> punya sisa aturan yang diikuti penulisan ulang ini, masing-masing dengan biaya melewatkannya.</p> <h2>Hal-hal yang layak dihapus</h2> <ul> <li><strong>"Kami dengan senang hati mengumumkan."</strong> Pembaca belum senang. Dapatkan itu di kalimat berikutnya.</li> <li><strong>Nomor tiket internal.</strong> <code>PROJ-4471</code> tidak berarti apa-apa di luar tracker Anda. Jika entri butuh referensi, tautkan ke halaman dokumen.</li> <li><strong>Nama komponen yang hanya digunakan tim Anda.</strong> Jika Anda mengganti nama "pipeline ingest", katakan "impor".</li> <li><strong>Nomor versi sebagai satu-satunya judul.</strong> <code>v4.2.0</code> adalah label pengarsipan, bukan ringkasan.</li> <li><strong>Screenshot halaman pengaturan yang tidak pernah dikunjungi siapa pun.</strong> Tunjukkan hal yang berubah, dalam penggunaan.</li> </ul> <h2>Seberapa sering release notes harus diterbitkan?</h2> <p>Terbitkan saat sesuatu terjadi, bukan sesuai jadwal. Catatan yang datang setiap rilis melatih semua orang untuk mengabaikannya. Catatan yang datang saat sesuatu terjadi dibuka. Tidak apa-apa, dan biasanya benar, untuk merilis tanpa catatan sama sekali dan menggulirkan entrinya ke set berikutnya yang punya judul yang layak dibaca.</p> <p>Changelog tetap mencatat semuanya. Itulah pembagian kerjanya: changelog lengkap, catatannya selektif. Jika Anda menjaga changelog tetap terstruktur seiring waktu, menulis catatan menjadi seleksi dan penulisan ulang, bukan arkeologi.</p> <p><a href="https://changeloop.dev/release-notes-template">Template release notes</a> adalah bentuk yang kami gunakan untuk langkah seleksi, dan <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> mengumpulkan entri dari tim yang changelog-nya cukup baik untuk diturunkan menjadi catatan.</p> <p>Semua ini mengasumsikan halaman yang sepenuhnya Anda kendalikan, tanpa batas panjang dan dengan tautan yang berfungsi. <a href="https://changeloop.dev/blog/id/mobile-app-release-notes/">Release notes untuk aplikasi mobile</a> membahas apa yang berubah saat permukaannya adalah daftar App Store atau Play Store. <a href="https://changeloop.dev/blog/id/emergency-release-notes/">Release notes darurat</a> membahas pengecualian lainnya: apa yang berubah saat tidak ada waktu tersisa sama sekali untuk mengikuti proses penulisan normal.</p> <h2>Satu tes sebelum menerbitkan</h2> <p>Baca catatan seperti seseorang yang baru liburan dua minggu dan punya 40 detik. Jika, dalam waktu itu, mereka tidak bisa memastikan apakah ada yang diminta dari mereka, catatan tersebut belum selesai, seakurat apa pun catatan itu.</p> <h2>FAQ</h2> <p><strong>Seberapa panjang release notes seharusnya?</strong> Sepanjang yang dibutuhkan perubahan berkonsekuensi, dan tidak lebih satu baris pun. Rilis dengan satu breaking change dan dua peningkatan adalah tiga paragraf. Mengisi rilis yang sepi agar terlihat substansial adalah cara pembaca belajar melewatkan catatan.</p> <p><strong>Siapa yang harus menulis release notes?</strong> Orang yang memahami perubahannya, diedit oleh seseorang yang tidak memahaminya. Insinyur tahu apa yang berubah; editor tahu apa yang akan salah dipahami orang luar. Menulis entri saat merge, selagi insinyur masih mengingatnya, adalah praktik yang membuat ini murah.</p> <p><strong>Apakah release notes harus mencakup perbaikan bug?</strong> Ya, yang dilaporkan atau dialami seseorang. Nyatakan gejala yang dilihat pembaca, bukan penyebabnya. "Ekspor lebih dari 50.000 baris gagal" adalah perbaikan yang dikenali pembaca; "memperbaiki race condition di worker ekspor" adalah pesan commit.</p> <p><strong>Apa perbedaan antara release notes dan changelog?</strong> Changelog adalah catatan lengkap dan berkelanjutan; release notes adalah pesan terkurasi tentang satu rilis, ditulis untuk orang yang belum memutuskan apakah mereka peduli. Jawaban yang lebih panjang ada di <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, benar-benar diimplementasikan</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog adalah konvensi satu halaman untuk <code>CHANGELOG.md</code>: versi terbaru dulu, satu bagian per versi dengan nomor dan tanggal ISO, entri dikelompokkan di bawah enam jenis (Added, Changed, Deprecated, Removed, Fixed, Security), dan bagian Unreleased di atas untuk entri antar rilis. Kebanyakan tim yang mengutipnya menerapkan sekitar dua pertiganya, dan sepertiga yang mereka lewatkan adalah sepertiga yang melindungi pengguna mereka.</p> <p>Olivier Lacan menerbitkan <a href="https://keepachangelog.com/">Keep a Changelog</a> pada 2014 dengan kalimat yang bertahan lebih baik daripada kebanyakan tulisan perangkat lunak: <em>don't let your friends dump git logs into changelogs</em>. Sepuluh tahun kemudian, ini adalah hal terdekat dengan standar yang dimiliki sudut perangkat lunak ini. Layak membaca sumbernya daripada ringkasannya; ini membahas bagian-bagian yang dilewatkan.</p> <h2>Apa yang diminta Keep a Changelog?</h2> <p><code>CHANGELOG.md</code> di root repo, terbaru dulu, dengan satu bagian per versi. Setiap versi membawa nomor dan tanggal ISO, dan mengelompokkan entrinya di bawah enam jenis:</p> <table> <thead> <tr> <th>Jenis</th> <th>Untuk</th> <th>Biaya melewatkannya</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Fitur baru</td> <td>Tidak ada; tidak ada yang melewatkan ini</td> </tr> <tr> <td>Changed</td> <td>Perubahan pada perilaku yang ada</td> <td>Pembaca menemukan perubahan perilaku dari sebuah error</td> </tr> <tr> <td>Deprecated</td> <td>Fitur yang akan dihapus</td> <td>Penghapusan menjadi insiden alih-alih peristiwa terjadwal</td> </tr> <tr> <td>Removed</td> <td>Fitur yang dihapus di rilis ini</td> <td>Tidak ada yang bisa membedakan penghapusan dari bug</td> </tr> <tr> <td>Fixed</td> <td>Perbaikan bug</td> <td>Tidak ada; tidak ada yang melewatkan ini juga</td> </tr> <tr> <td>Security</td> <td>Kerentanan</td> <td>Satu-satunya pembaca yang mencarinya tidak menemukannya</td> </tr> </tbody></table> <p>Ditambah bagian <code>Unreleased</code> di atas, sehingga ada tempat untuk meletakkan entri saat merge dilakukan, dan sehingga siapa pun bisa melihat apa yang akan datang.</p> <p>Itu hampir semuanya. Sisanya adalah alasannya: entri untuk manusia, satu entri per perubahan, dan berkas adalah dokumen alih-alih log.</p> <h2>Bagian mana dari Keep a Changelog yang dilewatkan?</h2> <p>Bagian Unreleased, lalu empat dari enam jenis, Security di antaranya, dalam urutan itu.</p> <p><strong><code>Unreleased</code> menghilang lebih dulu.</strong> Ini bagian tanpa tenggat waktu, jadi ini yang pemeliharaan-nya berhenti lebih dulu, dan begitu hilang entri ditulis saat rilis dari riwayat commit. Itu tepatnya dump git-log yang diperingatkan spesifikasi sejak awal, dicapai secara bertahap. <a href="https://changeloop.dev/blog/id/changelog-automation/">Otomatisasi changelog</a> sebagian besar tentang menjaga bagian ini tetap hidup tanpa perlu diingat siapa pun.</p> <p><strong>Enam jenis menyusut jadi dua.</strong> Kebanyakan changelog nyata berakhir dengan Added dan Fixed, karena Changed dan Deprecated memerlukan penilaian tentang apa yang diandalkan seseorang. Penilaian itu bagian yang berharga. Deprecated khususnya satu-satunya jenis yang merupakan janji tentang masa depan, dan melewatkannya adalah bagaimana penghapusan berubah menjadi insiden; mekanisme untuk menepati janji itu ada di <a href="https://changeloop.dev/blog/id/api-deprecation/">cara men-deprecate API</a>.</p> <p><strong>Security berhenti terpisah.</strong> Perbaikan keamanan yang diarsipkan di bawah Fixed tidak terlihat bagi satu-satunya pembaca yang mencarinya. Jaga tetap terpisah bahkan ketika perbaikannya sepele, dan terutama ketika Anda lebih memilih tidak menarik perhatian padanya.</p> <h2>Apa yang tidak dijawab spesifikasi?</h2> <p>Ini adalah format berkas. Tidak mengatakan apa-apa tentang pertanyaan yang segera Anda hadapi setelah mengadopsinya:</p> <ul> <li><strong>Bagaimana seseorang mengetahuinya?</strong> Berkas di repo menjangkau kontributor. Tidak menjangkau pelanggan yang tidak pernah membuka GitHub.</li> <li><strong>Bagaimana dengan produk tanpa versi?</strong> Layanan yang di-deploy terus-menerus tidak punya v4.2.0 untuk dikelompokkan. Kebanyakan tim menggantinya dengan tanggal, yang berhasil, dan spesifikasi tidak merestui atau melarangnya.</li> <li><strong>Siapa yang menulis entrinya?</strong> Spesifikasi mengasumsikan manusia yang melakukannya. Tidak mengatakan kapan.</li> <li><strong>Bagaimana dengan banyak audiens?</strong> Satu berkas melayani developer. Tidak melayani konten yang sama kepada admin non-teknis, dan memformat ulang secara manual untuk mereka adalah tempat duplikasi dimulai. <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">Changelog vs release notes</a> adalah pembagian yang dibiarkan spesifikasi untuk Anda buat sendiri.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, fork yang lebih ketat dari ide ini, memperketat sebagian ini: melarang formulasi entri tertentu, mewajibkan tautan ke perubahan, dan punya pendapat jelas tentang siapa pembacanya. Layak dibaca jika bagian longgar Keep a Changelog adalah yang terus diperdebatkan tim Anda.</p> <h2>Bisakah Keep a Changelog diotomatisasi tanpa membuang git log?</h2> <p>Bisa: turunkan draf dari commit terstruktur, letakkan di Unreleased dengan jenisnya sudah terisi awal, dan wajibkan manusia mengedit formulasinya sebelum rilis dipotong. Peringatan spesifikasi tentang keluarannya, bukan alatnya. Menurunkan draf dari commit tidak masalah. Menerbitkan draf itu tanpa penyuntingan yang ditentangnya.</p> <p>Mesin menangani pengumpulan dan pemformatan, yang dikuasainya. Manusia menangani seleksi dan formulasi, yang tidak dikuasainya. <a href="https://changeloop.dev/blog/id/conventional-commits-changelog/">Conventional commits</a> membahas pembagian dua lapis yang menjadi dasarnya, dan jenis commit mana yang berkaitan dengan kategori mana dari enam kategori di atas. Rangkuman <a href="https://changeloop.dev/changelog-tools">alat changelog</a> kami mencakup apa yang ada untuk separuh pengumpulan.</p> <h2>Di mana Keep a Changelog berhenti menjadi cukup?</h2> <p>Berhenti di distribusi. Keep a Changelog adalah jawaban yang baik untuk "seperti apa berkas ini seharusnya". Bukan jawaban untuk "bagaimana pengguna kami tahu apa yang berubah", karena berkas Markdown di repo adalah strategi distribusi yang hanya berhasil jika pengguna Anda adalah kontributor.</p> <p>Itulah rintangan yang dihadapi kebanyakan tim kedua: berkasnya baik-baik saja, dan tidak ada yang di luar tim membacanya. Menyelesaikannya berarti entri harus menjadi data yang bisa dirender di tempat lain, yang merupakan masalah berbeda dari memformat berkas, dan alasan mengapa <a href="https://changeloop.dev/changelog-examples">contoh changelog</a> mengumpulkan halaman changelog publik alih-alih berkas repositori. Cara mengubah entri itu menjadi sesuatu yang diikuti orang dibahas di <a href="https://changeloop.dev/blog/id/changelog-page/">cara membangun halaman changelog</a>.</p> <p>Adopsi spesifikasinya tetap saja. Butuh satu sore, membuat masalah kedua bisa ditangani, dan masih halaman terbaik yang pernah ditulis tentang ini.</p> <h2>FAQ</h2> <p><strong>Apakah Keep a Changelog sebuah standar?</strong> Ini konvensi yang diadopsi secara luas, bukan spesifikasi badan standardisasi. Alat (skrip rilis, linter, parser) sering cukup mengasumsikan bentuknya sehingga mengikutinya membeli kompatibilitas.</p> <p><strong>Apa yang masuk ke bagian Unreleased?</strong> Setiap entri untuk perubahan yang sudah di-merge tapi belum dirilis dalam versi bernomor. Ketika rilis dipotong, bagian tersebut diganti nama menjadi versi dan tanggal, dan bagian Unreleased baru yang kosong ditempatkan di atasnya.</p> <p><strong>Haruskah changelog menggunakan versi semantik?</strong> Keep a Changelog merekomendasikannya dan tidak mewajibkannya. Pustaka dan API mendapat manfaat; layanan yang di-deploy terus-menerus biasanya menggantinya dengan tanggal, yang diakomodasi formatnya.</p> <p><strong>Haruskah perbaikan keamanan ada di changelog sebelum dipublikasikan?</strong> Tambahkan entrinya saat perbaikan dirilis, dengan detail cukup untuk operator bisa bertindak dan tidak lebih. Menunda entri hingga tanggal pengungkapan terkoordinasi itu normal; menghilangkannya tidak.</p> </article> <article> <h1>Praktik terbaik release notes yang layak dipertahankan</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Praktik terbaik release notes yang penting adalah yang punya konsekuensi terlampir: tulis entri saat merge, sebutkan siapa yang terdampak, nyatakan tindakan yang diperlukan bahkan jika tidak ada, beri tanggal pada breaking change, pertahankan satu entri permanen per perubahan, kelompokkan berdasarkan hasil, dan pertahankan bagian yang membosankan. Masing-masing mengubah apa yang dilakukan pembaca. Sebagian besar saran lain tentang topik ini mengubah tampilan catatan.</p> <p>Cari praktik terbaik release notes dan Anda mendapatkan saran gaya: jelas, ringkas, gunakan bahasa sederhana, tambahkan screenshot. Tidak ada yang salah dari itu semua dan tidak ada yang mengubah apa pun, karena tidak ada tim yang pernah duduk dengan niat menjadi tidak jelas. Praktik di bawah ini disertai dengan biaya melewatkannya, karena praktik tanpa mode kegagalan terlampir hanyalah preferensi.</p> <table> <thead> <tr> <th>Praktik</th> <th>Biaya melewatkan</th> </tr> </thead> <tbody><tr> <td>Menulis entri saat merge, bukan saat rilis</td> <td>Entri yang direkonstruksi kemudian mengatakan "berbagai peningkatan"</td> </tr> <tr> <td>Menyebutkan siapa yang terdampak</td> <td>Setiap pembaca memutuskan itu tidak berlaku untuknya</td> </tr> <tr> <td>Menyatakan tindakan yang diperlukan, termasuk "tidak ada"</td> <td>Empat puluh tiket dukungan yang identik, dan pembaca yang mengasumsikan yang terburuk</td> </tr> <tr> <td>Memberi tanggal pada breaking change, bukan memversikannya</td> <td>Tenggat waktu ditemukan setelah lewat</td> </tr> <tr> <td>Satu entri permanen dan bisa ditautkan per perubahan</td> <td>Tidak ada yang bisa menjawab "kapan ini berubah"</td> </tr> <tr> <td>Mengelompokkan berdasarkan hasil, bukan sistem</td> <td>Pembaca membutuhkan arsitektur Anda untuk menemukan bagian mereka</td> </tr> <tr> <td>Mempertahankan bagian yang membosankan</td> <td>Keamanan, kepatuhan, dan yang men-debug ketidakcocokan versi kehilangan sumber mereka</td> </tr> </tbody></table> <h2>Apa saja praktik terbaik untuk release notes?</h2> <p><strong>Tulis entri saat Anda merge, bukan saat Anda rilis.</strong> Biaya melewatkan: orang yang merekonstruksi rilis dari riwayat commit bukan yang membuat perubahan, dan akan menebak niatnya. Entri yang ditulis dua minggu kemudian adalah yang mengatakan "berbagai peningkatan".</p> <p><strong>Sebutkan siapa yang terdampak, dengan nama.</strong> "Tim di paket Business", "siapa pun yang menggunakan API ekspor v1", "instalasi self-hosted di Postgres 14". Biaya melewatkan: setiap pembaca harus mencari tahu apakah itu berlaku untuknya, dan kebanyakan akan memutuskan tidak.</p> <p><strong>Nyatakan tindakan yang diperlukan, termasuk saat tidak ada.</strong> Biaya melewatkan: dukungan menjawab pertanyaan yang sama empat puluh kali, dan pembaca yang tidak bertanya berasumsi sesuatu diperlukan dan menundanya.</p> <p><strong>Beri breaking change tanggal, bukan nomor rilis.</strong> "Dihapus di v5" tidak berarti apa-apa bagi yang tidak tahu kapan v5 tiba. "Berhenti berfungsi pada 1 November" berarti hal yang sama untuk semua orang. Biaya melewatkan: tenggat waktu ditemukan setelah lewat. Apa yang termasuk itu, dan checklist untuk merilisnya, ada di <a href="https://changeloop.dev/blog/id/breaking-changes/">apa itu breaking change</a>.</p> <p><strong>Pertahankan satu entri permanen dan bisa ditautkan per perubahan.</strong> Email bukan arsip dan pesan Slack bukan referensi. Biaya melewatkan: tidak ada yang bisa menjawab "kapan ini berubah" enam bulan kemudian, termasuk Anda. Email tetap punya tugas, dibahas di <a href="https://changeloop.dev/blog/id/product-update-email/">template email update produk</a>; ia menunjuk ke entri alih-alih menggantikannya.</p> <p><strong>Kelompokkan berdasarkan hasil, bukan sistem.</strong> Biaya melewatkan: pembaca harus menyimpan arsitektur Anda di kepala untuk mengetahui bagian mana yang relevan bagi mereka. Urutan yang mengikuti ini ada di <a href="https://changeloop.dev/blog/id/how-to-write-release-notes/">cara menulis release notes</a>.</p> <p><strong>Pertahankan bagian yang membosankan.</strong> Pembaruan dependensi dan perubahan internal tetap ada, di bawah, satu baris masing-masing. Biaya melewatkan: tim keamanan, peninjau kepatuhan, dan yang men-debug ketidakcocokan versi kehilangan satu-satunya sumber mereka. Entri yang paling sering salah di sini adalah perbaikan; <a href="https://changeloop.dev/blog/id/bug-fix-release-notes/">release notes perbaikan bug</a> menunjukkan cara menulisnya agar pembaca tahu apakah mereka perlu bertindak.</p> <h2>Apa saja praktik terbaik changelog, dan bagaimana bedanya?</h2> <p>Changelog adalah referensi, jadi praktiknya tentang kelengkapan dan struktur, bukan persuasi. Empat yang penting:</p> <ul> <li><strong>Satu jenis entri tetap per baris.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Bukan gaya rumah, tapi filter: itu yang memungkinkan permintaan "hanya breaking change". Konvensi <a href="https://changeloop.dev/blog/id/keep-a-changelog-implemented/">Keep a Changelog</a> adalah sumber yang biasa.</li> <li><strong>Bagian belum rilis.</strong> Tempat entri hidup antara merge dan rilis. Ketiadaannya adalah alasan mengapa tim menulis entri terlambat.</li> <li><strong>Tanggal ISO.</strong> <code>2026-08-28</code>, bukan <code>28/08/26</code>, yang berarti dua hari berbeda tergantung pembaca.</li> <li><strong>Satu entri per perubahan, bukan per commit.</strong> Tiga commit yang memperbaiki satu bug adalah satu entri.</li> </ul> <p>Kedua artefak dibandingkan secara menyeluruh di <a href="https://changeloop.dev/blog/id/changelog-vs-release-notes/">changelog vs release notes</a>; versi singkatnya adalah praktik changelog melindungi kelengkapan dan praktik release notes melindungi perhatian. <a href="https://changeloop.dev/blog/id/private-release-notes-enterprise/">Release notes privat untuk pelanggan enterprise</a> membahas versi ini yang baru muncul begitu pelanggan Anda tidak lagi semuanya berada di build yang sama: tujuan kelengkapan dan perhatian yang sama, tapi disesuaikan per akun alih-alih disiarkan ke semua sekaligus.</p> <h2>Tiga yang ternyata kultus kargo</h2> <p><strong>Emoji sebagai jenis entri.</strong> Roket dan kunci pas bukan taksonomi. Terlihat rapi dan tidak bisa difilter, diurutkan, atau dibaca secara berguna oleh pembaca layar. Gunakan kata-kata, dan jika Anda menginginkan emoji, letakkan setelah kata.</p> <p><strong>Nomor versi semantik sebagai judul untuk produk yang di-hosting.</strong> Semver adalah janji tentang kompatibilitas API. Untuk produk SaaS di mana tidak ada yang memilih versinya, nomor versi di judul adalah pengarsipan internal yang menyamar sebagai berita. Simpan semver di changelog dan jangan masukkan ke pengumuman.</p> <p><strong>Menerbitkan sesuai jadwal terlepas dari konten.</strong> Catatan bulanan tanpa isi mengajarkan orang bahwa catatan Anda adalah kebisingan. Terbitkan saat ada sesuatu untuk disampaikan. Changelog mencakup sisanya.</p> <h2>Yang benar-benar sulit</h2> <p>Menjaga changelog dan pengumuman tetap selaras, tanpa menulis semuanya dua kali.</p> <p>Kebanyakan tim mulai dengan satu halaman, membaginya saat audiens berbeda, lalu diam-diam membiarkan salah satunya membusuk, biasanya changelog, karena itu yang tidak punya tenggat waktu terlampir. Jalan keluarnya bersifat struktural, bukan disiplin: simpan entri sebagai data dengan jenis, tanggal, dan audiens, dan perlakukan kedua permukaan sebagai rendering dari itu. Rangkuman <a href="https://changeloop.dev/changelog-tools">alat changelog</a> kami mencakup apa yang tersedia untuk itu, termasuk alat yang kami saingi, dan halaman <a href="https://changeloop.dev/beamer-alternative">alternatif Beamer</a> adalah perbandingan jujur terhadap widget tempat kebanyakan tim memulai.</p> <p><a href="https://changeloop.dev/release-notes-template">Template release notes</a> adalah tempat langkah seleksi berada begitu entri sudah ada.</p> <h2>Jika Anda hanya menerapkan satu hal</h2> <p>Tulis entri saat merge, dalam format tetap, dengan satu jenis. Setiap praktik lain di halaman ini menjadi lebih mudah begitu itu diterapkan, dan tidak ada yang bertahan tanpanya.</p> <h2>FAQ</h2> <p><strong>Haruskah release notes punya screenshot?</strong> Hanya dari hal yang berubah, dalam penggunaan. Screenshot halaman pengaturan yang tidak pernah dikunjungi siapa pun menambah gulir, bukan informasi. Teks yang menyebutkan hasil dan pembaca yang terdampak mengalahkan gambar yang tidak menunjukkan keduanya.</p> <p><strong>Bagaimana cara menulis release notes untuk breaking change?</strong> Pertama tanggal, kedua pemanggil yang terdampak, ketiga tindakan yang diperlukan, keempat migrasi. Jangan pernah memulai dengan nomor versi. Bentuk lengkapnya, dengan contoh entri, ada di <a href="https://changeloop.dev/blog/id/breaking-changes/">apa itu breaking change</a>.</p> <p><strong>Haruskah release notes ditulis oleh engineering atau marketing?</strong> Disusun oleh insinyur yang membuat perubahan, saat merge, dan diedit oleh seseorang yang membacanya sebagai orang luar. Tidak ada satu pun yang sendirian menghasilkan catatan yang bisa ditindaklanjuti pelanggan.</p> <p><strong>Apa format ideal untuk release notes?</strong> Pertama item dengan tenggat waktu, lalu kemampuan baru, lalu peningkatan, lalu daftar satu baris masing-masing untuk sisanya. <a href="https://changeloop.dev/release-notes-template">Template release notes</a> adalah format itu sebagai halaman untuk diisi.</p> </article> </main></body></html>