Open a pull request

A pull request proposes a change to your project so someone can check it before it is merged. This guide takes an already saved branch of website changes and turns it into a clear request with context, test results, and a useful place to start reviewing.

Before you start

• A GitHub account signed in at GitHub.com, with access to the website repository.
• Your change committed and pushed to a separate branch that you can see on GitHub, for example fix/newsletter-validation. If the change exists only on your computer, finish saving and pushing it first.
• Write access to your change branch. If you cannot push to the original repository, use an allowed fork that you own and push your branch there first.
• The intended destination repository and branch, plus the project’s contribution instructions and test commands. Ask the maintainer if you do not know the destination; it is not always main.

Want to do it yourself?

Difficulty

6 out of 10

Estimated completion time

30–60 minutes for a prepared change

Skills you’ll need: Use Git branches, inspect a diff, run checks, and explain the change clearly on GitHub.

I’ll do it myselfI’d rather get help

How this helps your brand

A clear change proposal lets another person check the behavior your customers or team will use. Recording the actual tests and remaining gaps makes website and software updates easier to assess before release.

1. 1

   Step 1: Prepare one reviewable change

   Choose one result to propose. For example: “Reject an empty newsletter email and show a helpful message.” Keep an unrelated home page redesign for another change. A reviewer should be able to explain the purpose in one sentence.

   In the repository on GitHub, choose your branch and use Compare & pull request if the banner is shown. Otherwise, open Pull requests and choose New pull request. Check base, the branch receiving the work, and compare, the branch containing your changes. For a fork, use compare across forks and check the head fork too.

   Read the file comparison before continuing. A diff is the list of lines being added and removed. Check every changed file against the result you chose. If you see unrelated work, return to your editor and prepare a focused branch before opening the request.

   • Run the project’s documented checks against the branch you are proposing and save the command and actual result.
   • Try the normal behavior and one failure case. For the newsletter example, try a valid test email and an empty submission; record what each actually does.
   • Review screenshots, logs, and changed files for private information before including them. Use test data in your evidence.

   Tip: If the comparison is empty or your file is missing, check the selected branches, fork, and whether your latest commit reached GitHub. If they are correct, ask the maintainer to help diagnose the comparison before proceeding.

   Illustrated exampleKeep the change and its proof together

   Sample change · prevent duplicate newsletter sign-ups

   • NewsletterForm.tsxDisable submit while the request is pending.
     Keep
   • NewsletterForm.test.tsxCover double-clicks and a failed request.
     Keep
   • Header.tsxAn accidental logo spacing edit.
     Remove from PR

   Sample verification Double-click → one request Failure → error shown; retry available

2. 2

   Step 2: Explain the change

   Give the request a title that describes its result, such as “Show a message when the newsletter email is empty”. In the description, explain the old behavior, the new behavior, and the reason for changing it. Follow any template supplied by the repository.

   Copy the template at the end of this guide into the description and replace every bracketed field. A useful test note is “Empty submission: message shown, no success message” rather than “Tested the form”. Include the environment you used, such as a local preview in a named browser. Label example results as examples until you have checked them yourself.

   For a visible change, include a screenshot that shows the relevant state. Say where a reviewer should look first and explain any remaining uncertainty. If you could not run a check, name it and explain what is missing. Do not turn an untested assumption into a passing result.

   Tip: Ask for a specific check: “Please check that empty submissions cannot reach the server.” That gives the reviewer a clearer job than “Any thoughts?”.

   Illustrated exampleWrite a description a reviewer can verify

   Example pull request

   Prevent duplicate newsletter submissions

   1 Problem

   A double-click sent two sign-up requests.

   2 New behavior

   Submit stays disabled while sending. A failed request shows an error and allows a retry.

   3 Verification

   Form tests pass for rapid clicks and server failure. Checked pending and error states in the browser.

   1. 1Give the trigger that caused the work.
   2. 2Describe what the user now experiences.
   3. 3Name the checks you actually ran.

3. 3

   Step 3: Help reviewers focus

   Recheck the destination and the description, then choose Create Pull Request when the change is ready for review. If work remains and your repository offers draft pull requests, use the create button’s dropdown to create a draft. Draft availability depends on the repository plan and organization access; if the option is absent, finish the work before submitting it as ready.

   Open the resulting request and check Files changed against your intended scope. Look at configured automated checks, if any; the Checks tab can show their results and logs. A passing check only covers what that check actually ran. If a check fails, read its output, investigate, and update the same change branch with the fix. New commits on that branch update the request.

   With write access to the repository, use Reviewers to request a review from the appropriate collaborator. If you lack that permission, follow the repository’s contribution instructions for getting a maintainer’s attention. Keep the request URL so you can return to feedback and explain any follow-up changes.

   Tip: Opening a pull request proposes a merge. Treat the decision to merge and any site deployment as later steps governed by your project’s process.

   Illustrated exampleCheck where the change is going

   Example destination repository

   northline / website

   Base · receives the changemain

   Propose into base

   Compare · contains your workfix/newsletter-submit

   Opening the pull request proposes this change. It does not merge it.

   Review focusCheck that a failed request releases the pending state.

   Known limitationThis client fix does not deduplicate direct API requests.

Problem: [what happened before, who it affected, and why this change is needed]

Result: [what happens after this change]

Scope: [the relevant files and why they changed]

Verification: [the commands or manual steps you actually ran, environment, and observed results]
Normal case: [input and observed result]
Failure case: [input and observed result]
Not checked: [anything you could not test, why, and who should check it; write none if everything planned was checked]

Please focus the review on: [the important behavior or decision]
Known limitations: [remaining limitations or none]
Related issue: [issue link if applicable, otherwise remove this line]