Pull requests

This guide will walk you through the process of creating, reviewing, and approving pull requests (PRs). It covers the following topics:

1. How to create a PR

This section defines guidelines for PRs.

Branch naming
- Convention: initials/description
- Example: aa/replace-button-title
PR names: To make it easier to skim commit history, name the PR with
- Convention: team: short but precise description of the change
- Example: search: update repo filter to be faster
Team labels: Apply a team label to the PR so that the associated team can easily find PRs.
- Example: team/search
Include the why in the description: The PR should include not just what the change is but why the change is necessary.
- Even if there is a linked issue, include at least a tl;dr in the PR description.
- Why? Often we have detailed context discussions in Slack. Documenting the key takeaways in a PR description (or a doc linked to from the PR description) makes it faster and more reliable to understand why the change was made. Plus, the play-by-play in a Slack conversation is often less useful than a direct, thoughtful summary.
- (Remember that Slack is not a source of truth and eventually goes away.)
Link the PR and the issue: Provides context for for future readers.
- If the PR is a result of a GitHub issue, include “Closes #12345” in the PR’s description in order to auto-close the related issue once the PR is merged.
- If the PR is a result of a Linear issue, you must enable linking from the issue. Choose one of these options:
  - Autolink: Click the first indicated icon and say “Closes <issueID>” in the PR description
  - Magic branch: Click the second indicated icon which will create a magic branch name which handles autolinking.
  - If you're the author of a PR you can put the issue name in the branch.
    - Example: aa/<issue number>/<description of pr>
Approvals: Defer merging a PR until at least one person has approved of the changes.

Suggested but not required:

Visual changes: If the PR makes a visual change to the UI (ex: changing the text of a button), include a screenshot or a video of it in the PR so that a reviewer knows exactly where to focus when looking at the change.
Self-assignment: Assign the PR to yourself so it is easier to find from search and also easy to switch assignee if need be.