Jika Anda mengerjakan produk digital, cepat atau lambat akan tiba saatnya untuk bertanya pada diri sendiri Cara menulis catatan perubahan yang bermanfaat dan memudahkan pekerjaan tim. Dan, sebagai tambahan, agar pelanggan Anda dapat dengan mudah memahami perubahan yang terjadi. Banyak tim memulai dengan catatan rilis yang hilang di pusat bantuan atau tersembunyi dalam commit Git, sampai mereka menyadari bahwa tidak ada yang membacanya atau menggunakannya.
Kabar baiknya adalah, dengan metode tertentu, kekacauan ini dapat diubah menjadi sistem yang memberikan kontribusi. Kejelasan, transparansi, dan nilai nyata untuk pembangunan, bisnis, pelanggan, investor, dan dukungan.Mari kita lihat, langkah demi langkah, bagaimana mendesain changelog yang berfungsi setiap hari, dengan memanfaatkan praktik teknis terbaik (Git, otomatisasi, template…) dan sisi manusiawi dari manajemen perubahan dalam organisasi.
Apa itu changelog dan mengapa hal itu sangat penting?
Pada dasarnya, catatan perubahan (changelog) adalah... catatan kronologis tentang perubahan relevan yang dilakukan pada suatu produkFitur baru, peningkatan, perbaikan, perubahan teknis mendalam, penghapusan fitur lama, eksperimen… Ini akan menjadi “buku harian evolusi” perangkat lunak Anda, yang ditulis sedemikian rupa sehingga siapa pun dapat mengikuti apa yang telah terjadi antara satu versi dan versi berikutnya.
Dalam praktiknya, biasanya muncul dua jenis utama catatan perubahan (changelog), yang perlu dibedakan sejak awal karena Nuansa, kedalaman, dan audiensnya berbeda. dalam setiap kasus:
- Siaran pers bisnisIni adalah catatan yang dirancang untuk pengguna non-teknis dan profil bisnis. Catatan ini menjelaskan secara sederhana apa yang baru, apa yang telah ditingkatkan, dan masalah apa yang telah dipecahkan, selalu berfokus pada manfaat dan kasus penggunaan.
- Catatan Perubahan TeknisIni berfokus pada detail implementasi: perubahan basis data, refaktorisasi, migrasi, versi dependensi, skrip yang dijalankan… Ini membantu tim memahami apa yang terjadi tanpa harus menelusuri setiap commit satu per satu.
Kedua jenis catatan tersebut penting karena Keduanya memiliki tujuan yang berbeda namun saling melengkapi.Secara internal, mereka memberikan konteks dan kendali; secara eksternal, mereka menunjukkan kemajuan, membangun kepercayaan, dan membantu mengkomunikasikan nilai.
Keuntungan nyata dari memelihara changelog yang baik
Lebih dari sekadar "terlihat profesional," catatan perubahan yang terawat dengan baik menawarkan manfaat yang sangat nyata bagi tim, perusahaan, dan pengguna.Ini bukan sekadar dokumentasi yang bagus: ini adalah alat yang berfungsi.
Pertama, ini menjadi bagian kunci untuk menyelesaikan insiden dan menganalisis regresiJika terjadi kesalahan produksi, kemampuan untuk meninjau dengan cepat apa yang dirilis pada hari itu (komponen, versi, migrasi, skrip yang dijalankan) menghemat waktu investigasi berjam-jam dan mengurangi waktu penyelesaian rata-rata.
Kedua, catatan perubahan yang jelas dan terbuka merupakan cara yang ampuh untuk Menerapkan transparansi dan memperkuat kepercayaan pada produk.Pelanggan dan pemangku kepentingan melihat bahwa produk tersebut terus berkembang, bahwa masalah-masalah sedang diperbaiki, dan bahwa ada peta jalan yang dinamis, alih-alih menganggap produk tersebut sebagai "kotak hitam" yang berubah tanpa penjelasan.
Selain itu, untuk profil bisnis, pemasaran, atau investor, catatan perubahan (changelog) berfungsi sebagai contoh nilai yang telah diberikan: Ini menunjukkan evolusi produk dari waktu ke waktu.Hal ini membantu untuk melacak prioritas dan memungkinkan Anda untuk menilai apakah laju peningkatan sejalan dengan tujuan perusahaan.
Kita juga tidak boleh melupakan kegunaan internalnya: bagi pengembang, produk, QA, atau dukungan, registri yang terorganisir dengan baik memungkinkan untuk menyegarkan kembali ingatan tentang apa yang terjadi dalam sebuah sprint atau dalam sebuah rilis. tanpa harus melacak lusinan cabang dan penggabungan di Git. Dan untuk dukungan, ini berfungsi sebagai skrip untuk menanggapi pelanggan tentang apa yang baru atau masalah apa yang baru saja diperbaiki.
Hal ini juga memiliki komponen motivasi yang signifikan: melihat sejarah perubahan yang terorganisir membantu untuk visualisasikan kerja kolektif yang dilakukan dari waktu ke waktuSesuatu yang sering kali terlupakan di antara tiket dan komitmen, dan melihatnya tercermin memperkuat kebanggaan tim.
Catatan perubahan pribadi: catatan internal yang berisi semua hal.
Sebagian besar produk membutuhkan, setidaknya, satu Catatan perubahan pribadi, teknis, dan cukup detail.Dokumen ini menjadi dasar untuk audit, diagnostik, dan koordinasi antar tim. Meskipun Anda mungkin nantinya menerbitkan versi yang lebih sederhana untuk klien, ini adalah dokumen "asli" yang menjadi dasar dari semua hal lainnya.
Dalam banyak sistem, catatan ini berbentuk tabel atau dokumen terstruktur di mana kolom-kolom seperti berikut dikumpulkan untuk setiap rilis atau versi produksi: Modul atau komponen yang terpengaruh, jenis perubahan yang dilakukan, versi sebelumnya dan versi baru, catatan khusus, penanggung jawab teknis, dan tautan ke pengujian. (misalnya, untuk kasus pengujian, bukti, atau pipeline CI).
Ketika perubahan tersebut berdampak pada basis data, mendokumentasikannya sangatlah penting. rincian operasi yang dilakukan dan referensi ke skrip spesifik tersebut Dirilis ke tahap produksi. Dengan cara ini, jika beberapa bulan kemudian mereka perlu meninjau kembali apa yang telah dilakukan, tim tidak perlu menyusun ulang cerita tersebut secara manual.
Catatan perubahan pribadi ini dapat dicatat per penerapan (setiap "peluncuran produksi") atau per versi aplikasi. Pada produk yang sangat dapat disesuaikan, catatan ini juga dapat diorganisir. berdasarkan kasus penggunaan atau berdasarkan pelanggan, yang menunjukkan bagaimana setiap skenario telah berkembang dari waktu ke waktu.
Praktik terbaik untuk catatan perubahan pribadi
Untuk mencegah agar catatan internal tersebut tidak menjadi dokumen mati, hal terpenting adalah: Harus dihosting di lokasi yang mudah diakses, aman, dan mudah diedit oleh tim.Ini bisa berupa ruang di wiki perusahaan, dokumen bersama yang terstruktur dengan baik, atau disimpan langsung di repositori (misalnya, sebagai CHANGELOG internal).
Sebaiknya sistem yang dipilih juga memungkinkan hal tersebut. Memelihara persyaratan keamanan dan kontrol akses. Hal ini diperlukan dalam proyek, terutama jika detail teknis sensitif atau data infrastruktur disertakan.
Kuncinya adalah membuat proses pembaruan cukup lincah sehingga tim tidak menganggapnya sebagai beban tambahan yang tidak berkelanjutan, karena Catatan perubahan yang sudah usang hampir lebih buruk daripada tidak memiliki catatan perubahan sama sekali.Hal ini memberikan informasi keamanan yang salah dan memaksa Anda untuk memverifikasi semuanya melalui cara lain.
Catatan perubahan publik: bagaimana menyampaikan pesan yang sama tanpa berlebihan
Berdasarkan catatan internal yang terperinci tersebut, seseorang dapat membangun sebuah Catatan perubahan publik, jauh lebih ramah pengguna dan ditujukan untuk pengguna akhir.Aspek teknis "bagaimana" tidak sepenting "apa" dan "mengapa": masalah apa yang dipecahkan, apa yang meningkatkan pengalaman, apa yang dapat mereka lakukan sekarang yang tidak dapat mereka lakukan sebelumnya.
Meskipun konten dasarnya sama dengan versi internal, pesannya berubah secara radikal: detail implementasi dihilangkan dan perubahannya diterjemahkan ke dalam bahasa bisnis, studi kasus, dan manfaat konkretBiasanya, fitur-fitur tersebut dikelompokkan ke dalam beberapa bagian, seperti "Fitur baru" dan "Perbaikan dan peningkatan".
Anda bahkan bisa melangkah lebih jauh dengan menggabungkan blok kecil dengan fitur yang akan datang atau sedang dikembangkanHal ini memungkinkan pengguna untuk mengetahui apa yang akan datang dalam jangka pendek atau menengah. Ini membantu mengelola ekspektasi dan menunjukkan bahwa ada peta jalan yang dinamis.
Ini juga tempat yang bagus untuk menambahkan pesan terima kasih, pemberitahuan, atau permintaan maaf Ketika terjadi insiden yang relevan, kami menggunakan catatan perubahan (changelog) sebagai saluran komunikasi yang jujur dengan basis pengguna.
Beberapa produk menyertakan entri catatan perubahan publik dengan tangkapan layar atau GIF animasi Mereka menampilkan fitur baru tersebut secara langsung, mirip dengan alat-alat yang sudah dikenal dalam ekosistem pengembangan. Secara visual, ini sangat membantu pengguna memahami perubahan tanpa harus membaca paragraf yang panjang.
Tips untuk menyusun dokumen publik
Aturan emasnya di sini adalah Tulislah dengan mempertimbangkan orang yang akan menggunakan alat tersebut, bukan orang yang membuatnya.Artinya, menghindari jargon teknis yang tidak perlu, menjelaskan dampaknya ("sekarang Anda dapat melakukan X lebih cepat") dan memprioritaskan apa yang benar-benar memengaruhi kehidupan sehari-hari pengguna.
Sebaiknya struktur yang mudah dikenali dipertahankan dari satu versi ke versi lainnya, agar pembaca dapat dengan cepat menemukan informasi yang relevan. bagian yang paling menarik bagi Anda (Sebagai contoh, pertama fitur baru, kemudian peningkatan, dan terakhir perbaikan bug). Konsistensi memudahkan untuk mengembangkan kebiasaan membaca catatan perubahan (changelog).
Terakhir, penting agar entri-entri tersebut cukup jelas sehingga tim dukungan dapat... Salin dan adaptasi teks catatan perubahan dengan mudah Saat menanggapi tiket atau menyiapkan komunikasi, jika teks tersebut bermanfaat dalam menjelaskan perubahan kepada pelanggan, Anda berada di jalur yang benar.
Changelog, Git, dan otomatisasi dipahami dengan benar.
Jika Anda menggunakan Git sebagai sistem kontrol versi Anda (praktik paling umum saat ini), Anda memiliki sumber informasi yang sangat berharga yang dapat Anda manfaatkan untuk menghasilkan catatan perubahan (changelog) dengan cara yang lebih sistematis dan tidak mudah terlupakan.Namun, hal itu harus dilakukan dengan bijaksana.
Langkah pertama adalah menjaga disiplin dengan melakukan komitmen: pesan yang deskriptif, konsisten, dan, jika memungkinkan, berdasarkan standar. seperti Conventional Commits. Ini memungkinkan perubahan diklasifikasikan secara otomatis ke dalam tipe (feat, fix, docs, refactor…), yang kemudian diterjemahkan ke dalam bagian-bagian changelog.
Berdasarkan hal tersebut, alat-alat seperti changelog konvensional, git-changelog, atau generator yang terintegrasi dalam platform seperti GitHub atau GitLab. untuk mengekstrak perubahan antar tag atau rilis dan memasukkannya ke dalam file CHANGELOG yang diorganisir berdasarkan versi.
Alur kerja tipikalnya adalah: menginisialisasi repositori, mengerjakan cabang dengan commit yang ditulis dengan baik, memberi label pada versi, dan kemudian Buat catatan perubahan secara otomatis atau semi-otomatis dari riwayat.misalnya, dengan mengintegrasikannya ke dalam sebuah Pipeline CI/CD dengan GitHub ActionsKemudian ditinjau, bahasanya disempurnakan, dan versi publik diterbitkan jika sesuai.
Otomatisasi ini tidak menggantikan penilaian manusia, tetapi membantu dalam hal untuk mencegah perubahan tidak terdokumentasi Memperbarui changelog membutuhkan sedikit usaha. Namun, jika standar diabaikan dalam pesan commit, kegunaan sistem akan menurun drastis.
Langkah-langkah penting untuk membangun changelog yang solid
Di luar alat-alat spesifik, akan sangat membantu jika kita memikirkan desain changelog sebagai sebuah proses kecil yang terdiri dari beberapa tahap, yang diulang dari versi ke versi dan memungkinkan untuk menjaga kualitas dan kegunaan catatan tersebut..
Tahap pertama terdiri dari Identifikasi semua pembaruan yang relevan sejak versi terakhir.Ini bukan tentang mengumpulkan setiap perubahan kecil internal, tetapi tentang mengumpulkan fitur, perbaikan, dan peningkatan yang memiliki dampak nyata pada produk.
Maka Anda harus mengorganisir perubahan-perubahan tersebut berdasarkan versi dan, di dalam setiap versi, berdasarkan kategori.Merupakan praktik umum untuk mengelompokkannya ke dalam blok seperti "Ditambahkan / Baru", "Ditingkatkan / Diubah", "Diperbaiki", "Tidak Digunakan Lagi" atau yang serupa, sehingga sangat mudah untuk menemukan jenis perubahan apa yang telah terjadi.
Selanjutnya adalah bagian penulisan: mendeskripsikan setiap perubahan dengan bahasa yang jelas dan tepat. Idealnya, Jelaskan apa yang telah dilakukan dan mengapa hal itu relevan.menghindari frasa kosong seperti "beberapa perbaikan kecil" yang tidak menguntungkan siapa pun.
Setelah versi, kategori, dan deskripsi ditentukan, disarankan untuk mengadopsi format standar dan konsisten Mengenai judul, urutan, gaya kalimat, penggunaan tautan, dll., ini mempermudah pembacaan dan integrasi dengan alat eksternal (generator, skrip penerbitan).
Terakhir, setiap rilis baru harus disertai dengan hal-hal berikut: Memperbarui catatan perubahan dan mengkomunikasikannya kepada tim terkait., baik melalui platform kode itu sendiri (rilis di GitHub/GitLab), situs web produk, pusat bantuan, atau kampanye email dan media sosial.
Cara mengelola dan memelihara catatan perubahan (changelog) dari waktu ke waktu
Kesulitan sebenarnya bukanlah membuka file CHANGELOG, tetapi untuk menjaga agar tetap berfungsi dan dapat diandalkan sepanjang masa proyek.Oleh karena itu, hal ini perlu diperlakukan sebagai bagian lain dari alur kerja dan bukan sebagai sesuatu yang diisi terburu-buru di akhir "jika ada waktu".
Pertama-tama, akan sangat membantu jika kita mendefinisikannya dari awal. Struktur yang jelas, kompatibel dengan alat eksternal, dan mudah diikuti.Skema klasik adalah dengan mencantumkan versi-versi tersebut dalam urutan terbalik (yang terbaru terlebih dahulu) dan, di dalam setiap versi, bagian-bagian dengan daftar singkat perubahan.
Selain itu, format yang dipilih juga harus mudah dibaca dan diedit oleh manusia: Markdown dan HTML biasa biasanya merupakan pilihan yang baik karena... Mereka terintegrasi dengan baik dengan repositori dan sistem manajemen dokumen. dan mudah diproses oleh skrip.
Mengenai konten, sebaiknya fokus pada perubahan signifikan (fitur baru, perbaikan bug besar, keputusan arsitektur, perubahan perilaku) dan hindari terlalu banyak uraian tentang hal-hal sepele. Changelog yang penuh dengan hal-hal yang tidak penting akan membuatnya... Informasi penting hilang di antara puluhan catatan sepele..
Kunci lainnya adalah jangan membebankan seluruh tanggung jawab pada satu orang: idealnya, Seluruh tim merasa turut serta dalam upaya mempertahankan rekor tersebut.Setiap orang dapat menyumbangkan draf dari tiket atau cerita pengguna mereka, yang kemudian ditinjau dan dikonsolidasikan oleh seseorang yang memiliki visi global.
Terakhir, sangat praktis untuk menghubungkan changelog dengan alat manajemen pekerjaan itu sendiri (masalah, tugas, insiden). Di banyak lingkungan, tag dan referensi silang digunakan untuk tujuan ini. Hubungkan setiap entri changelog ke isu atau pull request yang terkait., memfasilitasi ketertelusuran jika diperlukan penyelidikan lebih lanjut.
Alat dan sumber daya untuk memprofesionalkan catatan perubahan Anda.
Setelah fondasi diletakkan, saatnya mengandalkan alat-alat yang mempermudah tugas dan memungkinkan mengotomatiskan sebagian proses tanpa kehilangan kendali pada hasil akhir.
Di satu sisi, terdapat utilitas yang menghasilkan catatan rilis dari tag dan pesan commit, seperti Generator catatan rilis Git atau skrip berdasarkan konvensi pesan. Biasanya, Anda dapat menyesuaikan format output agar sesuai dengan template Anda.
Platform hosting kode itu sendiri menawarkan fitur-fitur yang bermanfaat: misalnya, Mekanisme rilis GitHub atau GitLab Fitur ini memungkinkan Anda membuat versi yang diberi tag dan menulis catatan perubahan terkait langsung di sana, yang kemudian dapat disinkronkan dengan dokumentasi publik.
Terdapat juga panduan dan templat standar, seperti inisiatif "Keep a Changelog" yang terkenal, yang mengusulkan struktur bagian dan konvensi penamaan yang standarMenerapkan hal seperti ini akan membantu siapa pun yang terbiasa dengan standar tersebut untuk menavigasi registri Anda.
Terakhir, terdapat generator daring yang mampu membandingkan tag dalam sebuah repositori dan menghasilkan draf catatan perubahan di antara tag-tag tersebut. Alat-alat semacam ini sangat berguna dalam proyek kolaboratif dengan banyak kontributordi mana mengkompilasi semua perubahan secara manual akan tidak praktis.
Apa pun susunan tumpukan yang dipilih, yang terpenting adalah bahwa Alat-alat tersebut beradaptasi dengan alur kerja tim Anda. dan bukan sebaliknya. Sistem yang sangat ampuh, tetapi dianggap asing atau kompleks, pada akhirnya akan jarang digunakan atau digunakan dengan buruk.
Pada akhirnya, membuat dan memelihara changelog yang baik bukan hanya tentang mencantumkan perubahan, tetapi tentang... Membangun narasi yang jelas dan jujur tentang evolusi produk.Hal ini membantu tim bekerja lebih baik, mengurangi risiko di setiap implementasi, dan mengkomunikasikan kepada klien dan pemangku kepentingan bahwa perangkat lunak tersebut aktif, terawat, dan bergerak ke arah yang mudah dipahami.
