Pull request submission best practices

To publish changes to content, you submit a pull request from your fork. Pull request submission and processing is covered in both the minor/infrequent changes and the major/long-running changes workflows.

Every pull request has to be reviewed prior to being merged. Read this article to understand how you should work with pull request reviewers and how you can create pull requests that are easier and faster to review so the pull request queue works better for everyone.

Working with pull request reviewers

Pull requests are commonly put through a technical or content quality review, or both, in order to ensure complete quality.

Pull request technical quality review

Some teams require technical review of pull request content before it can move to the content quality review and merge stage. If your team implements technical review, you will likely receive an invitation and link to the PR to provide your feedback. The feedback mechanisms used to review and update the PR vary, depending on the the tool being used. Please work with your technical review team for more specifics.

Pull request content quality review

Here are the basics you need to know about working with reviewers during the content quality review process.

  • Understand the role of the content quality reviewer. The reviewer:

    • Ensures the basic quality of the content
    • Prevents regressions in the repository
    • Provides feedback before merging

    Content quality reviewers are in a content governance role. The primary intent is not to simply merge whatever is submitted as quickly as possible. Expect feedback that will require you to make updates, especially for new and heavily revised articles. The content quality reviewer is also responsible for the final step of merging the pull request, after it passes all content quality criteria.

  • Plan ahead with your pull request reviewer:

    • For high-priority pull requests
    • Pull requests for timed/dated releases
    • Pull requests that change or add lots of files
  • Pull requests may take a few days to be merged

While content quality reviewers try to review/merge PRs at least twice daily, they all have other work to do, and some of that work might be higher priority than reviewing pull requests.

Make the pull request queue work better for everyone

There are two basic realities in the PR queue:

  • Pull requests that are small in scope and that contain very similar changes take less time to review.
  • Pull requests that are large in scope or that contain different, mixed kinds of changes take more time to review.

You can help make the pull request queue work better by following these best practices:

  • Separate minor updates to existing articles from new articles or major rewrites. Work on these changes in separate working branches.

  • When you delete articles or images, don't mix the deletions with new content additions or updates. Handle the changes/new content in a separate working branch.

  • If you are a Microsoft employee:

    • Contact your pull request reviewer to expedite PRs only when absolutely necessary. You can request expedited PR handling for Red Zone, privacy, legal, and security issues; for truly broken customer experiences; and for executive escalations.

    • For releases or refactoring of content, plan ahead with your PR reviewer. You may need his or her help to create a release branch or to coordinate merge times with publishing times so your content is published at the right time.

    • If you are trying to coordinate updates made by others out-of-band with changes you are making, which are interdependent, you must coordinate that work ahead of time with your PR reviewer. Otherwise, you risk having a lot of broken links.

In a hurry? Submit PRs that can be accepted automatically (Microsoft Employees)

If your repository supports it, use the PRMerger automation rules to get more of your day-to-day PRs merged automatically.

PRMerger can accept your PR automatically, if:

  • It affects 10 files or fewer.
  • It contains 15 commits or fewer.
  • Less than 20% of text changes.
  • Selectors/switchers aren't updated.
  • No files are deleted or added.
  • No images are new, changed, or deleted.

Need to make a lot of little changes?

Take your cue from the PRMerger automation rules above, and do the following:

  • Submit articles with light changes together in a PR with 10 or fewer files.
  • Create a separate PR for articles in which images or selectors change. This requires human review.
  • Create a separate PR for new or deleted articles. This requires human review.