Guidelines for responding to public pull requests

Contributions to Docs content can enter into our publishing workflow through two different channels:

  • Private repositories - Internal contributors should enter through our private repositories (ie: those with a "-pr" suffix). These contributors have read-only permissions to our private repositories, and typically create a fork of the repository, then clone their fork, before creating a pull request. These contributors are typically making large contributions, which require a more thorough review process. Review includes automated validation and staging when commits are pushed to their Pull Request (PR), plus thorough review of larger pull requests by a skilled reviewer.
  • Public repositories - External contributors enter through our public repositories. These contributors also have read-only permission, and typically use the GitHub UI to make edits and create a fork/branch, but may also submit from a local clone of their fork. The PR process they are subjected to also takes care of Common License Agreement (CLA) validation, and tends to be lighter weight with no validation/build/staging occurring in the pull request.

The focus of this article is on the latter public/external contributors.

Customer etiquette

A certain amount of etiquette should be employed when working with external contributors. These contributors are usually Microsoft partners and customers, and in some cases other Microsoft employees that don't fit into a role of "trusted" internal contributor. A "trusted" internal contributor is a writer or engineering PM/dev who is a subject matter expert (SME), and has assigned contribution responsibilities to the subject area.

Note

If you are seeing pull requests come through your public repositories from Microsoft employees that are trusted contributors, you should encourage them to become an internal contributor. This is mainly because internal repositories typically offer better quality enabled thorough automated validation and preview features, especially for large contributions.

Some things to keep in mind as you engage with an external contributor on content that you are responsible for:

  • Consider customer contributions a huge favor. When a customer goes to the trouble of taking time/energy to make a contribution, no matter how small, we need to be grateful to them. We not only need to thank them, but we (especially if you are the owner of the article) need to ensure that they know we appreciate their effort by acknowledging their contribution and incorporating it into the content source repo.
  • Play an active role in getting the PR merged Make sure you contribute to the process by providing the necessary review of any content that you own. There are no hard rules here, but please follow a reasonable SLA when processing these PRs. Do not allow them to sit idle in the PR. This not only sends a bad message to our customers/partners, but it also subjects the PR to possible merge conflicts the longer it remains unmerged.

  • Never close an external PR without communicating first to the contributor - it's perfectly valid to have a situation where you need to close a PR. But please do not close it until you've notified the contributor through the PR comments on why you need to close.

  • Do not be tempted to close the PR and incorporate later through your own PR This is another practice that sends a very bad message to our customers/partners. It also nullifies their contribution in terms of GitHub statistics and file commit history.

PR review/merge process

Open Publishing Services (OPS) repositories may have varying levels of automation incorporated. Below is the current list of organizations that manage OPS public repositories, and the related automation, which drives the PR review/merge process.

Cloud and Enterprise (C+E) repositories

Comment automation enables read-level users (users that don't have write permissions in a repo) to perform a write-level action, by assigning the appropriate label to a pull request. If you are working in a repository where comment automation has been implemented, use the hashtag comment listed in the following table to assign labels to let the reviewers in your repo know when a PR is ready for review/merge, to change the label status of a PR, or to close a PR. Microsoft employees will also be notified via e-mail for review and #sign-off of public repository PRs, whenever changes are proposed to articles for which you are the author.

Hashtag comment What it does Repo availability
#sign-off When the author of an article types the #sign-off comment in the comment stream, the ready-to-merge label is assigned. Public and private
#sign-off If a contributor who is NOT the listed author tries to sign off on a public pull request using the #sign-off comment, a message is written to the pull request indicating the label can be assigned only by the author. Public
#hold-off If you type #hold-off in a pull request comment, it removes the ready-to-merge label - in case you change your mind or make a mistake. In the private repo, this assigns the do-not-merge label. Public and private
#please-close Authors can type the #please-close comment in the comment stream of a pull request to close it if you decide not to have the changes merged. Public

Below is the typical lifecycle of an external pull request, and the integrated automation triggered by hashtag comments:

  1. Pull request is created by contributor. All C+E repositories have integrated CLA validation, which may require the contributor to pass CLA approval before continuing. The appropriate PR labels will be assigned to the PR accordingly.

    For non-Microsoft employees, if the contribution meets a size threshold verification, an existing CLA will be confirmed (cla-already-signed label), or a request for a new CLA will be initiated via email (cla-required label).

    For Microsoft employees this requirement is waived (cla-not-required label).

  2. After CLA approval, the contributor will receive an automated "thank you", and the article owner will be notified (Change sent to author label).

  3. The article author is encouraged to communicate with external contributors via the PR comments. At a bare minimum, please be sure to thank them for their contributions, but also use this as a way to get clarification or make suggestions. After the article author has reviewed/approved the PR, a #sign-off comment should be placed in the PR comments. This will trigger the application of the ready-to-merge label.

    Note

    Public repo sign off automation allows ONLY the article author to sign off.

    • Article authors: To use the public repository comment automation, your actual GitHub account must EXACTLY match the GitHub account listed in the article metadata. The capitalization of your account matters. If you are blocked from signing off due to this problem, send an email to the azdocprs alias.
    • Other employees: If you are an employee who is signing off on behalf of the author, you will be prevented from sign-off and a comment is written to the pull request indicating such. If you need help, contact azdocprs with the pull request link. Indicate who you are -- PMs on the same product team, colleagues on the writing team, and writing team managers are considered trusted sources.
  4. Twice daily, the centralized PR review team will monitor the public repo queues for PRs that are ready to be merged. The criteria used to determine PRs that are ready to merge includes:
    • The PR has received #sign-off by the article author
    • The PR has been assigned the "ready-to-merge" label

Finding open pull requests

To find open pull requests for your articles, use one of the following methods:

  • Use the SkyEye Search, searching by your alias or service/product name to get a summary of open pull requests from customers.
  • Use the Pull Requests PowerBI report, filtering by author or service to find the respective open pull requests.

Additional resources

  • Typically, the same review team that services internal PRs can provide PR queue management for our external PRs. As such, please review Pull request etiquette and best practices as many of the same principles apply to collaborating with the review team on external PRs.
  • In general, external PRs should be processed as quickly as possible. It's also a best practice to have someone monitor and report regularly on the status of PRs, which have a Change sent to author label but no ready-to-merge label. The report can show color coding of PRs by age, ie:

    • PRs that are 1-7 days old are green
    • PRs that are 8-14 days old are yellow
    • PRs that are 15 days old or more are red