SuaraSekitar Terkini Kumpulan Berita dan Informasi dari berbagai sumber yang terpercaya
Daftar Isi
Apa itu changelog?
Changelog adalah file yang berisi daftar perubahan penting yang disusun secara kronologis untuk setiap versi proyek.
Mengapa menyimpan changelog?
Untuk memudahkan pengguna dan kontributor melihat dengan tepat perubahan penting apa yang telah dibuat antara setiap rilis (atau versi) proyek.
Siapa yang butuh changelog?
Orang-orang melakukannya. Baik konsumen atau pengembang, pengguna akhir perangkat lunak adalah manusia yang peduli dengan apa yang ada di dalam perangkat lunak. Ketika perangkat lunak berubah, orang ingin tahu mengapa dan bagaimana.
Bagaimana cara membuat changelog yang baik?
Prinsip-Prinsip Panduan
Jenis perubahan
Ditambahkan
untuk fitur baru.
Diubah untuk perubahan fungsi yang ada. Tidak digunakan lagi untuk fitur yang akan segera dihapus. Dihapus untuk fitur yang sekarang dihapus. Memperbaiki untuk perbaikan bug apa pun. Keamanan dalam kasus kerentanan.
Bagaimana saya bisa mengurangi upaya yang diperlukan untuk mempertahankan changelog?
Pertahankan Belum dirilis
di bagian atas untuk melacak perubahan yang akan datang.
Ini melayani dua tujuan:
Orang dapat melihat perubahan apa yang mungkin mereka harapkan dalam rilis mendatang
Pada waktu rilis, Anda dapat memindahkan Belum dirilis
bagian berubah menjadi bagian versi rilis baru.
Bisakah changelog menjadi buruk?
Iya. Berikut adalah beberapa cara mereka bisa kurang berguna.
Komit log diffs
Menggunakan diff log komit sebagai changelog adalah ide yang buruk: mereka penuh dengan noise. Hal-hal seperti penggabungan komit, komit dengan judul yang tidak jelas, perubahan dokumentasi, dll.
Tujuan komit adalah untuk mendokumentasikan langkah dalam evolusi kode sumber. Beberapa proyek membersihkan komit, beberapa tidak.
Tujuan dari entri changelog adalah untuk mendokumentasikan perbedaan penting, sering kali di beberapa commit, untuk mengkomunikasikannya dengan jelas kepada pengguna akhir.
Mengabaikan Penghentian
Ketika orang meningkatkan dari satu versi ke versi lain, harus sangat jelas ketika sesuatu akan rusak. Seharusnya dimungkinkan untuk memutakhirkan ke versi yang mencantumkan penghentian, menghapus apa yang tidak digunakan lagi, lalu memutakhirkan ke versi di mana penghentian menjadi penghapusan.
Jika Anda tidak melakukan apa-apa lagi, daftarkan penghentian, penghapusan, dan perubahan apa pun yang mengganggu di log perubahan Anda.
Tanggal Membingungkan
Format tanggal regional bervariasi di seluruh dunia dan seringkali sulit untuk menemukan format tanggal yang sesuai untuk manusia yang terasa intuitif untuk semua orang. Keuntungan dari tanggal yang diformat seperti 17-07-17 adalah bahwa mereka mengikuti urutan unit terbesar ke terkecil: tahun, bulan, dan hari. Format ini juga tidak tumpang tindih secara ambigu dengan format tanggal lainnya, tidak seperti beberapa format regional yang mengganti posisi nomor bulan dan hari. Alasan-alasan ini, dan fakta bahwa format tanggal ini adalah standar ISO, adalah mengapa format tanggal ini direkomendasikan untuk entri changelog.
Pertanyaan yang Sering Diajukan
Apakah ada format changelog standar?
Tidak juga. Ada panduan gaya changelog GNU, atau “panduan” file GNU NEWS sepanjang dua paragraf. Keduanya tidak memadai atau tidak mencukupi.
Proyek ini bertujuan untuk menjadi konvensi changelog yang lebih baik. Itu datang dari mengamati praktik yang baik di komunitas open source dan mengumpulkannya.
Kritik, diskusi, dan saran perbaikan yang sehat dipersilahkan.
Apa nama file changelog?
Sebut saja CHANGELOG. md. Beberapa proyek menggunakan SEJARAH , BERITA atau RILIS.
Meskipun mudah untuk berpikir bahwa nama file changelog Anda tidak terlalu penting, mengapa mempersulit pengguna akhir Anda untuk secara konsisten menemukan perubahan penting?
Bagaimana dengan Rilis GitHub?
Ini inisiatif yang bagus. Rilis dapat digunakan untuk mengubah tag git sederhana (misalnya tag bernama v1.0.0
) menjadi catatan rilis yang kaya dengan menambahkan catatan rilis secara manual atau dapat menarik pesan tag git beranotasi dan mengubahnya menjadi catatan.
Rilis GitHub membuat changelog non-portabel yang hanya dapat ditampilkan kepada pengguna dalam konteks GitHub. Dimungkinkan untuk membuatnya terlihat sangat mirip dengan format Keep a Changelog, tetapi cenderung sedikit lebih terlibat.
Versi rilis GitHub saat ini juga bisa dibilang tidak terlalu dapat ditemukan oleh pengguna akhir, tidak seperti file huruf besar pada umumnya (BACA AKU, KONTRIBUSI, dll.). Masalah kecil lainnya adalah antarmuka saat ini tidak menawarkan tautan untuk melakukan log di antara setiap rilis.
Bisakah changelog diurai secara otomatis?
Sulit, karena orang mengikuti format dan nama file yang sangat berbeda.
Vandamme adalah permata Ruby yang dibuat oleh tim Gemnasium dan yang mem-parsing banyak (tetapi tidak semua) log perubahan proyek sumber terbuka.
Bagaimana dengan rilis yang ditarik?
Rilis yang ditarik adalah versi yang harus ditarik karena bug yang serius atau masalah keamanan. Seringkali versi ini bahkan tidak muncul di log perubahan. Mereka harus. Ini adalah bagaimana Anda harus menampilkannya:
## 0.0.5 - 2014-12-13
NS tag keras karena suatu alasan. Penting bagi orang untuk memperhatikannya. Karena dikelilingi oleh tanda kurung, ini juga lebih mudah untuk diurai secara terprogram.
Jika Anda pernah menulis ulang a perubahan log?
Tentu. Selalu ada alasan bagus untuk meningkatkan changelog. Saya secara teratur membuka permintaan tarik untuk menambahkan rilis yang hilang ke proyek sumber terbuka dengan log perubahan yang tidak terawat.
Mungkin juga Anda menemukan bahwa Anda lupa untuk mengatasi perubahan yang mengganggu dalam catatan untuk sebuah versi. Jelas penting bagi Anda untuk memperbarui changelog Anda dalam kasus ini.
Bagaimana saya bisa berkontribusi ?
Dokumen ini bukan kebenaran; itu pendapat saya yang dipertimbangkan dengan cermat, bersama dengan informasi dan contoh yang saya kumpulkan.
Ini karena saya ingin komunitas kita mencapai konsensus. Saya percaya diskusi sama pentingnya dengan hasil akhirnya.
Jadi tolong masukkan .
Percakapan
Saya melanjutkan podcast The Changelog untuk berbicara tentang mengapa pengelola dan kontributor harus peduli dengan changelog, dan juga tentang motivasi di balik proyek ini.
Baca selengkapnya
Bagaimana saya bisa mengurangi upaya yang diperlukan untuk mempertahankan changelog?
Pertahankan Belum dirilis
di bagian atas untuk melacak perubahan yang akan datang.
Ini melayani dua tujuan:
Belum dirilis
bagian berubah menjadi bagian versi rilis baru.
Bisakah changelog menjadi buruk?
Iya. Berikut adalah beberapa cara mereka bisa kurang berguna.
Komit log diffs
Menggunakan diff log komit sebagai changelog adalah ide yang buruk: mereka penuh dengan noise. Hal-hal seperti penggabungan komit, komit dengan judul yang tidak jelas, perubahan dokumentasi, dll.
Tujuan komit adalah untuk mendokumentasikan langkah dalam evolusi kode sumber. Beberapa proyek membersihkan komit, beberapa tidak.
Tujuan dari entri changelog adalah untuk mendokumentasikan perbedaan penting, sering kali di beberapa commit, untuk mengkomunikasikannya dengan jelas kepada pengguna akhir.
Mengabaikan Penghentian
Ketika orang meningkatkan dari satu versi ke versi lain, harus sangat jelas ketika sesuatu akan rusak. Seharusnya dimungkinkan untuk memutakhirkan ke versi yang mencantumkan penghentian, menghapus apa yang tidak digunakan lagi, lalu memutakhirkan ke versi di mana penghentian menjadi penghapusan.
Jika Anda tidak melakukan apa-apa lagi, daftarkan penghentian, penghapusan, dan perubahan apa pun yang mengganggu di log perubahan Anda.
Tanggal Membingungkan
Format tanggal regional bervariasi di seluruh dunia dan seringkali sulit untuk menemukan format tanggal yang sesuai untuk manusia yang terasa intuitif untuk semua orang. Keuntungan dari tanggal yang diformat seperti 17-07-17 adalah bahwa mereka mengikuti urutan unit terbesar ke terkecil: tahun, bulan, dan hari. Format ini juga tidak tumpang tindih secara ambigu dengan format tanggal lainnya, tidak seperti beberapa format regional yang mengganti posisi nomor bulan dan hari. Alasan-alasan ini, dan fakta bahwa format tanggal ini adalah standar ISO, adalah mengapa format tanggal ini direkomendasikan untuk entri changelog.
Pertanyaan yang Sering Diajukan
Apakah ada format changelog standar?
Tidak juga. Ada panduan gaya changelog GNU, atau “panduan” file GNU NEWS sepanjang dua paragraf. Keduanya tidak memadai atau tidak mencukupi.
Proyek ini bertujuan untuk menjadi konvensi changelog yang lebih baik. Itu datang dari mengamati praktik yang baik di komunitas open source dan mengumpulkannya.
Kritik, diskusi, dan saran perbaikan yang sehat dipersilahkan.
Apa nama file changelog?
Sebut saja CHANGELOG. md. Beberapa proyek menggunakan SEJARAH , BERITA atau RILIS.
Meskipun mudah untuk berpikir bahwa nama file changelog Anda tidak terlalu penting, mengapa mempersulit pengguna akhir Anda untuk secara konsisten menemukan perubahan penting?
Bagaimana dengan Rilis GitHub?
Ini inisiatif yang bagus. Rilis dapat digunakan untuk mengubah tag git sederhana (misalnya tag bernama v1.0.0
) menjadi catatan rilis yang kaya dengan menambahkan catatan rilis secara manual atau dapat menarik pesan tag git beranotasi dan mengubahnya menjadi catatan.
Rilis GitHub membuat changelog non-portabel yang hanya dapat ditampilkan kepada pengguna dalam konteks GitHub. Dimungkinkan untuk membuatnya terlihat sangat mirip dengan format Keep a Changelog, tetapi cenderung sedikit lebih terlibat.
Versi rilis GitHub saat ini juga bisa dibilang tidak terlalu dapat ditemukan oleh pengguna akhir, tidak seperti file huruf besar pada umumnya (BACA AKU, KONTRIBUSI, dll.). Masalah kecil lainnya adalah antarmuka saat ini tidak menawarkan tautan untuk melakukan log di antara setiap rilis.
Bisakah changelog diurai secara otomatis?
Sulit, karena orang mengikuti format dan nama file yang sangat berbeda.
Vandamme adalah permata Ruby yang dibuat oleh tim Gemnasium dan yang mem-parsing banyak (tetapi tidak semua) log perubahan proyek sumber terbuka.
Bagaimana dengan rilis yang ditarik?
Rilis yang ditarik adalah versi yang harus ditarik karena bug yang serius atau masalah keamanan. Seringkali versi ini bahkan tidak muncul di log perubahan. Mereka harus. Ini adalah bagaimana Anda harus menampilkannya:
## 0.0.5 - 2014-12-13
NS tag keras karena suatu alasan. Penting bagi orang untuk memperhatikannya. Karena dikelilingi oleh tanda kurung, ini juga lebih mudah untuk diurai secara terprogram.
Jika Anda pernah menulis ulang a perubahan log?
Tentu. Selalu ada alasan bagus untuk meningkatkan changelog. Saya secara teratur membuka permintaan tarik untuk menambahkan rilis yang hilang ke proyek sumber terbuka dengan log perubahan yang tidak terawat.
Mungkin juga Anda menemukan bahwa Anda lupa untuk mengatasi perubahan yang mengganggu dalam catatan untuk sebuah versi. Jelas penting bagi Anda untuk memperbarui changelog Anda dalam kasus ini.
Bagaimana saya bisa berkontribusi ?
Dokumen ini bukan kebenaran; itu pendapat saya yang dipertimbangkan dengan cermat, bersama dengan informasi dan contoh yang saya kumpulkan.
Ini karena saya ingin komunitas kita mencapai konsensus. Saya percaya diskusi sama pentingnya dengan hasil akhirnya.
Jadi tolong masukkan .
Percakapan
Saya melanjutkan podcast The Changelog untuk berbicara tentang mengapa pengelola dan kontributor harus peduli dengan changelog, dan juga tentang motivasi di balik proyek ini.
Bisakah changelog menjadi buruk?
Iya. Berikut adalah beberapa cara mereka bisa kurang berguna.
Komit log diffs
Menggunakan diff log komit sebagai changelog adalah ide yang buruk: mereka penuh dengan noise. Hal-hal seperti penggabungan komit, komit dengan judul yang tidak jelas, perubahan dokumentasi, dll.
Tujuan komit adalah untuk mendokumentasikan langkah dalam evolusi kode sumber. Beberapa proyek membersihkan komit, beberapa tidak.
Tujuan dari entri changelog adalah untuk mendokumentasikan perbedaan penting, sering kali di beberapa commit, untuk mengkomunikasikannya dengan jelas kepada pengguna akhir.
Mengabaikan Penghentian
Ketika orang meningkatkan dari satu versi ke versi lain, harus sangat jelas ketika sesuatu akan rusak. Seharusnya dimungkinkan untuk memutakhirkan ke versi yang mencantumkan penghentian, menghapus apa yang tidak digunakan lagi, lalu memutakhirkan ke versi di mana penghentian menjadi penghapusan.
Jika Anda tidak melakukan apa-apa lagi, daftarkan penghentian, penghapusan, dan perubahan apa pun yang mengganggu di log perubahan Anda.
Tanggal Membingungkan
Format tanggal regional bervariasi di seluruh dunia dan seringkali sulit untuk menemukan format tanggal yang sesuai untuk manusia yang terasa intuitif untuk semua orang. Keuntungan dari tanggal yang diformat seperti 17-07-17 adalah bahwa mereka mengikuti urutan unit terbesar ke terkecil: tahun, bulan, dan hari. Format ini juga tidak tumpang tindih secara ambigu dengan format tanggal lainnya, tidak seperti beberapa format regional yang mengganti posisi nomor bulan dan hari. Alasan-alasan ini, dan fakta bahwa format tanggal ini adalah standar ISO, adalah mengapa format tanggal ini direkomendasikan untuk entri changelog.
Pertanyaan yang Sering Diajukan
Apakah ada format changelog standar?
Tidak juga. Ada panduan gaya changelog GNU, atau “panduan” file GNU NEWS sepanjang dua paragraf. Keduanya tidak memadai atau tidak mencukupi.
Proyek ini bertujuan untuk menjadi konvensi changelog yang lebih baik. Itu datang dari mengamati praktik yang baik di komunitas open source dan mengumpulkannya.
Kritik, diskusi, dan saran perbaikan yang sehat dipersilahkan.
Apa nama file changelog?
Sebut saja CHANGELOG. md. Beberapa proyek menggunakan SEJARAH , BERITA atau RILIS.
Meskipun mudah untuk berpikir bahwa nama file changelog Anda tidak terlalu penting, mengapa mempersulit pengguna akhir Anda untuk secara konsisten menemukan perubahan penting?
Bagaimana dengan Rilis GitHub?
Ini inisiatif yang bagus. Rilis dapat digunakan untuk mengubah tag git sederhana (misalnya tag bernama v1.0.0
) menjadi catatan rilis yang kaya dengan menambahkan catatan rilis secara manual atau dapat menarik pesan tag git beranotasi dan mengubahnya menjadi catatan.
Rilis GitHub membuat changelog non-portabel yang hanya dapat ditampilkan kepada pengguna dalam konteks GitHub. Dimungkinkan untuk membuatnya terlihat sangat mirip dengan format Keep a Changelog, tetapi cenderung sedikit lebih terlibat.
Versi rilis GitHub saat ini juga bisa dibilang tidak terlalu dapat ditemukan oleh pengguna akhir, tidak seperti file huruf besar pada umumnya (BACA AKU, KONTRIBUSI, dll.). Masalah kecil lainnya adalah antarmuka saat ini tidak menawarkan tautan untuk melakukan log di antara setiap rilis.
Bisakah changelog diurai secara otomatis?
Sulit, karena orang mengikuti format dan nama file yang sangat berbeda.
Vandamme adalah permata Ruby yang dibuat oleh tim Gemnasium dan yang mem-parsing banyak (tetapi tidak semua) log perubahan proyek sumber terbuka.
Bagaimana dengan rilis yang ditarik?
Rilis yang ditarik adalah versi yang harus ditarik karena bug yang serius atau masalah keamanan. Seringkali versi ini bahkan tidak muncul di log perubahan. Mereka harus. Ini adalah bagaimana Anda harus menampilkannya:
## 0.0.5 - 2014-12-13
NS tag keras karena suatu alasan. Penting bagi orang untuk memperhatikannya. Karena dikelilingi oleh tanda kurung, ini juga lebih mudah untuk diurai secara terprogram.
Jika Anda pernah menulis ulang a perubahan log?
Tentu. Selalu ada alasan bagus untuk meningkatkan changelog. Saya secara teratur membuka permintaan tarik untuk menambahkan rilis yang hilang ke proyek sumber terbuka dengan log perubahan yang tidak terawat.
Mungkin juga Anda menemukan bahwa Anda lupa untuk mengatasi perubahan yang mengganggu dalam catatan untuk sebuah versi. Jelas penting bagi Anda untuk memperbarui changelog Anda dalam kasus ini.
Bagaimana saya bisa berkontribusi ?
Dokumen ini bukan kebenaran; itu pendapat saya yang dipertimbangkan dengan cermat, bersama dengan informasi dan contoh yang saya kumpulkan.
Ini karena saya ingin komunitas kita mencapai konsensus. Saya percaya diskusi sama pentingnya dengan hasil akhirnya.
Jadi tolong masukkan .
Percakapan
Saya melanjutkan podcast The Changelog untuk berbicara tentang mengapa pengelola dan kontributor harus peduli dengan changelog, dan juga tentang motivasi di balik proyek ini.