In this article

↑ Back to top

Creating a Pull Request

After you’ve set up your development environment, you’re probably itching to write some code! Your natural instinct when creating a new feature will likely be to create a local feature branch, and start building away. If you start doing this, stop, take your hands off the keyboard, grab a hot chocolate, and read on.

It’s important to break your feature down into small pieces first. This means you should take time scoping the feature, with each piece becoming its own bite-sized pull request (commonly referred to as a “PR”).

Once you’ve planned things out and are ready to start coding, here’s what to do:

1. Create a new branch

Create a new branch with a descriptive name that accurately reflects what changes are being made.

2. Add a changelog entry

Run jetpack changelogger add to add a changelog file with the expected changes, and commit the change. This is required to push a branch to the repo.

3. Push

Push the branch.

4. Open a pull request

  • Prefix the title with the section of the product, e.g.Sharing: add new Facebook button. Don’t stress over a perfect title; this can be changed later.
  • Write a detailed description of the problem you are solving, the part of Jetpack it affects, and how you plan on going about solving it. Fill out all applicable sections of the pull request template.
  • If you have write access, add the [Status] In Progress label. This indicates that the pull request isn’t ready for a review and may still be incomplete, but also welcomes early feedback and encourages collaboration during the development process.

5. Commit your changes

Start developing and pushing out commits to your new branch. Some tips:

  • Push your changes out frequently and try to avoid getting stuck in a long-running branch or a merge nightmare.
  • Smaller changes are much easier to review and address potential conflicts. If unexpected additional changes come up during the implementation, consider adjusting your scope and splitting the planned work into smaller parts. Our goal is to catch early in the review process those pull requests that attempt to do too much.
  • Don’t be afraid to change, squash, and rearrange commits, or even to force push (e.g. git push --force-with-lease origin fix/something-broken). Keep in mind, however, that if other people are committing on the same branch this can mess up their history. You are perfectly safe if you are the only one pushing commits to that branch.

6. Respect the standards

Remember to respect Coding Standards. Failure to adhere to these standards will trigger test failures that block merges. If you have Composer installed, you can run composer install and then composer phpcs:lint [directory or files updated] to check your changes against WordPress coding standards.

7. Pre-review checklist

When you feel that the pull request is ready for a formal review, go through this list:

  • Ensure each project that was touched includes a changelog entry.
  • Make sure all required checks listed at the bottom of the pull request are passing.
  • Make sure there are no merge conflicts listed in the pull request, and consider rebasing against trunk to keep the branch history short and clean.
  • If there are visual changes, add before and after screenshots in the pull request comments.
  • Add unit tests, or at a minimum, provide helpful instructions for the reviewer so they can test your changes. This will help speed up the review process.

8. Highlight critical changes

If your PR contains important changes and needs to be included in the next release, let us know! You can do so in the PR description, or in a comment on that PR. If you have the permissions, you can also add the [Pri] Blocker label to the PR.

9. Ask for review

Indicate that the PR is ready for review:

  • If you have write access and are on a Jetpack team, remove the [Status] In Progress label, add the [Status] Needs Team Review label, and assign your team as a reviewer. Someone on your team will then provide feedback on the latest unreviewed changes.
  • If you have write access and are on a non-Jetpack team, remove the [Status] In Progress label and add the general [Status] Needs Review label, and a triage team will route this to a relevant team for review.
  • If you don’t have write access, leave a comment stating that it’s ready for review, and a triage team will route this to the relevant team for review. You might also ping a committer you’ve been working with or the last few people to make significant changes to that part of the code.

10. Merge

Once the pull request is approved and has a [Status] Ready To Merge label, the pull request is ready to be merged into trunk. Congratulations!