Git favorit saya berkomitmen

Catatan perev. : Publikasi seorang programmer Inggris, yang telah menjadi hit nyata di Internet berbahasa Inggris, mengacu pada komitmen Git 6 tahun yang lalu. Itu direkam di salah satu repositori terbuka Layanan Digital pemerintah - layanan yang didedikasikan untuk pengembangan layanan digital di Inggris dan mendukung proyek GOV.UK. Komit itu sendiri menarik tidak begitu banyak dengan perubahan dalam kode seperti dengan deskripsi yang menyertai mereka ...


Gambar dari xkcd # 1296

Saya suka mengkomit deskripsi di Git. Ketika digunakan dengan benar, mereka dapat disebut salah satu alat paling kuat untuk mendokumentasikan evolusi basis kode selama keberadaannya. Saya ingin mengilustrasikan sudut pandang saya dengan contoh deskripsi favorit saya.

Komitmen ini berasal dari ketika saya bekerja di Layanan Digital Pemerintah. Penulisnya adalah pengembang bernama Dan Carley , dan memiliki judul yang agak biasa-biasa saja: " Konversi templat ke US-ASCII untuk memperbaiki kesalahan ."

“Saya telah mengimplementasikan beberapa tes di cabang fitur untuk mencocokkan isi` / etc / nginx / router_routes.conf`. Mereka bekerja dengan baik jika dijalankan dengan perintah `bundle exec rake spec` atau` bundle exec rspec modules / router / spec`. Tetapi ketika menjalankan `bundle exec rake`, masing-masing blok harus gagal:

ArgumentError: invalid byte sequence in US-ASCII 

Pada akhirnya, saya menemukan bahwa setelah pengecualian pada ekspresi `.with_content (//)`, semua kesalahan hilang. Bahwa tidak ada karakter aneh di file spesifikasi. Dan itu juga bisa dimainkan dengan memanggil Wayang dalam juru bahasa yang sama:

  rake -E 'require "puppet"' spec 

Template ini tampaknya menjadi satu-satunya file dalam basis kode kami yang dikodekan dengan 'utf-8'. Semua file lain di 'us-ascii':

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

Upaya menerjemahkannya ke US-ASCII gagal karena satu karakter yang terlihat seperti spasi:

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

Setelah menggantinya (secara manual) file kembali menjadi 'US-ASCII':

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

Sekarang tesnya berhasil! Seluruh jam hidupku tidak dapat dikembalikan ... "

Penyimpangan kecil: salah satu manfaat pengembangan sumber terbuka yang dipraktikkan dalam GDS adalah bahwa Anda dapat membagikan contoh seperti ini di luar organisasi yang menciptakannya. Saya tidak tahu siapa yang pertama kali mengusulkan konsep ini ke GDS - saat saya bergabung dengan organisasi, itu sudah banyak digunakan - tapi saya sangat berterima kasih kepada orang ini.

Kenapa saya suka komit ini

Berkali-kali saya mengutipnya sebagai contoh kemampuan deskripsi deskripsi. Agak lucu karena rasio perubahan kode dan ukuran uraian, tapi saya tidak suka sama sekali.

Di perusahaan lain, dengan pengembang lain, seluruh pesan dari komit dapat direduksi menjadi frasa seperti "mengganti celah", "memperbaiki kesalahan" atau (tergantung pada budaya tim) untuk menyerang terhadap penemu ruang yang tidak bisa dipisahkan. Alih-alih, Dan meluangkan waktu untuk membuat deskripsi terperinci yang bermanfaat bagi orang lain. Saya ingin memikirkan alasan mengapa saya menganggap komitmen ini sebagai contoh yang sangat baik.

Mengungkapkan alasan untuk perubahan

Deskripsi komit terbaik tidak hanya memberi tahu tentang apa yang telah berubah, tetapi juga menjelaskan alasannya . Dalam kasus kami:

Saya telah mengimplementasikan beberapa tes di cabang fitur untuk mencocokkan isi `/ etc / nginx / router_routes.conf`. Mereka bekerja dengan baik jika dijalankan dengan perintah `bundle exec rake spec` atau` bundle exec rspec modules / router / spec`. Tetapi ketika menjalankan `bundle exec rake`, masing-masing blok harus gagal:

  ArgumentError: invalid byte sequence in US-ASCII 

Tanpa tingkat perincian seperti itu, kita dapat mengasumsikan bahwa komit mengoreksi kesalahan parsing pada alat tertentu. Berkat deskripsi komit, kami tahu alat apa itu.

Informasi seperti ini ternyata sangat berharga, dan terlalu mudah hilang, karena orang cenderung melupakan seluk-beluk pekerjaan mereka, pindah ke tim lain dan akhirnya meninggalkan perusahaan.

Bagus untuk pencarian

Salah satu elemen kunci dari deskripsi ini adalah kesalahan itu sendiri, dengan mana pencarian lebih lanjut dimulai:

ArgumentError:
urutan byte tidak valid di US-ASCII

Siapa pun yang mengalami kesalahan ini dapat mencari basis kode, baik dengan menjalankan git log --grep "invalid byte sequence" , atau menggunakan GitHub melakukan pencarian . Bahkan, dilihat dari hasil pencarian, banyak yang sudah melakukannya dan menemukan siapa dan kapan dihadapkan dengan masalah ini dan bagaimana akhirnya diselesaikan.

Memberikan gambar lengkap

Pesan komit merinci bagaimana masalah tampak, bagaimana itu diselidiki dan diselesaikan. Sebagai contoh:

Pada akhirnya, saya menemukan bahwa setelah pengecualian pada ekspresi `.with_content (//)`, semua kesalahan hilang. Bahwa tidak ada karakter aneh di file spesifikasi. Dan itu juga bisa dimainkan dengan memanggil Puppet dalam interpreter yang sama.

Ini adalah salah satu area di mana pesan pada commit benar-benar dapat menunjukkan diri, karena mereka menggambarkan perubahan itu sendiri, dan bukan beberapa file, fungsi, atau baris kode. Ini membuat mereka menjadi tempat yang hebat untuk menyimpan informasi petualangan basis kode semacam ini.

Membuat semua orang sedikit lebih pintar

Dan melakukan satu hal di sini, yang sangat saya hargai: membawa semua tim yang saya lakukan di setiap tahap. Ini adalah cara yang bagus dan terjangkau untuk berbagi pengetahuan dalam tim. Membaca deskripsi komitnya, Anda dapat belajar banyak tentang alat Unix:

• Anda dapat melewatkan argumen -exec untuk find mengeksekusi perintah dengan setiap file ditemukan;
• menambahkan \+ di akhir perintah melakukan sesuatu yang sangat menarik (meneruskan beberapa nama file ke perintah file , dan tidak menjalankan perintah satu kali untuk setiap file);
• file --mime memungkinkan file --mime untuk mengetahui jenis file MIME;
• ada iconv utilitas.

Seseorang yang melihat deskripsi dapat mempelajari semua hal ini. Siapa pun yang menemukan komitmen ini nantinya juga akan belajar tentang hal-hal ini. Jika Anda melipatgandakan pendekatan ini dengan komitmen untuk waktu yang lama dan jumlah yang cukup dari mereka, itu bisa menjadi penolong insentif yang kuat untuk tim.

Mengembangkan empati dan kepercayaan

Sekarang tesnya berhasil! Seluruh jam hidupku tidak dapat dikembalikan ...

Paragraf terakhir menambahkan sedikit kemanusiaan. Membaca kata-kata ini, sulit untuk tidak merasakan kekecewaan dari Dan, yang harus menghabiskan satu jam mencari kesalahan tersembunyi, dan kepuasan untuk memperbaikinya.

Sekarang bayangkan sebuah pesan serupa dilampirkan pada retasan sementara atau fragmen kode prototipe yang masuk ke produksi dan "mengambil root" (seperti yang sering terjadi dengan fragmen seperti itu). Deskripsi komitmen ini mengingatkan semua orang bahwa di balik setiap perubahan adalah orang yang membuat keputusan terbaik, mengingat informasi yang tersedia pada saat itu.

Komitmen yang baik penting

Saya akui bahwa ini adalah contoh ekstrem, dan saya tidak berharap semua komitmen (terutama dalam cakupan seperti itu) membanggakan tingkat detail yang sama. Namun, saya masih berpikir bahwa ini adalah contoh yang bagus untuk menjelaskan alasan perubahan, membantu orang lain untuk mempelajari hal-hal baru dan berkontribusi pada model mental kolektif yang terkait dengan basis kode.

Jika Anda ingin tahu lebih banyak tentang kelebihan deskripsi komitmen yang baik dan beberapa alat yang membuatnya mudah untuk menyusun suntingan, saya dapat merekomendasikan bahan-bahan berikut:

• “ Bercerita melalui komitmu ” oleh Joel Chippindale;
• " Cabang dalam waktu " oleh Tekin Süleyman.

PS dari penerjemah

Baca juga di blog kami:

• “ Git terjadi! 6 kesalahan khas Git dan cara memperbaikinya ";
• “ Trik luar biasa untuk membuat pengelola proyek sumber terbuka sehari ”;
• “ Apa kesamaan proyek Open Source besar yang sukses? ".