GitHub contribution workflow: 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 as the UI does not support all Git operations and authoring scenarios. If you need to make large contributions, or need support for advanced Git features (such as branching management, advanced merge conflict resolution), please refer to the major or long-running changes workflow.

Using the GitHub editor to propose your changes, step-by-step

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

    • Visit the article on https://docs.microsoft.com/, click the Edit link in the upper-right corner:

      GitHub profile example

    • Find the article by browsing the Markdown files in the related GitHub repository

  2. Click the Edit this file pencil icon in the upper right to go into edit mode:

    GitHub profile example

  3. Make changes 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 will see one of the following:

  • Propose file change - displays 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 click "Propose file change", you will be presented with a "Comparing changes" page, allowing you to verify your changes. Then click the "Create pull request" button to submit your changes to the pull request queue, and proceed to the next section.

  • Commit changes - displays 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 you were on when you clicked the "Edit" button. This applies your changes directly to the branch instead of using a pull request. At this point you are finished!

    • "Create a new branch for this commit and start a pull request", which prompts with a default name to create a new branch. After you click "Propose file change", you will be presented with a "Comparing changes" page, allowing you to verify your changes. Then click 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) which is added to the destination repository's pull request 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, into the default/"master" branch in the main repository.

Validation

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

  • Mergeability: A baseline GitHub mergeability test will occur first, to verify whether the proposed changes in your branch are in conflict with the destination branch. If the PR indicates that this test failed, you must reconcile the content that is causing the merge conflict(s) 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 may be asked to complete a short Contribution License Agreement (CLA) the first time you submit a PR to that repository. Once the CLA step has cleared, your PR will be processed.
  • Labeling: Labels may be automatically applied to your PR, which are used to indicate the state of your PR as it passes through the validation workflow. For instance, new PRs may automatically receive the "do-not-merge" label, indicating that the PR is has not yet completed the validation, review, and sign-off steps.
  • Validation/Build: Your changes may be examined by a series of automated checks to verify whether they pass validation testing. The validation tests may yield warnings/errors, requiring you to make changes to one or more files in your PR before it can be merged. The validation test results will be added as a comment in your PR for your review, and may also be sent to you via e-mail.
  • Staging: The article pages impacted by your changes may automatically be deployed to a staging environment for review upon successful validation and build, with "Preview URLs" made available in a PR comment.
  • Auto-Merge: The PR may be automatically merged, if it passes validation testing and certain criteria. In this case, there is no further action required by you.

Review and sign-off

Once all PR processing has 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 your PR has been reviewed by a PR reviewer, they may also provide feedback via comments if there are outstanding issues/questions to be resolved prior to merge.

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

Once the pull request is issue-free and signed-off, your changes will be merged back into the parent branch and the PR will be closed.

Publishing

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

Once your contributions have been approved and merged, they will be picked up by the Docs.Microsoft.Com publishing process. 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. Once your article has been 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 section to learn more about topics such as Markdown and Markdown extensions syntax, and more.