Chapter 7: Creating a Pull Request
A pull request is a proposal to change a project.
It combines code, explanation, and communication in a single place.
This guide focuses on creating pull requests that are easy to review and easy to trust.
What a Pull Request Represents
A pull request represents:
- a problem being addressed
- a solution being proposed
- a discussion space
- a request for review
It is not just a code submission.
Opening a Pull Request at the Right Time
Open a pull request when:
- the change is complete
- tests pass
- the scope is clear
- the intent is well defined
Draft pull requests can be used for early feedback if the project supports them.
Choosing the Right Base Branch
Make sure your pull request targets:
- the correct branch
- the branch specified in contribution guidelines
Targeting the wrong branch creates unnecessary work.
Writing a Clear Pull Request Title
A good title:
- is concise
- describes the change
- avoids vague language
Examples:
- “Fix crash when config file is missing”
- “Improve error message for invalid input”
Titles set the tone for review.
Explaining the Context
Start the description by explaining:
- what problem is being solved
- why it matters
- how it affects users or maintainers
Assume the reviewer has not read the full issue history.
Describing the Solution
Clearly describe:
- what was changed
- how the solution works
- any trade-offs or limitations
Avoid unnecessary detail, but do not omit important context.
Linking Related Issues
If the pull request relates to an issue:
- link it explicitly
- reference it in the description
This connects discussion and decision-making.
Following Pull Request Templates
If a template exists:
- follow it
- fill all relevant sections
- remove unused placeholders
Templates exist to help reviewers.
Keeping Pull Requests Focused
A good pull request:
- addresses one concern
- avoids unrelated changes
- keeps diffs readable
Large pull requests are harder to review and slower to merge.
Preparing for Review
Before submitting:
- review your own changes
- check formatting
- re-read the diff
- ensure clarity
Self-review improves review quality.
Understanding Automated Checks
Many projects use automated checks.
These may include:
- tests
- linters
- formatting rules
Failing checks usually block review.
Fix them before asking for feedback.
Being Available After Submission
After opening a pull request:
- monitor notifications
- respond to questions
- clarify when needed
Silence can slow progress.
What You Should Be Able to Do Now
You should now be able to:
- open a clear pull request
- explain your changes effectively
- align with project expectations
- invite constructive review
This is a major step in contributing.
Reflection
Ask yourself:
- Is the problem clear without extra explanation?
- Would this be easy to review?
- Does the change align with project direction?
Clarity reduces friction.
You've Completed Chapter 7
Well done! You've learned about creating a pull request.