Last Updated on 2024-01-15 by Clay
Introduction
Sending a Pull Request (PR) on GitHub to an open-source project is a wonderful yet significant endeavor.
In simple terms, a PR is when you come across an open-source project, notice a feature you really want to implement or a bug you'd like to fix, and you decide to fork the original project into your own private repository.
You then proceed with the development on your forked repository. Once the development is complete, you submit a PR to the original project's maintainers for a merge review, to determine whether it should be merged back into the main branch of the original project.
If your submission is accepted successfully, you have effectively contributed a new feature or resolved an issue for this open-source project. Collaborative efforts like these are what accelerate the development of the project, as it takes everyone's contributions to move it forward.
Upon careful consideration, isn't the beauty of open-source projects that they allow anyone to participate and contribute to the project? In other words, being willing to submit a PR to an open-source project signifies a selfless contribution of one's skills to enhance a particular feature or fix a bug in the project, ultimately providing a better experience for more people who use the project. This is truly a fantastic endeavor!
Recently, I made my first-ever pull request (PR) to an open-source project that wasn't related to my university or colleagues at work. I added a feature that I believed would be highly beneficial, and I am honored to announce that it has been successfully merged into the master/main branch. This experience has been truly rewarding for me.
Therefore, I aspire to comprehensively document the submission process, hoping that this PR experience won't be just a fleeting moment. I aim to ensure that the next time I revisit this note, it will be in the not-so-distant future.
How To PR
Here's a brief summary of the process:
- Check for similar issues or opinions in Issues and PRs and understand the maintainer's thoughts on the matter
- Read the project's contribution guidelines
- Fork the project to your account and clone it locally
- Set up the development environment
- Create a new branch
- Begin development or bug fixing
- Write unit tests
- Document the changes
- Commit the changes
- Before submitting, sync with the latest upstream version
- Push to your forked project
- Create a Pull Request
- Code review
- Merge
- Delete your branch in the open-source project
Below, I will provide a more detailed explanation of the tasks to be performed.
1. Check for similar issues or opinions in Issues and PRs and understand the maintainer's thoughts on the matter
Before you proceed with adding or modifying a feature in an open-source project, don't forget to check if similar ideas or changes have already been discussed in Issues and PRs. If you find existing discussions, consider referencing their suggestions or confirming the maintainer's stance on the proposed modification.
Sometimes, they may already have plans or even be in the midst of developing the feature you wish to contribute, so it's always a good idea to browse through them.
Even if you don't come across the same idea, it's polite to open an issue and inquire with the maintainers and the community for feedback before you start the actual development.
However, open-source communities are generally friendly, so don't hesitate to ask. Most people are enthusiastic about discussing their development work.
2. Read the project's contribution guidelines
Many open-source projects have their own Contribution Guidelines, which may specify the format of PRs, where to gather new feature requests, unified coding styles, submission processes, unit testing requirements, and more. Before you begin preparing to submit your desired feature, don't forget to take a look at this document.
3. Fork the project to your account and clone it locally
On GitHub, fork the project you want to contribute to into your own account, and then clone your forked project to your local machine.
4. Set up the development environment
Create an identical environment based on the project's documentation. Unless there are exceptional circumstances, never use your custom environment to develop someone else's project and then expect them to accommodate your setup.
5. Create a new branch
In your local repository, create a new branch for the feature you want to develop. Ideally, it's best practice to create a separate branch for each feature you work on. This approach allows our changes to be isolated from the main branch, making it easier to manage and review.
git checkout -b new-feature-branch6. Begin development or bug fixing
At this point, you are officially starting the development of a new feature or fixing a bug. Don't forget to adhere to the coding style and other requirements of the open-source project.
7. Write unit tests
If the project mandates it, don't forget to create unit tests as instructed and ensure they pass successfully. If there are no specific requirements, make sure to test the existing functionality for integrity and ensure that your newly added features work as intended.
8. Document the changes
Update or create relevant documentation, usually in README.md, explaining the new features you've added and how to use them. If you're fixing a bug, you generally don't need to modify this document; instead, document it in the issue or the submission description.
9. Commit the changes
Commit your modified files to your branch. Ensure that your commit messages are clear and can describe your updates effectively.
git add updated_file
git commit -m "your message"10. Before submitting, sync with the latest upstream version
Before submitting, sync with the latest changes from the main branch of the open-source project to ensure that your code remains compatible with the project's latest progress.
You can check your remote project settings with git remote -v. If the remote project is not set to the original open-source repository, you can add it yourself:
git remote add upstream https://github.com/original_owner/original_repo.gitHere, "upstream" is a user-defined alias representing the original open-source project, and the URL provided is the original project's URL.
在這裡，upstream 是我們自己定義的，代表原先開源項目，而後方的專案則是原始項目的 URL。
Once added, you can fetch the latest updates from upstream:
git fetch upstreamAfter confirming there are no issues, you can merge these changes into your local main or master branch based on your needs:
git checkout your_branch
git merge upstream/your_branchIf you want to maintain a clean history, you can use rebase.
git checkout your_branch
git rebase upstream/your_branch11. Push to your forked project
Finally, push your changes to your forked remote GitHub project:
git push origin new-feature-branch12. Create a Pull Request
At this point, if you go back to the original open-source project's page and click on the Pull requests tab, you should see that GitHub has automatically detected your branch for sending a PR. Click the green "Compare & pull request" button to submit your PR request.
Don't forget to provide a detailed description of your PR's functionality and purpose to help the maintainers understand your contribution better.
13. Code review
Next, you may engage in discussions with the maintainers, making necessary modifications based on their feedback or the community's input.
14. Merge
Once your PR is approved, the project maintainer will merge your submitted code into the main or master branch.
15. Delete your branch in the open-source project
This step is optional, as many people don't delete their branches after submission. However, GitHub's recommended best practice is to delete your branch.
To do this, go to your merged PR, and within the "Closed" section, you should find the "Delete branch" button automatically suggested by GitHub.
In sharing this extensive record of my notes, my intention is to encourage everyone to contribute their programming skills and technical expertise to various open-source projects. I hope this information can benefit both you and others in the open-source community.