Peninjauan kode

Dokumen ini menjelaskan filosofi peninjauan kode tim XLA – filosofi yang kami kembangkan selama bertahun-tahun sebagai pengalaman kolektif dalam mengerjakan project open source secara umum dan XLA pada khususnya.

Project open source yang berbeda memiliki ekspektasi budaya yang berbeda terkait seberapa banyak yang dapat diminta peninjau dari penulis kode. Dalam beberapa proyek, peninjau akan mengambil permintaan pull (PR) yang "sebagian besar benar", mengubahnya sendiri, dan mengirimkannya. XLA mengambil pendekatan yang berbeda: Kami berharap penulis melakukan iterasi PR sampai cukup baik untuk dikirimkan tanpa perubahan tambahan.

Alasan utama pendekatan ini adalah kami ingin penulis PR belajar menjadi kontributor XLA yang matang. Jika peninjau memperbaiki masalah dalam kampanye Humas, akan jauh lebih sulit bagi penulis untuk mempelajarinya. Pendekatan XLA dapat menjadi tantangan bagi peninjau dan penulis, tetapi kami yakin hal ini pada akhirnya membantu kami mengembangkan komunitas.

Belajar menjadi "kontributor XLA yang matang" bukan hanya tentang menulis kode yang tidak memiliki bug. Masih banyak lagi yang perlu dipelajari tentang cara berkontribusi pada XLA. Hal ini mencakup:

  • gaya coding
  • {i>edge case<i} yang harus diwaspadai
  • ekspektasi seputar penulisan tes
  • ekspektasi seputar komentar dan deskripsi PR
  • ekspektasi seputar membangun infrastruktur untuk mendukung perubahan Anda

Saat membangun pengetahuan tentang project dan kepercayaan dari peninjau, akan ada lebih sedikit komentar yang akan Anda terima, karena secara alamiah Anda menulis kode yang lebih selaras dengan ekspektasi peninjau.

Seperti banyak project open source, XLA memiliki beberapa orang yang sangat berpengalaman dan banyak orang yang relatif baru. Kita yang sangat berpengalaman memiliki banyak tuntutan saat ini. Anda dapat menjalankan PR secara tepat waktu dan mengurangi jumlah iterasi dengan mengikuti saran-saran berikut:

  • Tinjau dengan cermat siaran pers dan/atau minta PR Anda ditinjau oleh rekan kerja sebelum mengirimnya: Cobalah untuk menghapus kesalahan sepele (kesalahan gaya kode, ejaan dan tata bahasa, dll.) sebelum mengirim PR untuk ditinjau. Pastikan semua pengujian lulus.
  • Baca komentar pengulas Anda dengan cermat: Cobalah untuk memahami apa yang diminta pengulas dan cobalah untuk menjawab semua komentar sebelum Anda mengirimkan versi baru.
  • Hindari diskusi tangensial (bersepeda): Diskusi teknis dan pertentangan sangat berharga dan tidak ada yang sempurna. Namun, hindari diskusi yang tidak menimbulkan perbedaan atau hanya bergaya. Jika Anda tidak setuju dengan komentar peninjau, coba jelaskan alasan Anda setepat dan selengkap mungkin untuk menghindari diskusi yang panjang.
  • Hindari mengajukan "pertanyaan ulasan umum" yang tercantum di bawah: Kami telah mencantumkan beberapa jawaban atas pertanyaan umum beserta alasannya di bawah ini.

Secara umum, kami mengajak Anda untuk mencoba agar peninjauan PR Anda memerlukan waktu sesedikit mungkin bagi kami. Selanjutnya, kami akan dapat meninjau perubahan Anda dengan cepat!

Terima kasih telah berkontribusi pada XLA, dan selamat mencoba!

Pertanyaan peninjauan yang umum diajukan

Tim XLA tidak memiliki tim infrastruktur khusus, jadi kita semua bebas membangun library helper dan menghindari utang teknis. Kami menganggapnya sebagai bagian rutin dalam membuat perubahan pada XLA, dan semua orang diharapkan dapat berpartisipasi. Kita biasanya membangun infrastruktur sesuai kebutuhan saat menulis kode.

Peninjau XLA mungkin meminta Anda untuk membangun infrastruktur (atau membuat perubahan besar pada PR) bersama dengan PR yang telah Anda tulis. Permintaan ini mungkin tampak tidak perlu atau ortogonal terhadap perubahan yang Anda coba lakukan. Hal ini kemungkinan karena ketidakcocokan antara ekspektasi Anda tentang jumlah infrastruktur yang perlu di-build dan ekspektasi peninjau untuk hal yang sama.

Ketidakcocokan dalam ekspektasi adalah hal yang wajar! Hal ini wajar ketika Anda baru mengenal suatu project (dan kadang hal ini bahkan terjadi pada kita). Kemungkinan besar proyek yang telah Anda kerjakan sebelumnya memiliki ekspektasi yang berbeda. Hal itu juga tidak apa-apa dan diharapkan! Bukan berarti salah satu dari proyek ini memiliki pendekatan yang salah; keduanya hanya berbeda. Kami mengundang Anda untuk menerima permintaan infra bersama semua komentar ulasan lainnya sebagai kesempatan untuk mempelajari apa yang kami harapkan pada project ini.

"Bisakah saya menanggapi komentar Anda dalam PR mendatang?"

Pertanyaan yang sering diajukan sehubungan dengan permintaan infrastruktur (atau permintaan besar lainnya) dalam PR adalah apakah perubahan harus dilakukan dalam PR asli atau tidak, atau apakah perubahan dapat dilakukan sebagai tindak lanjut dalam Humas mendatang.

Secara umum, XLA tidak mengizinkan penulis PR untuk menangani komentar ulasan dengan PR tindak lanjut. Saat peninjau memutuskan bahwa sesuatu perlu ditangani dalam PR tertentu, biasanya kami mengharapkan penulis menanganinya dalam PR tersebut, meskipun hal yang diminta adalah perubahan besar. Standar ini berlaku secara eksternal dan juga secara internal di dalam Google.

Ada beberapa alasan mengapa XLA melakukan pendekatan ini.

  • Kepercayaan: Mendapatkan kepercayaan dari peninjau merupakan komponen utama. Dalam project open source, kontributor dapat muncul atau menghilang sesuai keinginan. Setelah kami menyetujui PR, peninjau tidak memiliki cara untuk memastikan bahwa tindak lanjut yang dijanjikan benar-benar dilakukan.

  • Dampak pada developer lain: Jika Anda telah mengirim PR yang menyentuh bagian tertentu dari XLA, ada kemungkinan orang lain melihat bagian yang sama. Jika kami menerima utang teknis dalam PR Anda, semua orang yang melihat file ini akan terpengaruh oleh utang ini sampai tindak lanjut dikirimkan.

  • Bandwidth peninjau: Menunda perubahan pada tindak lanjut akan menimbulkan beberapa biaya bagi peninjau kami yang sudah kelebihan beban. Peninjau mungkin akan melupakan apa tentang PR pertama saat menunggu tindak lanjut, membuat peninjauan berikutnya menjadi lebih sulit. Peninjau juga harus melacak tindak lanjut yang diharapkan, memastikan bahwa itu benar-benar terjadi. Jika perubahan dapat dilakukan sehingga benar-benar ortogonal dengan PR asli sehingga beberapa peninjau lain dapat meninjaunya, bandwidth tidak akan menjadi masalah. Berdasarkan pengalaman kami, hal ini jarang terjadi.