This guidebook is written following the diátaxis “how-to guide” style. And because this document reflects how we work in the Seedcase Project, it is living and constantly evolving. It won’t ever be in a state of “done”.
Pull requests (PRs) are how we propose, review, and discuss changes before they become part of a project on GitHub. In fact, we require that all changes to a repository on GitHub go through a pull request. We use pull requests for several reasons. They:
As the American software developer (and founder of Stack Exchange) Jeff Atwood wrote:
“Peer code reviews are the single biggest thing you can do to improve your code. If you’re not doing code reviews right now with another developer, you’re missing a lot of bugs in your code and cheating yourself out of some key professional development opportunities. As far as I’m concerned, my code isn’t done until I’ve gone over it with a fellow developer.”
This section covers the practices we follow for creating and reviewing pull requests.
To understand pull requests, it helps to first understand branches. When you work on a project in Git, there is a default branch (usually called main) that holds the current, stable version of the project. Instead of making changes directly to main, you create a branch—think of it like making a copy of a document so you can draft changes without touching the original. A branch allows you to work on your changes independently, and, when you are happy with your changes, you propose merging (or adding) them into the project’s main branch. That proposal is called a pull request (PR).
A PR gives your collaborators the opportunity to review your changes, ask questions, and suggest improvements before the changes become part of the project. This review process helps catch mistakes, maintain quality, and keep your collaborators informed about what is changing and why.
The diagram below Figure 3.1 shows this in practice. A person creates a branch called docs/add-pr-guide to work on their changes. The dots represent commits, which are saved snapshots of their work. When ready, they open a PR. After review and approval, their changes are merged back into the main branch of the project.
---
config:
theme: 'forest'
gitGraph:
showCommitLabel: false
---
gitGraph
commit
commit
branch docs/add-pr-guide
checkout docs/add-pr-guide
commit
commit
commit tag:"Make PR"
checkout main
merge docs/add-pr-guide
commit
main via a pull request.
Generally, the PR process follows these steps:
main.main. If not, make further changes, update the PR, and request another review.This workflow is called the GitHub flow and is a widely used and effective collaboration strategy for projects of all sizes.
Before making a PR, you should create a branch to make your changes on. Branch names should be lowercase, use hyphens between words, and follow the format {type}/{short-description}. The type is based on the Conventional Commits types (e.g., docs, fix, feat, refactor). For example:
docs/add-pr-workflow-guidefix/broken-link-in-readmerefactor/update-template-structureWhen you’ve made your changes on a branch, there are a few ways to make a PR. We use two ways: through VS Code and through the GitHub website. Using the GitHub website is a fairly straightforward way of making a PR: You go to the pull request tab of the repository, click the “New pull request” button and follow the instructions there.
Creating a PR through VS Code, however, is usually faster, though it requires some setting up and practice. To be able to create pull requests to GitHub from within VS Code, you need to install the extension GitHub Pull Requests and Issues. You can find and install this extension by going to the Extension view in the left sidebar of VS Code and search for it. Once you have installed it, VS Code will prompt you to link to your GitHub account by signing in and giving access.
Now, you can use the command palette (Ctrl+Shift+P or Cmd+Shift+P) and search for “GitHub: Create Pull Request” to create a pull request from the current branch you are working on. This will open a new pull request form in the sidebar where you can fill out the title, description, and other details of your PR before submitting it. If you’re comfortable with the Terminal, you can also use that from within VS Code to push your changes to GitHub.
Create a pull request when you have a set of changes that are ready for someone else to review. This usually means after you have completed the work on an issue or task, and the changes are in a state where they can be tested and reviewed.
Each pull request should represent a single, focused change. This makes it easier for reviewers to understand the changes and provide meaningful feedback. A small (atomic) PR might be:
Avoid combining unrelated changes into a single PR. If you find yourself writing “and” in your PR description to connect two separate ideas, consider splitting them into separate PRs. Smaller, focused PRs are quicker to review, easier to test, and simpler to revert if something goes wrong.
A good PR description helps reviewers understand the context and purpose of the changes. Our repositories include a pull request template to make it easy to fill out the description when creating a PR. In the description field, aim to cover:
If the PR addresses an existing issue, reference it by writing Closes #<issue-number>, e.g., Closes #2 in the description. This automatically links the PR to the issue and closes the issue when the PR is merged.
Try to keep the description concise but informative. A few sentences that give enough context for someone unfamiliar with the work to understand what you did and why is a good target. The easier it is for a reviewer to understand the PR, the faster and more focused their feedback will be.
Indicate in the description whether the PR needs a quick or thorough review. A quick review might be suitable for small changes like typos, while a thorough review is better for larger or more complex changes.
When you create a PR, you should assign an assignee and request reviewers using the options in the sidebar on the right side of the PR page on GitHub:
template-website, you will automatically be assigned to the PR when you create it.template-website, it will automatically request a review from the team or people listed in the .github/CODEOWNERS file when you create the PR.Setting both ensures that it is clear who owns the PR and who needs to look at it. We’ve set it up so this is done automatically (see our template for how).
Reviewing pull requests is a key part of a collaborative workflow. As outlined in our task priority order, both responding to reviewer comments on your own PRs and reviewing others’ PRs are tasks of the highest priority. Timely reviews keep the work moving and prevent bottlenecks.
When reviewing a PR, focus on providing constructive and actionable feedback. Use GitHub’s suggestion feature to propose specific changes directly in the code or text. This makes it easy for the author to accept your changes with a single click.
To make a suggestion, go to the “Files changed” tab and click the + icon next to a line. Then, either add a comment or make a suggestion. If you want to make a specific suggestion, click the “Add a suggestion” button (a document icon with + and -). This inserts the suggestion syntax into the comment box, where you can write your proposed change. The syntax looks like this:
```suggestion
the corrected or improved text here
```When leaving comments, be specific about what you think should change and why. Avoid vague feedback like “this doesn’t look right” and instead explain what the issue is and how it could be improved.
Sometimes someone else may have made changes to the same files or lines as the changes you’ve made and merged them to main. This will lead to merge conflicts as Git can’t determine what to do with the conflicting changes. Dealing with merge conflicts requires manual editing and resolving.
There are two main ways to resolve merge conflicts:
To handle a merge conflict locally, pull any changes from the remote repository to your local repository by using either git (e.g. git pull origin main) or through VS Code’s Git features. You can use the command palette and search for Git: Pull from and then pull from origin/main. Then, you can resolve the conflicts with the help of VS Code and with manual editing. After you’ve resolved the conflicts, you can push the changes to GitHub to update the PR.
Once a PR is approved, it can be merged into main. Merging is the responsibility of those who have write access to the main branch. GitHub offers several merge strategies (e.g., “Merge commit”, “Squash and merge”, “Rebase and merge”). We typically use “Squash and merge”, which combines all the commits in the PR into a single commit on main. This keeps the commit history clean and focused on the overall change rather than individual commits.
3.3.2 Comment, request changes, or approve
When you finish your review, GitHub gives you three options for submitting it:
If a reviewer requests changes, then you will need to address the feedback, update the PR, and re-request a review by clicking the “Re-request review” button in the right sidebar of the PR page. This back and forth continues until the PR is approved and ready to merge.