Dispelling Rumors
A common belief that fairly new open source contributors tend to have is the bigger the pull request, the better. Well, contrary to this belief, bigger is not always better. Sometimes, doing small pull requests to solve an issue, especially ones that are large, is actually better. Feel intimidated? Don’t fret. In this blog post, I will share 5 tips to create effective small pull requests.
Tip #1: Read the issue closely
Whether you’re fixing a bug, or revising outdated tutorials, it’s important to thoroughly read the project’s issue because it’s where you’ll find the problem that needs solving. For example, during the ending week of Hacktoberfest, I stumbled upon the following issue at @yuridevat's project, Yuri’s Coding Club’s Accessibility Mentor:
<bug>: Issue Templates don't appear
#47
Problem
I noticed that when I click on the "New Issue" button, the templates don't appear. This can caused contributors to be confused.
Proposed Solution
According to the little note in the Configuring Template Chooser section of GitHub's Docs, the issue templates will work by by adding a config.yml file to the .github/ISSUE_TEMPLATE folder and setting blank_issues_enabled to false.
Update: I realized that some of the syntax in the issue templates were not correct, so I'm going to redo them an see.
Additional Information
I would like to work on this issue @yuridevat.
### Tasks
- [ ] https://github.com/YurisCodingClub/accessibility-mentor/issues/50
- [ ] https://github.com/YurisCodingClub/accessibility-mentor/issues/51
- [ ] https://github.com/YurisCodingClub/accessibility-mentor/issues/52
</div>
<div class="gh-btn-container"><a class="gh-btn" href="https://github.com/YurisCodingClub/accessibility-mentor/issues/47">View on GitHub</a></div>
I thought it was going to be easy, but then as I read the issue more deeply, I realized that there were specific requirements such as:
- Update the content of the
doc.ymlfile - Update the content of the
feature.ymlfile
At first, I had no idea how to go about fixing this issue. But after taking a deep breath, I decided to create small Pull Requests for each section, so I proposed this idea to the project’s maintainer. After she approved my idea, the question I had then was “Which one should I do first?". This is where the tasklist comes in.
Tip #2: Create a tasklist
Like most things in life, a checklist is needed for taking on big tasks and pull requests are no exception. Here’s how it looks:
Adding this to your Pull Request will help you stay focused as you create your contribution. For example, I clicked on the tasklist, and created a PR form for the docs.yml file. Here's how it looks:
After that, I repeated this process for the feature.yml file:
If you want to learn more about tasklists, check out the article, “Creating a tasklist”. Now, creating a tasklist is only one of the many ways to make effective small Pull Requests. Let’s move onto the next tip.
Tip #3: Link the small Pull Request to its corresponding issue
You know how Mufasa from The Lion King says, “We are all connected in the Circle of Life”? Well, the same concept applies to open source. Small pull requests and their issues are no different. Linking the small pull requests to their corresponding issues makes it easier for maintainers to understand how your contribution would help improve or solve a problem in their project.
After making my Pull requests for each yml file, I went to the Fixes Issues section of each PR form and did the following:
I used specific keywords like “closes” because it ensures that its corresponding issue and checkbox in the main issue form’s tasklist will automatically close:
Tip #4: Create separate branches
As a general open source rule, it’s always best to create separate branches to make Pull Requests. This however, is especially important when creating smaller Pull Requests. For example, I named the branch for my PR for the docs.yml file “revise-docs.yml-file” and “fixing-the-feature.yml-file” for the branch for my feature.yml file PR. As simple as these names are, doing this makes it easier for me and the project’s maintainer to keep track of how the problem is being addressed. Now before you go and start creating small Pull Requests, there’s just one more tip I have for you.
Tip #5: Write specific instructions for merging
Managing the merging process of pull requests is like traffic lights controlling cars and other vehicles. If too many go at once, casualties and accidents occur (or in the case of open source, merge conflicts). To prevent issues like this from happening, it helps to specify when to merge certain pull requests. For example, I put the question “Hi [Maintainer’s name], can you merge this one first before you do the other one?" in the comment section of my PR for the docs.yml file. Doing this not only fosters effective communication but ultimately makes the merging process smoother.
There you have it folks! Five tips on how to create small yet effective pull requests. Doing this would not only help you grow in your open source journey, but prepare you for your tech role. Speaking of journey, if you’re looking for more ways to get started in open source or need a refresher, check out our intro course. Need more practice? Check out these issues in our pizza-verse repository. Also, join our Discord community to learn about other projects to contribute to. We look forward to working with you! 😊
Top comments (2)
Great article, Christine! You did such an amazing job creating PRs!
Aww thanks @yuridevat! :)