How Pull Requests Work

A pull request is a proposal to merge changes from one branch or fork into another branch. It gives maintainers and contributors a place to review code, discuss intent, run checks, request changes, approve work, and decide whether the change belongs in the project.

Different platforms use different names. GitHub uses pull requests. GitLab uses merge requests. The workflow is similar: a contributor proposes a change, the project reviews it, automated checks run, and maintainers decide how or whether to merge.

The pull-request lifecycle

Most pull requests move through the same broad stages:

1. A contributor creates a branch or fork.
2. The contributor makes commits for one focused change.
3. The contributor opens a pull request against the target branch.
4. Automated checks run, such as tests, builds, formatting, or linting.
5. Maintainers and reviewers discuss the change.
6. The contributor updates the branch if changes are requested.
7. A maintainer approves, merges, closes, or defers the request.

The expected outcome is not always a merge. A pull request can reveal a design issue, duplicate work, missing tests, a better solution, or a change that does not fit the project.

Branches and forks

A branch is a separate line of work inside a repository. A fork is a separate copy of a repository, often under a contributor's account or organization. Open source projects commonly accept work from forks because contributors may not have write access to the main repository.

Branches and forks make review safer. The proposed change can be tested and discussed before it affects the main branch. Maintainers can also compare the proposed code against the target branch and see exactly what would change.

For small projects, contributors may use a short-lived branch with a simple pull request. Larger projects may require forks, signed commits, issue links, release branches, or special review rules.

What belongs in a good pull request

A good pull request is focused enough to review. It should explain why the change exists, what it changes, how it was tested, and whether it affects documentation, compatibility, performance, security, or user behavior.

Useful pull request descriptions include:

• a short summary of the change;
• the issue, bug report, or feature request it relates to;
• screenshots or output when the change affects the interface;
• test commands or checks run by the contributor;
• migration, compatibility, or release-note notes when relevant;
• known tradeoffs or incomplete follow-up work.

Avoid combining unrelated work. A pull request that fixes a typo, changes formatting, rewrites an API, and adds a feature is harder to review and more likely to stall.

Review, checks, and discussion

Automated checks can catch build failures, style problems, missing tests, and some regressions. They do not replace human review. Maintainers still need to judge scope, design fit, maintainability, security implications, user impact, and whether the project can support the change over time.

Discussion should stay attached to the specific change. Review comments can ask for clarification, request tests, suggest simpler code, point out compatibility risk, or explain why the change does not fit. Contributors can respond, update commits, or explain constraints.

Healthy pull-request discussion is specific and actionable. "This needs tests for the import error path" is more useful than "not good enough."

Merge methods

Platforms may support several merge methods, and projects choose based on history style and release needs.

No merge method is universally best. A project should document its preferred method so contributors understand how their commits will appear after merge.

Contributor responsibilities

Contributors help maintainers by keeping pull requests small, explaining context, following the contribution guide, responding to review, and updating the change when tests fail.

Before opening a pull request, check:

• the target branch is correct;
• the change matches an issue or documented need;
• tests or examples cover the important behavior;
• documentation is updated when user behavior changes;
• unrelated formatting or refactoring is not mixed in;
• sensitive data, secrets, or generated noise are absent.

If a pull request becomes too large, split it into smaller pieces where possible. Smaller reviews are easier to understand and safer to merge.

Maintainer responsibilities

Maintainers decide whether a pull request fits the project. They also protect project quality, security, release timing, and contributor experience.

Good maintainer responses explain what is needed next. That might be a test, a design change, a smaller scope, documentation, a linked issue, or a clear reason for closure. If a project cannot review large changes quickly, the contribution guide should say so.

Maintainers do not need to accept every correct patch. A change can be technically valid and still outside the project scope, too costly to maintain, or poorly timed for the release cycle.

Common blockers

A pull request is successful when it reaches a clear decision. Merge is one good outcome, but so is a respectful close when the project cannot take the change.