Check this article on Medium: @ngodingbang/my-first-pull-request-to-laravel-framework-part-3-bbe0bec18671

You may want to read this article in Bahasa Indonesia version: Pull Request Pertama Saya di Laravel Framework — Part 3

The story of how I discovered and fixed the bug in Laravel can be found in the previous part.

What to Do Next?

After going through a winding journey to solve this bug, it’s time to submit this bugfix to Laravel. The problem was that I had no experience in making a pull request. Fortunately, Laravel provides detailed documentation on how to file a bug report while offering a solution.

Let’s go through some of these steps briefly; it might give you an idea of how to submit a pull request to Laravel.

Bug Reports

Laravel emphasizes that when you submit a bug report, you should ideally include a pull request with the bug fix as well. The goal is for us, as Laravel users, to take an active role in improving the framework as part of the open-source community.

If you can’t provide a fix for the bug, Laravel encourages you to write a clear title and description of the bug. Additionally, include as much relevant information as possible and provide source code examples. This way, other developers can easily understand and reproduce the issue on their machines.

For more tips on writing bug reports, you can check out this guide: https://gist.github.com/larsenwork/3f92a3adf79838abd7d6b15c5b74f7b0.

Which Branch?

Laravel usually supports two main versions at any given time, such as version 8 and version 9. So, if you’re reporting a bugfix, your pull request should be submitted to the 8.x branch. For minor updates, submit your pull request to the 9.x branch. Here’s a quick breakdown:

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

Coding Style

Laravel follows PSR-2 coding standards and PSR-4 autoloading standards. Additionally, every method in a class must be documented using PHPDoc like this:

Some important components visible in the image above are:

• Register a binding …: It describes the purpose and details of the method below it.
• @param: Lists the parameters defined in the method and their data types. While PHP allows us to use type hinting, you may notice that some parameters have multiple data types separated by OR (|). This feature is only available in newer PHP versions (either 7 or 8, correct me if I’m wrong), so PHPDoc helps fill that gap.
• @return: The return type of the method, similar to the @param in structure.

Why is PHPDoc required? It has several benefits. Besides helping IDEs and text editors like VSCode better understand the code, it also serves as documentation for other developers. Since Laravel is an open-source framework, the code you write will not only be used by you but also maintained and improved by thousands of other developers worldwide. That’s why PHPDoc is so essential.

Now, let’s dive into my experience of submitting the pull request for the bugfix I created earlier.

Pull Request Process

Once the bug was fixed, the next step was to submit a pull request to Laravel’s official GitHub repository. If you’re not familiar with how GitHub works, a pull request is a way to suggest changes to a repository’s code—in this case, the Laravel Framework. Here are the steps I followed:

Fork the Laravel Repository

The first step was to fork the Laravel repository. This creates a copy of the Laravel repository in my own GitHub account, where I can make changes.

Clone the Forked Repository Locally

After forking, I cloned the repository to my local machine with the following command:

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

Checkout the Branch

According to the Laravel Contribution Guide, any bugfix changes should be made in the branch where the current stable version of Laravel resides, like 8.x. So I checked out to that branch:

git checkout 8.x

Make Code Changes

On the 8.x branch, I started implementing the bugfix. I also ensured that the code followed Laravel’s standards, as explained earlier, such as PSR-2 and PSR-4.

Create Unit Tests

Laravel uses PHPUnit for running unit tests. I made sure that my changes did not break any other features by writing and running all the unit tests:

vendor/bin/phpunit

Commit dan Push

Once the changes and tests were complete, I committed the changes and pushed them to my GitHub repository:

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

Create a Pull Request

After pushing the code to GitHub, the last step was to open the Laravel repository and create a pull request from my 8.x branch to the 8.x branch of the official Laravel repository.

Here, I added a clear description of the bug I fixed and briefly explained the changes.

Review dan Merge by the Laravel Team

Once the pull request is created, it usually undergoes a code review by Laravel’s core team or other contributors. In my case, I was surprised that my first pull request was directly approved and merged by Taylor Otwell —the creator of Laravel— the very next day without any revisions. This was an amazing experience that motivated me to contribute more to open-source projects in the future.

Conclusion

That’s the complete story of my first experience making a pull request to the Laravel Framework, from finding the bug, fixing it, and finally having my contribution accepted. I hope this story gives you an idea and inspires you to start contributing to the open-source world.

If you have any further questions or need help in making a pull request, don’t hesitate to ask. Thank you!