Skip to content
OrionHub Developer tooling and cloud development
Section
open-source
Kind
Editorial
Reading time
4 min
Updated
8 September 2026

What Maintainers Actually Want: First Contributions That Get Merged

A first contribution to an open-source project is most likely to be merged when it is small, single-purpose, and written in the terms of the project, not the contributor’s.

Keeping Changes Small and Focused

Smaller, focused changes are easier for busy maintainers to understand and integrate..

Contributing something small and isolated helps reviewers quickly grasp the scope and intent of your changes. Ideally, the contributor takes on a bugfix or a specific feature at a time [2][3][10][11]. According to GitHub, it’s best to break large code changes into a sequence of smaller, dependent pull requests that can be reviewed and merged independently [3]. One contributor guide explicitly says to submit one pull request per bugfix or feature, so as not to overwhelm reviewers [10].

The guide also warns that enormous pull requests take enormous amounts of time to review and may even be rejected altogether [12]. Hence, a stretched-out pull request is like a job candidate who plays their entire resume as the opening instrument before making their pitch: the reviewer is left with the work of sifting through too much.

Explain the Purpose

Maintainers need to understand immediately what a pull request will accomplish. It’s not enough to fix a bug or resolve a ticket; the reviewer needs to see that, in the submission process, a clearer understanding of the change emerges [5][13]. The pull request body should state the purpose of the change, provide a high-level overview of what’s been updated, and link to any relevant tracking issues or prior conversations [4][5]. Pull request descriptions should reference which issue the changes will close in the first paragraph [1].

The goal is to make seeing what’s happening a quick visual juxtaposition of what was, what is, and why. To a maintainer, a good pull request provides clear context and purpose. Whereas the pull request that says everything in reference links and leaves substrate for deduction comes across like surveillance footage with cutbacks to the presenter’s home movie with a soundtrack of nothing but ominous string music.

Let Reviewers In Early, with Clarity

Drawn-out pull request evolutions are anathema to maintainers who have community-wide support demands. That’s why a draft pull request can be a very useful tool..

A draft PR, which GitHub specifies, shares incomplete changes in the repository without formally requesting review [6][7]. It can be a way to show they’re still in progress, making it a critical tool for potential feedback and suggesting productive approaches..

Diverging evolution of a PR ends in a review of a final version where multiple iterations of the work have been interwoven. This is relatively easy for smaller contributions, but can quickly become difficult to tease out with larger contributions. Multiple developers might push changes in sequence that fundamentally alter the logic, layout, and even the request for including the change from the initial commit. It becomes a tangled set of changes that only the original contributor may fully understand. This is one reason it increases nascent contributor attrition. A contributor who keeps their pull request isolated makes it easier to review and merge.

Conservative First Contributions Have the Least Headaches for Reviewers

If a first pull request is doing the minimum, it will avoid the process headaches that can dispose of perfectly viable contributions.

GitHub recommends building, testing, and reviewing one’s own pull request to sort out issues.. Reviewers may find bugs that contributors missed.

Relatedly, ensuring a well-documented change means early reporting on why specific problems were fixed or features were included. Getting cues from a maintainer’s current documentation style ensures that they are looking at conclusions that anticipate how the change will contribute to the project, rather than documentation you think implements what was originally intended without considering how the project uses it.

The common failure modes in pull requests are oversized changes, intervening warts in unrelated code that make the overview difficult to focus on, and poor communication around the scope and intent of the change.

For example, the guide notes changes unrelated to the original pull are rarely approved, especially at any preliminary stages. It states that you should keep them isolated to pertinent changes [11].

Oversized changes can slow down reviews and frustrate maintainers. It catches the flaws in my code that I missed until you sent that email saying, “Hey! Don’t forget that next iteration.” As others pull in what they can, you get the bump you wanted. When they see your docs following style rules, they move on your changes.

Write like the Existing Project

Excess formality in a first PR can be counterproductive. Start with an overview explaining the motivation, and explain the changes after you close your high level discussion, then point to the links and repository background. Doing this will warm up reviewers to see that you recognize the work is not a task, it’s a contribution.

So rather than quoting unfamiliar material, stay within the project-style code. Use the same language as the community’s documentation, chats, and even their code comments. If you’ve contributed by following up on a ticket, referencing that ticket shows you followed through, but adding a link helps reviewers know they don’t have to google your reference. Instead, they can ensure they’re looking at the specifics you did.

In that spirit, conclude that while a great pull request requires focus on scope, purpose, and communications, conforming to the pre-existing norms ensures they can see the change through from beginning to end. In 10 lines I hope you remember it should stay small and separated, clear and context-sensitive, and fair to norms or they’ll toss your change back without a glance.