Check this article on Medium: @ngodingbang/pull-request-pertama-saya-di-laravel-framework-part-3-996d3d3e2dcc

This article has been translated into English version: My First Pull Request to Laravel Framework — Part 3

Penjelasan mengenai bagaimana cerita saya ketika menemukan serta menyelesaikan bug pada Laravel sudah ada di part sebelumnya. Silakan dibaca ya :)

Apa yang Harus Dilakukan Sekarang?

Setelah melewati perjalanan yang berliku untuk menyelesaikan bug ini, saatnya men-submit bugfix ini ke Laravel. Masalahnya saya belum punya pengalaman sama sekali untuk membuat pull request. Untungnya Laravel sudah menyiapkan dokumentasi yang amat lengkap jika kita ingin membuat bug report sekaligus memberikan solusi dari bug tersebut.

Ada baiknya kita coba bahas secara singkat satu per satu, barangkali ini juga bisa memberimu gambaran ketika ingin membuat pull request ke Laravel.

Bug Reports

Laravel sangat menekankan kita untuk tidak hanya membuat bug reports saja, tapi juga menyertakannya bersama dengan pull requests dari bug reports tersebut. Tujuannya supaya kita sebagai pengguna Laravel bisa turut serta secara aktif dalam membangun Laravel sebagai sebuah open source.

Jika memang tidak mampu menyertakan solusi dari bug tersebut, kita diminta untuk menuliskan judul serta deskripsi yang jelas dari bug tersebut. Selain itu sertakan sebanyak mungkin informasi yang relevan dan juga contoh source code yang dibuat ketika bug tersebut terjadi. Sehingga orang lain yang membaca bug reports tersebut bisa memahaminya dengan mudah serta mereplikasi situasinya di komputer masing-masing.

Tips lebih lanjut tentang cara membuat bug reports bisa dibaca di sini: https://gist.github.com/larsenwork/3f92a3adf79838abd7d6b15c5b74f7b0.

Which Branch?

Laravel biasanya memiliki dua versi utama yang masih dalam support mereka, contohnya saat ini yaitu versi 8 dan 9. Jadi jika kita ingin melaporkan bugfix, maka pull requests-nya harus diarahkan ke branch 8.x. Sedangkan jika pull requests-nya bersifat minor update, maka pull requests-nya harus diarahkan ke branch 9.x. Penjelasan singkatnya bisa dicek di bawah ini.

• Bugfix => Branch 8.x
• Minor update => Branch 9.x
• Major update => Branch master__

Coding Style

Laravel saat ini mengikuti PSR-2 coding standard dan PSR-4 autoloading standard. Selain itu setiap method yang didefinisikan di tiap-tiap class wajib menyertakan PHPDoc seperti di bawah ini.

Ada beberapa komponen yang kita bisa lihat pada gambar di atas, seperti:

• Register a binding …: Tujuannya jelas, yaitu untuk mendeskripsikan fungsi dan detil dari method yang ada di bawahnya.
• @param: Menjabarkan apa saja parameter yang didefinisikan di method tersebut beserta tipe datanya. Memang di PHP kita bisa memanfaatkan fitur type hinting untuk mendeklarasikan tipe data dari parameter tersebut, tapi jika dilihat pada gambar maka akan kita temui beberapa parameter yang memiliki tipe data lebih dari satu. Dan mendeklarasikan tipe data dengan pemisah OR (|) seperti itu baru bisa dilakukan di versi PHP yang lebih baru (7 atau 8 kalau tidak salah, CMIIW). Jadi di sinilah PHPDoc bisa berperan untuk mengisi kekosongan tersebut.
• @return: Tipe data yang akan dikembalikan oleh method tersebut mirip seperti poin di @param sebelumnya.

Kenapa harus ada PHPDoc seperti ini? Manfaatnya banyak sekali sebenarnya. Selain membantu IDE ataupun text editor yang dipakai ketika melakukan coding — seperti VSCode — untuk memahami lebih detil tentang kode yang kita tulis, kita sebagai programmer juga terbantu dengan deskripsi yang dituliskan oleh si pembuat kode tersebut. Ingat bahwa Laravel adalah framework yang bersifat open source, jadi kode yang kamu buat tidak hanya digunakan oleh kamu sendiri. Melainkan digunakan dan di-maintenance juga oleh ribuan orang lainnya di luar sana yang menggunakan framework ini. Inilah pentingnya PHPDoc pada kode yang kita buat.

Sekarang mari kita langsung masuk ke ̶t̶u̶t̶o̶r̶i̶a̶l̶ cerita saya pada saat membuat pull request dari bugfix yang sudah saya buat sebelumnya.

Proses Membuat Pull Request

Setelah bug yang saya temukan selesai diperbaiki, langkah selanjutnya adalah membuat pull request ke repository resmi Laravel di GitHub. Jika kamu belum familiar dengan cara kerja GitHub, pull request adalah cara untuk menyarankan perubahan pada bagian kode tertentu ke open-source repository, dalam hal ini adalah Laravel Framework. Tahapan yang saya lakukan yaitu:

Fork Repository Laravel

Langkah pertama adalah melakukan fork repository Laravel. Ini adalah cara untuk membuat salinan dari repository Laravel ke akun GitHub pribadi saya, sehingga saya bisa melakukan perubahan pada salinan tersebut.

Clone Repository Hasil Fork ke Local

Setelah melakukan fork, saya meng-clone repository hasil fork ke komputer lokal saya dengan perintah berikut:

git clone https://github.com/<YOUR_USERNAME>/framework.git
cd framework

Melakukan Checkout Branch

Menurut Laravel Contribution Guide, perubahan untuk setiap bugfix harus dilakukan di branch tempat versi stabil Laravel tersebut, misalnya 8.x. Jadi saya melakukan checkout ke branch tersebut:

git checkout 8.x

Melakukan Perubahan Kode

Pada branch 8.x, saya mulai melakukan perubahan yang diperlukan untuk memperbaiki bug. Saya juga memastikan kode tersebut mengikuti standar Laravel, seperti yang dijelaskan sebelumnya terkait PSR-2 dan PSR-4.

Membuat Unit Test

Laravel menggunakan PHPUnit untuk menjalankan unit test. Saya memastikan bahwa perubahan yang saya buat tidak merusak fitur lain dengan membuat unit test dan menjalankan semua unit test yang ada:

vendor/bin/phpunit

Commit dan Push

Setelah selesai melakukan perubahan dan test, saya melakukan commit perubahan dan push ke repository GitHub saya:

git add .
git commit -m "Adding reference on $request parameter and retrieve the latest value from the given callback"
git push origin 8.x

Membuat Pull Request

Setelah kode di-push ke GitHub, langkah terakhir adalah membuka halaman repository Laravel di GitHub dan membuat pull request dari branch 8.x yang ada di akun saya ke branch 8.x pada repository resmi Laravel.

Di sini saya menambahkan deskripsi yang jelas mengenai bug yang saya perbaiki, serta menjelaskan secara singkat perubahan yang dilakukan.

Review dan Merge oleh Tim Laravel

Setelah pull request dibuat, biasanya akan ada proses code review oleh tim inti Laravel atau oleh kontributor lain. Dalam kasus saya, saya cukup terkejut karena pull request pertama yang saya buat pada saat itu langsung di-approve di-merge oleh Taylor Otwell – sang creator dari Laravel – keesokan harinya tanpa revisi apapun. Ini merupakan pengalaman yang luar biasa dan memberikan semangat bagi saya untuk terus berkontribusi ke open-source di masa depan.

Penutup

Kira-kira seperti itulah cerita lengkap mengenai pengalaman pertama saya dalam membuat pull request ke Laravel Framework. Dari mencari bug, memperbaikinya, hingga akhirnya kontribusi saya diterima. Semoga cerita ini bisa memberikan gambaran dan inspirasi bagi kamu yang ingin mulai berkontribusi di dunia open source.

Jika ada pertanyaan lebih lanjut atau kamu butuh bantuan dalam membuat pull request, jangan ragu untuk bertanya. Terima kasih!