Jika anda mengusahakan produk digital, lambat laun akan tiba masanya untuk bertanya kepada diri sendiri Cara menulis log perubahan berguna yang memudahkan kerja pasukan Dan, secara kebetulan, pelanggan anda boleh memahami dengan mudah apa yang telah berubah. Banyak pasukan bermula dengan nota keluaran yang hilang di pusat bantuan atau tersembunyi dalam komitmen Git, sehingga mereka menyedari bahawa tiada siapa yang membaca atau menggunakannya.
Berita baiknya ialah dengan beberapa kaedah, kekacauan ini boleh diubah menjadi sistem yang menyumbang Kejelasan, ketelusan dan nilai sebenar untuk pembangunan, perniagaan, pelanggan, pelabur dan sokongan.Mari kita lihat, langkah demi langkah, cara mereka bentuk log perubahan yang berfungsi setiap hari, memanfaatkan amalan teknikal terbaik (Git, automasi, templat…) dan aspek pengurusan perubahan yang lebih berperikemanusiaan dalam organisasi.
Apakah itu changelog dan mengapa ia begitu penting?
Log perubahan, pada asasnya, rekod kronologi perubahan berkaitan yang dibuat pada sesuatu produkCiri-ciri baharu, penambahbaikan, pembetulan, perubahan teknikal yang mendalam, penolakan, eksperimen… Ia akan menjadi "diari evolusi" perisian anda, yang ditulis sedemikian rupa sehingga sesiapa sahaja boleh mengikuti apa yang telah berlaku antara satu versi dan versi seterusnya.
Dalam praktiknya, dua jenis utama changelog biasanya muncul, yang harus dibezakan dari awal kerana Nada, kedalaman, dan khalayak adalah berbeza dalam setiap kes:
- Siaran perniagaanIni adalah nota yang direka untuk pengguna bukan teknikal dan profil perniagaan. Ia menerangkan dengan mudah apa yang baharu, apa yang telah diperbaiki dan masalah yang telah diselesaikan, sentiasa memberi tumpuan kepada faedah dan kes penggunaan.
- Log Perubahan TeknikalIa memberi tumpuan kepada butiran pelaksanaan: perubahan pangkalan data, pemfaktoran semula, migrasi, versi kebergantungan, skrip yang dilaksanakan… Ia membantu pasukan memahami apa yang berlaku tanpa perlu menyelami komit demi komit.
Kedua-dua jenis rekod adalah penting kerana Mereka mempunyai tujuan yang berbeza tetapi saling melengkapiSecara dalaman mereka menyediakan konteks dan kawalan; secara luaran mereka menunjukkan kemajuan, membina kepercayaan dan membantu menyampaikan nilai.
Kelebihan sebenar mengekalkan changelog yang baik
Selain sekadar "kelihatan profesional," log perubahan yang diselenggara dengan baik menawarkan manfaat yang sangat konkrit untuk pasukan, syarikat dan penggunaIa bukan sekadar dokumentasi yang cantik: ia juga merupakan alat yang berfungsi.
Pertama, ia menjadi bahagian penting untuk menyelesaikan insiden dan menganalisis regresiSekiranya berlaku ralat pengeluaran, keupayaan untuk menyemak semula dengan cepat apa yang dikeluarkan pada hari itu (komponen, versi, migrasi, skrip yang dilaksanakan) menjimatkan masa penyiasatan dan mengurangkan purata masa penyelesaian.
Kedua, log perubahan awam yang jelas merupakan cara yang ampuh untuk mengamalkan ketelusan dan mengukuhkan keyakinan terhadap produkPelanggan dan pihak berkepentingan melihat bahawa produk sedang berkembang, masalah sedang diatasi, dan terdapat pelan tindakan yang hidup, dan bukannya melihat "kotak hitam" yang berubah tanpa penjelasan.
Tambahan pula, untuk profil perniagaan, pemasaran atau pelabur, log perubahan bertindak sebagai pameran nilai yang disampaikan: Ia menunjukkan perkembangan produk dari semasa ke semasa.Ia membantu untuk menjejaki keutamaan dan membolehkan anda menilai sama ada kadar penambahbaikan selaras dengan objektif syarikat.
Kita juga tidak harus melupakan utiliti dalaman: untuk pembangun, produk, QA atau sokongan, pendaftaran yang tersusun dengan baik membolehkan untuk menyegarkan ingatan tentang apa yang berlaku dalam pecutan atau dalam pelepasan tanpa perlu menjejaki berpuluh-puluh cabang dan penggabungan dalam Git. Dan untuk sokongan, ia berfungsi sebagai skrip untuk memberi respons kepada pelanggan tentang perkara baharu atau isu yang baru-baru ini dibetulkan.
Ia juga mempunyai komponen motivasi yang ketara: melihat sejarah perubahan yang terancang membantu menggambarkan kerja kolektif yang dilakukan dari semasa ke semasaSesuatu yang sering hilang di antara tiket dan komitmen, dan melihatnya terpantul mengukuhkan lagi kebanggaan pasukan.
Log perubahan peribadi: log dalaman yang menyimpan segala-galanya
Kebanyakan produk memerlukan, sekurang-kurangnya, satu log perubahan peribadi, teknikal dan agak terperinciIni adalah dokumen yang berfungsi sebagai asas untuk audit, diagnostik dan penyelarasan antara pasukan. Walaupun anda mungkin kemudiannya menerbitkan versi ringkas untuk pelanggan, ini adalah dokumen "asal" yang menjadi asas segala-galanya.
Dalam banyak sistem, rekod ini berbentuk jadual atau dokumen berstruktur di mana medan seperti berikut dikumpulkan untuk setiap keluaran atau versi pengeluaran: Modul atau komponen yang terjejas, jenis perubahan yang dibuat, versi sebelumnya dan baharu, nota khas, petunjuk teknikal dan pautan ke ujian (contohnya, untuk kes ujian, bukti atau saluran paip CI).
Apabila perubahan melibatkan impak pada pangkalan data, ia amat berguna untuk didokumentasikan. butiran operasi yang dilakukan dan rujukan kepada skrip khusus Dikeluarkan untuk penerbitan. Dengan cara ini, jika beberapa bulan kemudian mereka perlu menyemak semula apa yang telah dilakukan, pasukan tidak perlu membina semula cerita dengan tangan.
Log perubahan peribadi ini boleh direkodkan setiap penggunaan (setiap "pengeluaran secara langsung") atau setiap versi aplikasi. Dalam produk yang sangat boleh disesuaikan, ia juga boleh disusun atur mengikut kes penggunaan atau oleh pelanggan, menunjukkan bagaimana setiap senario telah berkembang dari semasa ke semasa.
Amalan terbaik untuk log perubahan peribadi
Untuk mengelakkan rekod dalaman daripada menjadi dokumen mati, adalah penting untuk dihoskan di lokasi yang mudah diakses, selamat dan mudah untuk diedit oleh pasukan.Ia boleh jadi ruang dalam wiki korporat, dokumen kongsi yang berstruktur dengan baik atau disimpan terus dalam repositori (contohnya, sebagai LOG PERUBAHAN dalaman).
Adalah juga dinasihatkan bahawa sistem yang dipilih membenarkan Mengekalkan keperluan keselamatan dan kawalan akses yang diperlukan dalam projek, terutamanya jika butiran teknikal sensitif atau data infrastruktur disertakan.
Kuncinya adalah untuk menjadikan proses kemas kini cukup tangkas supaya pasukan tidak menganggapnya sebagai beban tambahan yang tidak mampan, memandangkan Log perubahan yang ketinggalan zaman hampir lebih teruk daripada tidak mempunyai apa-apa.Ia memberikan maklumat keselamatan palsu dan memaksa anda untuk mengesahkan semuanya melalui cara lain.
Log perubahan awam: cara menyampaikan mesej yang sama tanpa terlalu membebankan
Berdasarkan rekod dalaman yang terperinci itu, seseorang boleh membina log perubahan awam, lebih mesra pengguna dan ditujukan kepada pengguna akhirTeknikal bagaimana tidak sepenting di sini seperti apa dan mengapa: masalah apa yang diselesaikan, apa yang menambah baik pengalaman, apa yang boleh mereka lakukan sekarang yang tidak dapat mereka lakukan sebelum ini.
Walaupun kandungan asasnya sama seperti dalam versi dalaman, mesejnya berubah secara radikal: butiran pelaksanaan dialih keluar dan perubahan diterjemahkan kepada bahasa perniagaan, kes penggunaan dan faedah konkritAdalah perkara biasa untuk mengumpulkannya ke dalam bahagian seperti "Ciri baharu" dan "Pembetulan dan penambahbaikan".
Anda juga boleh melangkah lebih jauh dengan menggabungkan blok kecil dengan ciri-ciri yang akan datang atau sedang dibangunkanIni membolehkan pengguna mengetahui apa yang akan berlaku dalam jangka pendek atau sederhana. Ia membantu mengurus jangkaan dan menunjukkan bahawa terdapat pelan tindakan yang dinamik.
Ia juga merupakan tempat yang baik untuk menambah mesej terima kasih, notis atau permohonan maaf Apabila terdapat insiden yang berkaitan, kami telah menggunakan log perubahan sebagai saluran komunikasi yang jujur ​​dengan pangkalan pengguna.
Sesetengah produk disertakan dengan entri log perubahan awam tangkapan skrin atau GIF animasi Mereka mempamerkan ciri baharu dalam tindakan, seperti alat yang biasa digunakan dalam ekosistem pembangunan. Secara visual, ini sangat membantu pengguna memahami perubahan tanpa perlu membaca perenggan yang panjang.
Petua untuk mendraf rekod awam
Peraturan emas di sini ialah Tulislah dengan memikirkan orang yang akan menggunakan alat itu, bukan orang yang membuatnya.Ini bermakna mengelakkan jargon teknikal yang tidak perlu, menjelaskan impaknya ("kini anda boleh melakukan X dengan lebih pantas") dan mengutamakan apa yang benar-benar mempengaruhi kehidupan seharian pengguna.
Adalah dinasihatkan untuk mengekalkan struktur yang boleh dikenali dari satu versi ke versi yang lain, supaya pembaca dapat dengan cepat mencari apa yang relevan. bahagian yang paling menarik minat anda (Contohnya, ciri baharu dahulu, kemudian penambahbaikan, dan akhirnya pembetulan pepijat). Ketekalan memudahkan untuk membangunkan tabiat membaca untuk log perubahan.
Akhir sekali, adalah penting bahawa entri tersebut cukup jelas supaya sokongan dapat... Salin dan sesuaikan teks changelog dengan mudah Apabila membalas tiket atau menyediakan komunikasi, jika teks tersebut membantu dalam menjelaskan perubahan kepada pelanggan, anda berada di landasan yang betul.
Log perubahan, Git dan automasi difahami dengan betul
Jika anda menggunakan Git sebagai sistem kawalan versi anda (amalan paling biasa hari ini), anda mempunyai lombong emas maklumat yang boleh anda manfaatkan untuk menjana log perubahan dengan cara yang lebih sistematik dan kurang terdedah kepada dilupakanWalau bagaimanapun, ia mesti dilakukan dengan bijaksana.
Langkah pertama adalah untuk mengekalkan disiplin dengan komitmen: mesej yang deskriptif dan konsisten, dan jika boleh, berdasarkan piawaian seperti Komitmen Konvensional. Ini membolehkan perubahan dikelaskan secara automatik kepada jenis (feat, fix, docs, refactor…), yang kemudiannya diterjemahkan kepada bahagian-bahagian dalam log perubahan.
Berdasarkan itu, alat-alat seperti conventional-changelog, git-changelog atau penjana yang dibina dalam platform seperti GitHub atau GitLab untuk mengekstrak perubahan antara teg atau keluaran dan membuangnya ke dalam fail CHANGELOG yang disusun mengikut versi.
Aliran kerja biasa ialah: memulakan repositori, mengusahakan cawangan dengan komitmen yang ditulis dengan baik, melabelkan versi, dan kemudian Jana log perubahan secara automatik atau separa automatik daripada sejarahcontohnya, dengan mengintegrasikannya ke dalam Saluran paip CI/CD dengan Tindakan GitHubKemudian ia disemak, bahasanya digilap, dan versi awam diterbitkan jika sesuai.
Automasi ini tidak menggantikan pertimbangan manusia, tetapi ia membantu untuk mengelakkan perubahan daripada tidak didokumenkan Mengemas kini log perubahan memerlukan usaha yang lebih sedikit. Walau bagaimanapun, jika piawaian diabaikan dalam mesej komit, kegunaan sistem akan merosot.
Langkah-langkah utama untuk membina log perubahan yang kukuh
Selain alatan khusus, adalah berguna untuk menganggap reka bentuk changelog sebagai proses kecil berbilang peringkat yang diulang versi demi versi dan membolehkan untuk mengekalkan kualiti dan kegunaan rekod.
Peringkat pertama terdiri daripada Kenal pasti semua kemas kini yang berkaitan sejak versi terakhir.Ia bukan tentang menyusun setiap perubahan mikro dalaman, tetapi tentang mengumpulkan ciri, pembetulan dan penambahbaikan yang mempunyai impak ketara pada produk.
Kemudian anda perlu atur perubahan tersebut mengikut versi dan, dalam setiap versi, mengikut kategoriAdalah amalan biasa untuk mengumpulkannya ke dalam blok seperti "Ditambah / Baharu", "Diperbaiki / Diubah", "Diperbaiki", "Ditamatkan" atau yang serupa, supaya sangat mudah untuk mencari jenis perubahan yang telah berlaku.
Seterusnya ialah bahagian penulisan: menerangkan setiap perubahan dengan bahasa yang jelas dan tepat. Sebaik-baiknya, Terangkan apa yang telah dilakukan dan mengapa ia relevanmengelakkan frasa kosong seperti "beberapa penambahbaikan kecil" yang tidak memberi manfaat kepada sesiapa pun.
Sebaik sahaja versi, kategori dan penerangan telah ditakrifkan, adalah dinasihatkan untuk menerima pakai format yang standard dan konsisten Berkenaan tajuk, susunan, gaya ayat, penggunaan pautan, dan sebagainya, ini memudahkan pembacaan dan penyepaduan dengan alatan luaran (penjana, skrip penerbitan).
Akhir sekali, setiap keluaran baharu hendaklah disertakan dengan mengemas kini log perubahan dan menyampaikannya kepada pasukan yang berkaitan, sama ada melalui platform kod itu sendiri (keluaran di GitHub/GitLab), laman web produk, pusat bantuan atau kempen e-mel dan media sosial.
Cara mengurus dan menyelenggara log perubahan dari semasa ke semasa
Kesukaran sebenar bukanlah membuka fail CHANGELOG, tetapi untuk memastikan ia kekal hidup dan boleh dipercayai sepanjang hayat projekUntuk itu, ia perlu dianggap sebagai sebahagian daripada aliran kerja dan bukan sebagai sesuatu yang diisi dengan tergesa-gesa pada akhirnya "jika ada masa".
Sebagai permulaan, ia banyak membantu untuk ditakrifkan dari awal. struktur yang jelas, serasi dengan alatan luaran dan mudah diikutiSatu skema klasik adalah untuk menyenaraikan versi dalam susunan terbalik (terkini dahulu) dan, dalam setiap satu, bahagian dengan senarai pendek perubahan.
Ia juga penting bahawa format yang dipilih boleh dibaca oleh manusia dan mudah diedit: Markdown dan HTML biasa biasanya merupakan pilihan yang baik kerana Ia berintegrasi dengan baik dengan repositori dan sistem pengurusan dokumen dan ia mudah diproses oleh skrip.
Berkenaan kandungan, adalah lebih baik untuk memberi tumpuan kepada perubahan ketara (ciri baharu, pembetulan pepijat utama, keputusan seni bina, perubahan tingkah laku) dan elakkan terlalu memperincikan perkara remeh. Log perubahan yang dipenuhi dengan hingar menjadikannya... Maklumat yang berkaitan hilang di antara berpuluh-puluh nota remeh.
Satu lagi kunci adalah untuk tidak meletakkan semua tanggungjawab kepada seorang sahaja: idealnya, Seluruh pasukan berasa sebahagian daripada usaha mengekalkan rekodSetiap orang boleh menyumbang draf daripada tiket atau kisah pengguna mereka, yang kemudiannya disemak dan disatukan oleh seseorang yang mempunyai visi global.
Akhir sekali, adalah sangat praktikal untuk menghubungkan log perubahan dengan alat pengurusan kerja itu sendiri (isu, tugas, insiden). Dalam banyak persekitaran, tag dan rujukan silang digunakan untuk tujuan ini. Pautkan setiap entri changelog kepada isu atau permintaan tarik yang sepadan., memudahkan pengesanan sekiranya siasatan lanjut diperlukan.
Alat dan sumber untuk memprofesionalkan log perubahan anda
Sebaik sahaja asas diletakkan, sudah tiba masanya untuk bergantung pada alat yang memudahkan tugas dan membolehkan mengautomasikan bahagian proses tanpa kehilangan kawalan pada keputusan akhir.
Di satu pihak, terdapat utiliti yang menjana nota pelepasan daripada tag dan mesej komit, seperti Penjana nota keluaran Git atau skrip berdasarkan konvensyen mesej. Ia biasanya membenarkan anda menyesuaikan format output agar sesuai dengan templat anda.
Platform pengehosan kod itu sendiri menawarkan ciri-ciri berguna: contohnya, Mekanisme pelepasan GitHub atau GitLab Ia membolehkan anda mencipta versi yang ditag dan menulis log perubahan yang berkaitan di sana, yang kemudiannya boleh disegerakkan dengan dokumentasi awam.
Terdapat juga panduan dan templat yang diseragamkan, seperti inisiatif "Simpan Log Perubahan" yang terkenal, yang mencadangkan struktur standard bahagian dan konvensyen penamaanMengguna pakai sesuatu seperti ini membantu sesiapa sahaja yang biasa dengan piawaian tersebut untuk menavigasi pendaftaran anda.
Akhir sekali, terdapat penjana dalam talian yang mampu membandingkan tag dalam repositori dan menghasilkan draf log perubahan antara mereka. Alatan seperti ini amat berguna dalam projek kerjasama dengan ramai penyumbangdi mana menyusun semua perubahan secara manual adalah tidak praktikal.
Apa jua susunan yang dipilih, yang penting ialah Alatan ini menyesuaikan diri dengan aliran kerja pasukan anda dan bukan sebaliknya. Sistem yang sangat berkuasa, tetapi dianggap asing atau kompleks, akhirnya akan digunakan sedikit atau kurang digunakan.
Akhirnya, mencipta dan menyelenggara log perubahan yang baik bukan sekadar menyenaraikan perubahan, tetapi juga membina naratif yang jelas dan jujur ​​tentang evolusi produkyang membantu pasukan bekerja dengan lebih baik, mengurangkan risiko dalam setiap penggunaan dan menyampaikan kepada pelanggan dan pihak berkepentingan bahawa perisian tersebut masih hidup, dijaga dan bergerak ke arah yang difahami.
