Pull request submission best practices

To publish changes to content, you submit a pull request from your fork. Pull request submission and processing are covered in both the minor/infrequent changes and 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.

Work with pull request reviewers

Pull requests commonly go through a technical quality review or a content quality review, or both, to ensure complete quality.

Technical quality review

Some teams require a technical review of pull request content before it can move to the content quality review and merge stage. If your team implements a 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 tool being used. Please work with your technical review team for specifics.

Content quality review

Here are the basics that 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.
    • For pull requests for timed/dated releases.
    • For pull requests that change or add lots of files.
  • Pull requests may take a few days to be merged

    Although content quality reviewers try to review/merge PRs at least twice daily, they all have other work to do. 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 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 content additions or updates. Handle the additions and updates in a separate working branch.

  • If you are a Microsoft employee:

    • Contact your PR reviewer to expedite pull requests 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 out-of-band dates made by others 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 percent 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 preceding PRMerger automation rules, 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.