Tips for getting your Pull Request reviewed on GitHub

I had a great time working with Hacktoberfest contributors. In my Open Sauced project, we had 14 PRs merged, most of which closed Hacktoberfest labeled issues. There were concerns for small projects and the amount of spam it would attract, but I did not see it. The only PR came in that was explicit spam, and it was October 1st.

Hacktoberfest (my experience)

I have never been great at documentation but learned how valuable the CONTRIBUTING.md was while assisting with some of my previous employer's open-source projects. Having exact steps to contributing can help a lot in getting folks to do so.

My recommendation to all folks looking towards contributing to open source is read the documentation, then write code. If there is a CONTRIBUTING.md, please read it. My contributing guide outlines how to assign yourself to an issue. If someone comments that they would like to work on an issue but has not assigned themselves, it is clear they have not read the guide.

Assigning issues in my project happen through GitHub Actions. This is a task reserved for organization members only, but my Action takes care of that and allows folks to claim issues without waiting on me to respond.

Open an issue

I am a fan of improving the process for new contributors; however, my contributing guide states an open issue is required for PRs to be merged. This is another smoke test for distinguishing which contributors read the guide.

As much as I want to stay cutting edge with my linter, I cannot accept changes to it blindly and without explanation. I have also had poor previous experience with pre-commit hook libraries, but for whatever reason, I get a PR that sneaks in husky once a month. To this day, I have not got a valid reason for adding husky. I have no interest in adding friction to the contribution onboarding experience and need a good explanation of why I need to add new libraries to my codebase.

If you would like to make a change, open an issue to discuss it.

Screenshots, please

I recommend people add screenshots to their PRs if there are visual changes. If you are fixing padding (or something else visual), I need to see a mobile screenshot and desktop view. Also, consider sharing screenshots using different browsers. As much as I love to PR deploy previews, I don't always have the time to stop and QA them. I have sat on PRs for weeks due to other priorities. Use that time waiting to improve the context and add a screenshot.

If you are interested in doing videos of gifs for your content, consider Loom, it has a chrome extension that links your video to your PR.

In summary, provide a visual representation for the change if you made a visual change.

Use the PR template to provide context

A pull request template is a tool that can guide you. It's helped me review the code quickly and understand what's happening.

If I am looking at an opened PR without a description or linked issue, I have to close it. I need context at the time of PR (You can create a draft if you prefer to PR early). My concern is for future contributors who would like to know what happened in the history and debug changes involved with your code. If they view the PR that was merged with no context, no information will be lost. I cannot confidently integrate code without a proper explanation through the documentation.

I don't have the time to explain why this change happened to every new contributor, and I am guaranteed to miss some context. Suppose you don't have the history there for me. Having a description is paramount to getting your PR merge because.

I was able to push back on low or no descriptions with a saved reply. The saved reply is a feature that has been in GitHub for a few years now and allows and me to respond to common questions or concerns with a few clicks.

side note: if there is no template, consider adding one

Describe your change with the SCQA structure

Finally, when you get to the point where you have a PR and provide a description, I always recommend using the format, which is SCQA. I created another video on this idea focused on conference abstracts, but it works with PRs.

This SCQA model was first presented to me by a former engineer manager of mine. He noticed I had trouble getting my PRs reviewed by other team members, and I struggled to explain my changes in a way that would entice my coworkers to stop what they were doing and review. This structure is a debate tactic for convincing others that your argument is sound.

Read more about SCQA hear

The acronym SCQA stands for Situation, Complication, Question, and Answer.

Situation

The Situation should be the opener for your description. For example, if your PR is updating a React version, it could highlight what features are updated in React and how they could benefit the projects.

Complication

The Complication is the opportunity for you to share things that need comments or were difficult to implement. It can also be a place to explain how your change fits or doesn't fit with the current structure of the codebase. This is your opportunity to educate the reviewer and provide context for the documentation to go alongside your change.

Question

The Question seems obvious, but some folks are unsure how to use this. I leverage the Question as the title of my issues if needed, but I also help reiterate the change I am solving. It is possible to include scope creep into a PR unintentionally, and the Question--What does this change do? I can keep you on track in your description.

I also use the Question to get unstuck when using a trick I don't have time to get into now but will in a future post—PR early, even when you are no finished.

Answer

The Answer is meant to describe your change and document your approach. If you skip the previous steps, you cannot skip this -- it is required. Explaining your difference not only helps your reviewers, but it also enables you to discover if your change was necessary or the best approach.

Like and Subscribe

So that summarizes my approach to getting PRs reviewed. If you have these concepts down, I can guarantee a review on your code.

If you are interested in hearing more tips like this, please hit that heart and follow button.

Also, check out my Youtube channel, where I spend time explaining concepts like these in video form.