GitHub contribution workflow for minor or infrequent changes

Important

All repositories that publish to docs.microsoft.com have adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ. Or contact opencode@microsoft.com with any questions or comments.

Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. New or significant changes will generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. We need you to complete the online form before we can accept your pull request.

Overview

This workflow is suitable for making minor or infrequent changes, by using GitHub's web-based Markdown editor. The GitHub editor is limited in terms of what you can do, because the UI does not support all Git operations and authoring scenarios. If you need to make large contributions, or you need support for advanced Git features (such as branch management or advanced merge conflict resolution), refer to the major or long-running changes workflow.

Procedure for using the GitHub editor to propose your changes

  1. Browse to the article's corresponding GitHub repository and Markdown file. You can use either of the following methods:

    • Find the article by browsing through the Markdown files in the related GitHub repository.
    • Go to the article on docs.microsoft.com and select the Edit link in the upper-right corner of the page.

      Location of the Edit link

      Important

      If you are a Microsoft employee and need to work in the private repository, before proceeding to the next step you will need to:

      1. Go to your browser's address bar and change the link to redirect to the private repository. In most cases, this means adding a "-pr" suffix to the repository portion of the URL. For example, "sql-docs" becomes "sql-docs-pr", etc.
      2. If your team requires you to work in a specific branch, make sure the branch portion of the URL is set correctly. You may need to change it to "master', 'live', or a release branch, for example.

      Branch reference in URL

  2. Select the Edit this file pencil icon to go into edit mode:

    Location of the pencil icon

  3. Make changes by using Markdown on the Edit file tab, and preview your changes on the Preview changes tab. Using the editor is fairly straightforward, but if you need assistance, see the following guides:

  4. Scroll to the bottom of the page, where you see one of the following:

    • Propose file change: Appears when you have read-only access to the repository, such as editing files in another user's repository. In this case, GitHub will create a "patch" branch in your fork of the repository (and automatically create a fork if it doesn't exist). After you select Propose file change, a Comparing changes page appears so you can verify your changes. Then select the Create pull request button to submit your changes to the pull request queue, and proceed to the next section.

    • Commit changes: Appears when you have write permissions to a repository, such as editing files in your own repository. In this case, GitHub gives you two options for saving your changes:

      • Commit directly to the <branch-name> branch, where <branch-name> is the name of the branch that you were on when you selected the Edit button. This applies your changes directly to the branch instead of using a pull request. At this point, you're finished!

      • Create a new branch for this commit and start a pull request, which prompts you with a default name to create a new branch. After you select Propose file change, a Comparing changes page appears so you can verify your changes. Then select the Create pull request button to submit your changes to the pull request queue, and proceed to the next section.

Pull request processing

The previous section walked you through the process of submitting proposed changes, by bundling them in a new pull request (PR) that is added to the destination repository's PR queue. A pull request enables GitHub's collaboration model, by asking for the changes from your working branch to be pulled and merged into another branch. In most cases, that other branch is the default/master branch in the main repository.

Validation

Before your pull request can be merged into its destination branch, it might be required to pass through one or more PR validation processes. Validation processes can vary depending on the scope of proposed changes and the rules of the destination repository. After your pull request is submitted, you can expect one or more of the following to happen:

  • Mergeability: A baseline GitHub mergeability test occurs first, to verify whether the proposed changes in your branch are in conflict with the destination branch. If the pull request indicates that this test failed, you must reconcile the content that is causing the merge conflict before processing can continue.
  • CLA: If you are contributing to a public repository and are not a Microsoft employee, depending on the magnitude of the proposed changes, you might be asked to complete a short Contribution License Agreement (CLA) the first time you submit a pull request to that repository. After the CLA step is cleared, your pull request is processed.
  • Labeling: Labels are automatically applied to your pull request, to indicate the state of your pull request as it passes through the validation workflow. For instance, new pull requests might automatically receive the "do-not-merge" label, indicating that the pull request has not yet completed the validation, review, and sign-off steps.
  • Validation and build: Automated checks verify whether your changes pass validation tests. The validation tests might yield warnings or errors, requiring you to make changes to one or more files in your pull request before it can be merged. The validation test results are added as a comment in your pull request for your review, and they might be sent to you in e-mail.
  • Staging: The article pages affected by your changes are automatically deployed to a staging environment for review upon successful validation and build. Preview URLs appear in a PR comment.
  • Auto-merge: The pull request might be automatically merged, if it passes validation testing and certain criteria. In this case, you don't need to take any further action.

Review and sign-off

After all PR processing is completed, you should review the results (PR comments, preview URLs, etc.) to determine if additional changes to its files are required before you sign off for merging. If a PR reviewer has reviewed your pull request, they can also provide feedback via comments if there are outstanding issues/questions to be resolved prior to merge.

Comment automation enables read-level users (users who 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 comments listed in the following table to assign labels, change labels, or close a pull request. 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. This label lets the reviewers in the repo know when a pull request is ready for review/merge. Public and private
#sign-off If a contributor who is not the listed author tries to sign off on a public pull request by using the #sign-off comment, a message is written to the pull request indicating that only the author can assign the label. Public
#hold-off Authors can type #hold-off in a PR comment to remove the ready-to-merge label--in case they change their mind or make a mistake. In the private repo, this assigns the do-not-merge label. Public and private
#please-close Authors can type #please-close in the comment stream to close the pull request if they decide not to have the changes merged. Public

When the pull request is issue-free and signed off, your changes are merged back into the parent branch and the pull request is closed.

Publishing

Remember, your pull request has to be merged by a PR reviewer before the changes can be included in the next scheduled publishing run. Pull requests are normally reviewed/merged in the order of submission. If your pull request requires merging for a specific publishing run, you will need to work with your PR reviewer ahead of time to ensure that merging happens prior to publishing.

After your contributions are approved and merged, the docs.microsoft.com publishing process picks them up. Depending on the team that manages the repository you are contributing to, publishing times can vary. Articles published under the following paths are normally deployed at approximately 10:30 AM and 3:30 PM Pacific Time, Monday-Friday:

It can take up to 45 minutes for articles to appear online after publishing. After your article is published, you can verify your changes at the appropriate URL: http://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

Next steps

  • See Pull request best practices for additional information on the pull request process.

  • Continue to the "Writing essentials" articles to learn more about Markdown, Markdown extensions syntax, and more.