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.