Haruskah riwayat komit digunakan untuk menyampaikan informasi penting kepada pengembang?

Selama pertemuan mengenai kemunduran SDK pihak ketiga dari versi terbaru, dicatat bahwa pengembang kami telah menandai dalam komit sejarah bahwa versi terbaru tidak boleh digunakan.

Beberapa pengembang berpendapat bahwa ini adalah praktik yang buruk dan seharusnya dicatat dalam file sumber (yaitu // Don't upgrade SDK Version x.y.z, see ticket 1234) atau dalam READMEfile tingkat proyek . Yang lain berpendapat bahwa karena sejarah komit adalah bagian dari dokumentasi proyek, maka itu adalah lokasi yang dapat diterima untuk informasi tersebut karena kita semua harus membacanya.

Haruskah riwayat komit digunakan untuk menyampaikan informasi penting kepada pengembang lain atau haruskah informasi tersebut diduplikasi ke lokasi lain seperti proyek READMEatau komentar dalam file sumber yang relevan?

Jika saya akan melihat peningkatan ke versi yang lebih baru dari SDK pihak ketiga, tempat terakhir yang saya lihat adalah dalam sejarah sistem kontrol sumber.

Jika produk Anda menggunakan SDK versi 2.0 dan seseorang tertarik untuk memutakhirkan ke 3.0, saya rasa tidak masuk akal untuk berpikir bahwa mereka harus melihat ke belakang dalam waktu dalam sistem kontrol sumber Anda untuk mengetahui bahwa itu bukan ide yang baik.

Di sini, kami memiliki tim wiki yang memiliki beberapa halaman dengan info menarik yang dibaca setiap pengembang (konvensi pengkodean, cara mengatur lingkungan pengembangan untuk membangun produk, hal-hal pihak ketiga apa yang perlu Anda instal, dll). Ini adalah jenis tempat yang sesuai untuk peringatan terhadap pemutakhiran perpustakaan pihak ketiga.

Itu harus dicatat dalam histori komit tetapi tempat terbaik mutlak untuk menempatkan pemberitahuan adalah di tempat yang sama Anda mendefinisikan ketergantungan. Jika Anda memiliki misalnya file .pom maven yang menyatakan dependensi artefak Anda, saya akan melakukan sesuatu seperti:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Tepat di atas <dependency>garis Anda .

Masalah # 123 akan mencakup rincian tentang bagaimana crash, versi yang Anda perbarui yang menyebabkan crash, dan mungkin kemudian harus ditambahkan ke backlog Anda lagi untuk meninjau kembali nanti - mungkin ada versi yang lebih baru lagi yang memperbaiki masalah. Baik secara otomatis dengan mengedit tiket, atau secara manual sendiri, itu akan mengirim email kepada tim untuk memberi tahu mereka tentang masalah saat ini sekarang, dan dengan berada di pelacak itu memungkinkan orang menemukannya lagi nanti.

Alasan untuk memasukkannya dengan deklarasi dependensi adalah karena siapa pun yang ingin mengubah versi akan melihatnya pada saat mereka ingin mengubahnya dan memahami mengapa mereka tidak boleh.

Saya tidak akan berkomentar dalam kode sumber karena saya dapat dengan mudah menggambarkan situasi di mana seseorang menjalankan pemeriksaan pada dependensi Anda dan mulai memutakhirkannya. Mereka seharusnya tidak perlu menjelajahi basis kode untuk setiap komentar TODO untuk melakukan itu.

Menautkan ke tiket masalah memungkinkan pengembang yang penasaran tahu bagaimana kegagalannya dan berpotensi mengunjungi kembali nanti. Tanpa itu, mungkin menjadi cukup statis dan tidak pernah diperbarui lagi.

Potongan informasi yang kritis dan tidak intuitif harus didokumentasikan di mana orang akan mencari ketika mempertimbangkan informasi tersebut.

Untuk tim dan proyek yang saya kerjakan, saya akan melakukan roll-back dengan komentar tentang mengapa versi baru gagal. Saya akan menambahkan cerita backlog untuk mencoba kembali upgrade jika versi baru diperbaiki. Saya akan menambahkan komentar ke sistem build / membangun skrip di mana perpustakaan terhubung.

Roll-back akan memberikan konteks masa depan pengembang ketika melihat ke dalam sejarah proyek. Kisah backlog menjaga perlunya peningkatan ini sebagai bagian aktif dari proyek. Komentar membangun sistem tepat di mana perubahan harus ketika perpustakaan akhirnya diperbarui.

Saya tidak akan berkomentar dalam kode dan saya tidak akan menambahkannya ke README. Pengembang yang berpikir untuk mencoba peningkatan tidak akan melihat potongan-potongan ini. Jika Anda menambahkannya di sana, maka ketika masalah dengan perpustakaan akhirnya diperbaiki dan pemutakhiran selesai, Anda harus menghapusnya. Langkah ini sering dilupakan: menghasilkan catatan yang kontra produktif dengan proyek.

Jika proyek Anda memiliki pengaturan yang berbeda atau alur yang berbeda, maka jawaban Anda mungkin berbeda. Saya pikir kuncinya adalah untuk meluruskan informasi bahwa pengembang akan melihatnya ketika melakukan pekerjaan untuk upgrade. Dengan begitu, jika waktunya tidak tepat untuk peningkatan, pengembang akan melihatnya dan berhenti, dan ketika waktunya tepat pengembang akan melihatnya dan menghapus catatan sehingga tidak akan membingungkan pengembang di masa depan.

Saya ingin memberi komentar Matthew lebih banyak perhatian dengan menyoroti ide pentingnya dalam sebuah jawaban. Ada alasan mengapa Anda tidak ingin memutakhirkan SDK Anda, dan alasan itu harus ditangkap dalam unit test. Bukan cek untuk nomor revisi, tetapi alasan mendasar yang sebenarnya.

Misalnya, ada bug di versi baru. Tulis unit test yang memeriksa bug itu. Jika nanti mereka memperbaiki bug itu di SDK, maka pemutakhiran akan terjadi dengan lancar. Jika ada perubahan API yang tidak kompatibel, tulis tes yang memeriksa apakah kode Anda mendukung API baru atau SDK mendukung API lama. Itu lebih dari tes integrasi daripada tes unit, tetapi harus tetap bisa dilakukan.

Perusahaan saya menghasilkan 50+ komitmen per hari, dan kami tidak terlalu besar. Bahkan jika setiap pengembang membaca setiap pesan komit, yang sejujurnya tidak, seluruh alasan kita memerlukan riwayat komit yang direkam adalah karena orang tidak dapat mengingatnya. Dan orang tidak kembali dan membaca sejarah nanti kecuali ada masalah. Dan mereka tidak memiliki alasan untuk mencurigai masalah pada peningkatan yang sejauh yang mereka tahu belum terjadi.

Dengan segala cara, kirim email untuk mencegah duplikasi pekerjaan dalam waktu dekat, dan catat di skrip build Anda dan README atau errata. Namun, terutama jika masalah dengan versi baru itu halus dan memakan waktu untuk memecahkan masalah, Anda perlu cara untuk membuatnya jelas. Itu berarti unit test.

Saya menyusun ulang pertanyaan sebagai "Haruskah saya mengomunikasikan informasi penting yang saya temukan kepada anggota tim lainnya hanya melalui pesan komit?" Karena saya pikir itu membuat jelas bahwa tidak, Anda tidak boleh. Saya berusaha keras untuk banyak berkomunikasi (ini adalah sesuatu yang oleh sebagian besar tim pengembangan, dalam pengalaman saya, perlu melakukan upaya aktif) dan saya tentu melakukan segala yang saya bisa untuk menghindari membuat jebakan atau membiarkan mereka berbohong.

Jika rantai tindakan yang membawa saya ke penemuan seperti itu dipicu oleh tiket, saya akan memperbarui tiket (dan memastikan orang-orang yang seharusnya tahu ini memiliki visibilitas), saya mungkin akan menyebutkannya secara langsung (berharap untuk setidaknya meninggalkan seseorang dengan perasaan mengomel bahwa "Wah, saya pikir Damon mengatakan sesuatu tentang memperbarui itu"), dan tentu saja saya akan meninggalkan komentar dalam kode pada titik SDK dimasukkan sehingga tidak ada yang bisa memperbarui tanpa memiliki kesempatan untuk melihatnya. Saya mungkin melihat apakah saya bisa memasukkannya ke wiki dev kami juga, meskipun itu dilakukan lebih dengan pandangan ke arah perekrutan masa depan, bukan tim saat ini.

Hanya perlu beberapa menit lebih lama dibandingkan dengan waktu yang dibutuhkan untuk menemukan dan menemukan masalahnya. Saya tentu saja tidak akan memutuskan bahwa salah satu dari potongan-potongan dokumentasi kami yang paling sedikit digunakan, dan membiarkannya.

Itu harus dalam sejarah komit tetapi seharusnya tidak hanya dalam sejarah komit, bayangkan sejenak Anda menyewa pengembang baru. Apakah Anda berharap pengembang baru membaca setiap pesan komit selama 10 tahun terakhir dari proyek Anda karena beberapa di antaranya akan sangat penting untuk memahami basis kode Anda?

Kedua, katakan situasinya tetapi bukan perubahan kode, apakah Anda akan membuat komitmen "dokumentasi" sehingga Anda dapat menambahkan pesan komit di sepanjang baris "komit pesan dari revisi 5432 sekarang salah, inilah situasi saat ini."

Saya tidak yakin bagaimana tim Anda berkomunikasi tapi saya percaya cara yang paling efektif untuk mengatakan ini adalah untuk pertama mengirim dan email ke grup email tim, ditandai sebagai "URGENT" dengan tubuh mengatakan

Kawan, kita tidak bisa menggunakan SDK v xyz karena hal itu menyebabkan buffer Foo meluap dan layanan Bar akan macet. Tetap dengan versi xyy

Itulah yang kami lakukan di sini dan ini adalah cara paling andal untuk menyampaikan pesan di sana. Jika Anda benar - benar ingin cerewet (dan jika sistem email Anda memungkinkannya), mintalah "tanda terima baca" pada email tersebut.

Setelah Anda memberi tahu seluruh tim, dokumentasi yang lebih detail harus dimasukkan ke dalam wiki tim. Ini akan bervariasi, tergantung pada bagaimana Anda menyusun dokumentasi Anda. Jika Anda memiliki bagian khusus untuk Ketergantungan dan Persyaratan aplikasi Anda, itu akan menjadi tempat yang baik untuk menambahkannya.

Tempat tambahan untuk mendokumentasikan masalah semacam ini mungkin ada dalam kode sumber itu sendiri, meskipun itu mungkin tidak selalu berhasil. Jika SDK version ...hanya direferensikan di satu atau dua tempat yang jelas, Anda dapat menyertakan catatan tentang tidak meningkatkan.

Riwayat file dalam kontrol sumber bisa sangat panjang, dan tergantung pada pengembang, bisa memiliki beberapa entri per hari. Seseorang yang sedang berlibur selama seminggu mungkin tidak punya waktu untuk membaca sejarah komitmen selama seminggu. File README adalah tempat yang lebih baik karena sedikit lebih sentral dan orang mungkin lebih cenderung untuk membacanya, tetapi Anda tidak dapat memastikan bahwa semua orang benar-benar akan membaca README. Yah, saya kira mereka mungkin jika mereka melihat itu telah berubah ...

Sesuatu seperti ini seharusnya dimasukkan dalam komentar komit, tetapi itu akan mendapat manfaat dari berada di tempat lain juga.

Siapa pun yang membuat keputusan untuk meningkatkan, perlu memiliki fakta. Orang itu mungkin tidak hidup dalam kendali sumber. Bagaimana jika seseorang akan membaca tentang masalah ini pada SO dan tidak pernah memasukkannya ke dalam basis kode?

Perlu ada semacam dokumen tentang SDK pihak ketiga ini.

• Masalah apa yang dipecahkannya?
• Mengapa yang satu ini dipilih?
• Pertimbangan apa yang perlu dibuat sejauh: versi, peningkatan, pengujian, dll.
• Siapa yang membuat keputusan ini?

Anda memiliki kasus di mana sesuatu seperti ini masuk ke kontrol versi, dan Anda harus merekomendasikan semua orang menggunakan informasi ini sebanyak mungkin. Hanya tim Anda yang dapat memutuskan di mana seseorang akan melakukan pencarian dalam dokumentasi, kontrol sumber, atau pelacak bug apa pun untuk mendapatkan informasi sebanyak mungkin mengenai subjek tersebut. Kalau tidak, Anda akan lupa, bagaimanapun juga, seseorang akan melakukannya, dan Anda akan beruntung jika itu menghafal ingatan seseorang dan dengan cepat mengembalikannya.

Sejarah adalah tempat yang tepat untuk menaruh data yang ditujukan bagi pembaca yang secara sadar mencarinya, dan memiliki pengertian umum tentang di mana seharusnya. Ini adalah tempat yang sangat buruk untuk menaruh data yang harus disodorkan kepada pengguna, daripada dicari.

Sejarah adalah badan yang sangat besar dari teks yang relatif tidak disortir. Mereka biasanya dimaksudkan untuk menyediakan pengembang dengan informasi terperinci tentang apa yang diubah, dan mengapa itu diubah. Ini bisa menjadi informasi yang berlebihan kecuali ada yang tahu apa yang mereka cari.

Jika pengguna tidak tahu apa yang mereka cari, maka informasi tersebut dengan cepat dikubur di bawah ratusan log komit, dan mereka tidak memiliki alat untuk memangkas tumpukan informasi di depan mereka.

Saya menafsirkan situasi ini sebagai memiliki dua masalah dasar, mungkin tiga.

• Pemutakhiran SDK yang tidak diinginkan membuatnya menjadi sumber, di mana hal itu dapat berdampak negatif pada produk.
• Dari pertanyaan: kontributor yang melakukan peningkatan yang tidak diinginkan tidak tahu tentang keputusan sebelumnya yang spesifik untuk tidak meningkatkan.

Yang pertama, menurut saya, adalah yang paling serius. Jika pemutakhiran SDK yang tidak diinginkan dapat membuatnya menjadi kode, demikian juga masalah lainnya.

Seseorang menyarankan menambahkan case test unit yang akan gagal jika mendeteksi upgrade. Sementara itu akan mencegah upgrade terjadi, saya percaya ini adalah jalur berbahaya, yang mengarah ke aliran lava dari waktu ke waktu. Tampaknya tak terhindarkan bahwa di beberapa titik di masa depan SDK akan ditingkatkan, untuk menghadirkan fitur baru atau perbaikan bug, atau karena versi lama tidak lagi didukung. Bayangkan head-scratching, bahkan mungkin argumen, yang akan terjadi ketika unit test seperti itu gagal.

Saya pikir solusi paling umum adalah menyesuaikan proses pengembangan. Untuk git, gunakan proses tarik permintaan . Untuk Subversion dan alat yang lebih lama, gunakan cabang dan diff. Tetapi memiliki beberapa proses yang memungkinkan pengembang senior untuk menangkap masalah semacam ini sebelum mereka membuatnya menjadi basis kode dan mempengaruhi pengembang lain.

Jika proses permintaan tarikan telah digunakan dalam situasi Anda, dan jika setiap permintaan tarikan sempit dan spesifik, tidak banyak waktu akan terbuang sia-sia. Permintaan tarikan untuk memutakhirkan SDK akan diajukan, dan ditolak dengan komentar bahwa pemutakhiran tidak diinginkan. Tidak ada orang lain yang akan terkena dampak, dan sekarang tidak perlu mengembalikan upgrade SDK.

Tetapi untuk langsung menjawab pertanyaan awal, saya setuju dengan yang lain yang mengharapkan semua pengembang untuk sepenuhnya membaca seluruh sejarah revisi kode, catatan rilis, dll untuk pemberitahuan seperti ini adalah buang-buang waktu yang berharga. Ada apa dengan email tim pendek?

Kemungkinan masalah ketiga: Mengapa pembaruan tidak diinginkan sejak awal? Jelas setidaknya satu pengembang mengira peningkatan akan menjadi hal yang baik. Ada banyak alasan bagus untuk menunda upgrade, tetapi juga banyak alasan buruk. Berhati-hatilah untuk menghindari aliran lahar (kode kompatibilitas ke belakang yang tidak perlu) dan kultus kargo ("kami tidak dapat memutakhirkannya, tetapi saya tidak tahu mengapa") anti-pola!

Saya akan mengatakan menambahkan bahwa jenis informasi ke riwayat komit ok tetapi masih perlu didokumentasikan dengan baik. Kami baru-baru ini mulai menggunakan pertemuan (oleh atlassian). Ini dapat dicari, Anda dapat mengatur halaman tertentu sebagai favorit, dll.

Beberapa alat lain mungkin berupa buku catatan umum di evernote atau google docs.

Memperluas jawaban Karl , saya akan pergi dengan pendekatan yang secara otomatis memberlakukan pembatasan sebagai bagian dari proses checkin itu sendiri. Anda memerlukan sesuatu yang tidak memerlukan tindakan proaktif atas nama pengembang, seperti membaca dokumen / wiki / README, dan tidak dapat ditimpa secara terselubung.

Di tanah kendali sumber TFS Anda dapat membuat kode kebijakan checkin khusus yang menjalankan aturan pada checkin. Misalnya, Anda bisa menetapkan kebijakan yang mengevaluasi versi dalam file konfigurasi dengan checkin yang tertunda dan akan gagal jika tidak sama dengan xyz Aturan ini sebenarnya mencegah pengembang melakukan checkin dan dapat memberikan pesan deskriptif. Kebijakan dapat ditimpa, tetapi dimungkinkan untuk menghasilkan peringatan ketika ini terjadi.

Alternatif dapat dibuat-checkin yang gagal akan dengan beberapa bentuk unit test yang baik secara langsung atau tidak langsung mengevaluasi versi SDK, seperti yang disebutkan Karl.

Saya menghargai jawaban ini sangat TFS-sentris, tetapi mungkin fitur serupa ada di sistem kontrol versi / CI yang berlaku dalam situasi Anda (jika tidak TFS).