Menulis Deskripsi Pull Request yang lebih baik

Photo by ThisIsEngineering

Table Of Contents

Preface

Code Review merupakan bagian yang sangat penting ketika mengembangkan sebuah produk digital. Di Github dan beberapa hosting repository, Pull Request (disebut Merge Request di Gitlab) digunakan untuk me-review kode di suatu branch sebelum kode tersebut bisa menjangkau branch master/target. Seringnya membutuhkan anggota tim yang berpengalaman yang harus meluangkan waktu buat membaca, mengevaluasi, merespon, dan memberi masukkan dari kode untuk fitur baru tersebut.

Saya mengganti kata Pull Request / Merge Request menjadi PR supaya lebih singkat

.   .   .

Perspektif Reviewer

Kalau kamu pernah me-review PR, akui saja kalau me-review sebuah PR bukan hal yang mudah. Sebagai Reviewer, sudah jadi tanggung jawabmu buat memastikan kode yang sedang di review merupakan kode yang bagus dan berkualitas sebelum kode tersebut masuk di branch target.

Kamu harus paham apa yang kode tersebut lakukan, bagaimana logikanya, apakah kode tersebut aman dan tidak merusak sistem yang sudah berjalan. Selain itu kamu harus melihat style code nya apakah sudah cukup rapi, apakah ada typo, apakah ada cara lain yang lebih singkat, dan untuk melakukannya kamu harus melihat kode yang diubah baris perbaris. Well, banyak yang harus dilakukan seorang Reviewer, apalagi kalau kode yang berubah sangat banyak.

.   .   .

Perspektif Pembuat Pull Request

Di sisi lain, kamu juga meminta kodemu di-review developer lain. Kamu sedang dikejar deadline tapi kodemu gak kunjung selesai di review. Setelah membaca Perspektif Reviewer di atas, harusnya kamu paham kenapa kodemu tak kunjung selesai di review. Selain kesulitan Reviewer yang saya sebutkan di atas, Reviewer pasti juga punya kerjaan yang harus dia selesaikan bukan?

Trus gimana caranya kita meringankan beban Reviewer dan kode kita bisa cepat merged? Salah satunya adalah dengan menulis deskripsi yang baik.

Tulisan saya disini merupakan principles yang sampai sekarang selalu ada di kepala & saya terapkan ketika membuat sebuah PR. Tulisan ini terinspirasi dari apa yang diajarkan Shalabh Aggarwal, ex.Engineering Manager saya terdahulu yang sekarang sudah balik ke India dan bekerja di sana.

.   .   .

Kenapa saya harus peduli?

Gambar 1: Kenapa saya harus peduli?

Selalu tanamkan di pikiran kalau sebuah PR adalah produkmu. Tiap kali kamu bikin PR, seseorang bernama “Reviewer” adalah kustomer mu. Kamu mau supaya kustomer tersebut membeli produkmu, supaya produkmu yang dalam bentuk PR itu bisa di-deploy ke server secepatnya bukan?

Tiap kali mau bikin PR berhentilah sejenak, bayangkan kamu menjadi si “Reviewer”, trus tanya ke dirimu sendiri. “Gimana ya supaya ini mudah dipahami?”.

Kalau kamu belum yakin kenapa menulis deskripsi PR itu penting, mungkin poin-poin berikut bisa membantu:

Meng-capture konteks

Saya selalu percaya sebuah deskripsi PR itu bukan cuma sebatas hubungan antara pembuat PR dan Reviewer, tapi juga sebagai histori kode di project kita. Suatu saat kita pasti akan melihat sebuah kode dan gak tau itu buat apa, dengan adanya histori PR kita bisa selalu melacak histori terdahulu sampai akhirnya kita bisa paham kenapa kode itu ada.

Tentu gak perlu ada deskripsi PR buat bisa ngeliat kodenya. Tapi yang gak akan bisa kamu temuin di kodenya adalah:

1. “Kenapa perubahan itu dilakukan?”
2. “Apa masalah yang di solve dari kode ini?”
3. “Gimana kode ini bekerja?”
4. “Kenapa kode ini bisa ada di planet ini??”

Sebuah deskripsi PR yang bagus yang bakal menjawab semuanya.

Buat bisa ngerasain pain point nya, sekarang cobalah buka sebuah PR yang udah merged 1tahun yang lalu dan yang berisi lebih dari 100baris kode / 50 file, trus jawab ke 4 pertanyaan di atas.

Susah bukan? Hehe..

Membawa ke solusi yang terbaik

Deskripsi yang bagus bisa menuntun kita ke sebuah diskusi.

Tentu kamu tau, kamu gak mungkin punya solusi terbaik dari suatu masalah. Seringnya selalu ada orang lain di tim mu yang lebih tau tentang area yang sedang kamu kerjakan dari pada kamu.

Reviewer punya kesempatan buat ngasih kamu alternatif solusi yang lebih baik dari apa yang ada di PR. Tanpa deskripsi yang memberikan gambaran yang jelas ke Reviewer tentang solusi yang kamu bikin, kamu secara gak langsung mengurangi kesempatan diskusi dan tentu mengurangi kesempatan buat adanya kode & solusi yang lebih baik.

Review jadi lebih mudah

Deskripsi PR yang bagus akan memberikan petunjuk ke Reviewer tentang apa yang bakal dia temukan di kodenya.

Isinya juga bisa berisi informasi tentang apa yang perlu dia fokuskan untuk di review, yang kamu gak yakin dari apa yang sudah kamu bikin. Hal ini membuat proses review lebih cepat dan PR tersebut cepat mendapat feedback.

Membuatmu lebih berharga

Kita sebagai developer menghabiskan waktu setiap hari buat mecahin masalah.

Kalau kamu menghabiskan waktu seminggu buat mecahin masalah atau mungkin juga nyari bug, menyisihkan waktu sejam buat nulis deskripsi PR yang mendetail akan lebih baik karena Reviewer atau bahkan rekanmu jadi tau kenapa masalah yang coba kamu pecahkan memang rumit sampai butuh waktu sampai seminggu.

.   .   .

Pull Request yang ideal

PR yang ideal adalah PR yang kecil. PR kecil bisa mempercepat proses review dan cepat dapat feedback. Karena kecil, otomatis jadi lebih mudah bagi si Reviewer buat bisa ngerti konteksnya dan bagaimana logika yang dibikin.

Kalau fitur yang lagi kamu bikin itu besar atau kompleks banget, kamu bisa mecah fiturnya supaya PR nya jadi kecil-kecil.

Kita harus paham bagaimana memecahnya dan berpikir gimana caranya supaya yang kecil-kecil tadi bisa merged tanpa merusak apapun.

Memecah fitur memang gak mudah, dan perlu dibiasakan. Semakin sering kamu memecah fitur, maka akan semakin terbiasa.

Di tempat saya bekerja sekarang, kalau fitur nya besar maka kami bakal bikin satu branch sendiri yang kami sebut Story. Nah, PR yang kecil-kecil tadi di targetkan ke Story, ketika semua yang kecil-kecil sudah selesai dan semua sudah tersusun di Story, baru dari Story tersebut bikin PR lagi ke branch utama.

.   .   .

Anatomi Pull Request

Semoga sampai di sini kamu sudah paham pentingnya deskripsi sebuah PR.

Tapi apakah ada aturan tertentu yang bisa di ikuti? Sebenernya tidak ada aturan khusus, tapi setidaknya berikut poin-poin yang saya terapkan ketika membuat PR:

Title

Sebuah judul PR yang bagus menurut saya harus berupa:

1. Ringkasan singkat tentang apa yang dikerjakan

Judul harus cukup singkat dan informatif sehingga Reviewer langsung tau apa poin utama dari PR yang kamu buat, tanpa dia harus membaca seluruh deskripsi yang ada.

2. Kalimat yang disusun, ditulis layaknya sebuah perintah.

Contohnya, dari yang tadinya “Menghapus middleware auth dan menggantinya dengan sistem auth yang baru” bisa diganti menjadi “Hapus middleware auth dan ganti dengan sistem auth yang baru”.

Karena judulnya berupa perintah, bagaimana kita melaksanakan perintah tersebut ada di dalam deskripsi dan kodenya.

Body

Deskripsi yang informatif

Deskripsi yang ditulis harus informatif. Paling tidak berisi poin-poin berikut:

✓  Apa masalah yang coba buat dipecahkan.
✓  Kenapa solusi tersebut menurutmu jadi solusi yang tepat.
✓  Jika ada kelemahan dari solusi tersebut, juga harus disebutkan.
✓  Apa yang bisa di tingkatkan di masa depan juga harus disebutkan.

Saya sering melihat kebiasaan menulis deskripsi yang buruk, seperti contohnya:

✕  "Fix build”
✕  "Fix bugs”
✕  "Add patch”
✕  "Moving code from A to B”
✕  "Kill weird URLs.”

Gak jelas kan? Bug apa? Patch apa? Kill weird url? Kamu ngapain buat ngebenerinnya?

Di beberapa kasus bahkan gak ada deskripsinya sama sekali 😥

Mungkin kalo kodenya dikit masih bisa kita coba cari tau dari kodenya, kalau changes nya lebih dari 50 file gimana? Hmm…

Gambar 2: Bad PR Example

Hasil Unit Tests

Hasil dari unit tests dari fitur yang kamu kerjakan juga bisa ikut disertakan, sehingga Reviewer tau apa saja test case yang kamu buat dan gimana hasilnya.

Beberapa company biasanya mewajibkan tiap fitur baru yang dibuat, harus datang bersamaan dengan unit tests-nya

Screenshots

Kalau kamu punya sesuatu yang bisa kamu bagikan dalam bentuk visual, kamu juga bisa melampirkannya di body PR.

Untuk seorang Front-End Engineer, bagian screenshots di ini bisa dipakai untuk menampilkan hasil UI yang udah dibikin. Kalau kamu mau, kamu juga bisa melampirkan extra gif atau video di bagian ini.

Tentu bagian screenshots bukan hal wajib apalagi kalau kamu seorang DevOps, Back-End Engineer, atau role lain yang tidak berhubungan dengan visual.

.   .   .

Template Pull Request

Dengan menerapkan principle yang telah saya sebutkan di atas, kamu bisa meningkatkan kualitas kode dari aplikasimu dan membuka kesempatan untuk diskusi antar developer yang lebih baik.

Lalu gimana caranya company yang berisi ratusan developer bisa mengikuti principle yang sama?

Di tempat bekerja saya sekarang, kami membuat sebuah PR Template yang berisi beberapa pertanyaan yang wajib dijawab siapapun yang ingin membuat PR, supaya semua developer bisa tetap berada di principle yang sama.

Kurang lebih isi template nya mengandung pertanyaan sebagai berikut:

1. “Apa masalah/bug/improvement yang kamu coba selesaikan?”
2. “Bagaimana kamu menyelesaikan masalah tersebut?”
3. “Apa kelemahan dari solusi yang kamu buat?”
4. “Apa yang bisa di tingkatkan dari solusimu sekarang di masa depan?”
5. “Lampiran Screenshots Unit Tests”
6. “Lampiran Screenshots UI (Opsional)”

Cara membuat sebuah template PR bisa ikuti panduan dari Github di sini, atau jika kamu pakai Gitlab bisa baca di sini.

.   .   .

Penutup

Semua project besar tidak mungkin melewatkan deskripsi tiap PR nya, ini juga alasan kenapa project Open Source di luar sana memiliki kualitas yang bagus. Salah satunya karena mereka selalu melakukan diskusi dari setiap PR yang ada, dan ketika seorang kontributor tidak menjelaskan apapun di PR nya, biasanya kecil kemungkinan PR tersebut bisa di approve.

Apa yang saya share di sini adalah berdasarkan dari apa yang saya terapkan sehari-hari, tiap company pastinya punya rule sendiri tentang bagaimana mereka mengatur isi sebuah PR. Kalau company tempatmu bekerja belum menerapkan aturan penulisan deskripsi PR, kamu bisa coba menggunakan principle yang sama dengan yang saya gunakan.