Edit

Share via

Managing pull requests

  • Article

This article documents how we manage pull requests in the PowerShell-Docs repository. This article is designed to be a job aid for members of the PowerShell-Docs team. We publish this information here to provide process transparency for our public contributors.

Best practices

  • Request a review. The person submitting the PR shouldn't merge the PR without a peer review.
  • Assign the peer reviewer when the PR is submitted. Early assignment allows the reviewer to respond sooner with editorial remarks.
  • Use comments to describe the nature of the change being submitted. For example, if the change is minor, explain the change and that you don't need a full technical review. Be sure to @mention the reviewer.
  • Use the comment suggestion feature to make it easier for the author to accept the suggested change. For more information, see Reviewing proposed changes in a pull request.

PR Process steps

  1. Writer: Create PR
    • Fill out the PR template
    • Link any issues resolved by the PR
    • Use GitHub's autoclose feature to close the issue
    • Work through and check off each item in the checklist
  2. Writer: Assign peer reviewer
  3. Reviewer: proofreads and comments (as necessary)
  4. Writer: Incorporate review feedback
  5. Both: Review preview rendering
  6. Both: Review validation report - fix warnings and errors
  7. Reviewer: Mark review "Approved"
  8. Repo Maintainer: Merge PR

Content Reviewer Checklist

See the editorial checklist for a more comprehensive list.

  • Proofread for grammar, style, concision, technical accuracy
  • Ensure examples still apply for the target version
  • Check Preview rendering
  • Check metadata - ms.date, remove ms.assetid, ensure required fields
  • Validate markdown correctness
    • See style guide for content-specific formatting rules
  • Reorganize examples as follows:
    • Intro paragraph
    • Code and output
    • Detailed explanation of code (as necessary)
  • Check hyperlinks for accuracy
    • Replace or remove TechNet/MSDN links
    • Ensure minimum number of redirects to target
    • Ensure HTTPS
    • Correct link type
      • File links for local files
      • URL links for files outside of the docset
    • Remove locales from URLs
    • Simplify URLs pointing to learn.microsoft.com
  • Verify versioned content is correct across all versions

Branch Merge Process

The main branch is the only branch that should be merged into live. Merges from short-lived (working) branches should be squashed before merging into main.

Merge from/to release-branch main live
working-branch squash and merge squash and merge Not allowed
release-branch — merge Not allowed
main rebase — merge

PR Merger checklist

  • Content review complete
  • Correct target branch for the change
  • No merge conflicts
  • All validation and build step pass
    • Warnings and suggestions should be fixed (see Notes for exceptions)
    • No broken links
    • The Checklist action ran and passed
    • If an Authorization check was triggered, it passed
  • Merge according to table

Notes

The following warnings can be ignored:

Can't find service name for `<version>/<modulepath>/About/About.md`

Metadata with following name(s) are not allowed to be set in YAML header, or as file level
metadata in docfx.json, or as global metadata in docfx.json: `locale`. They are generated by
Docs platform, so the values set in these 3 places will be ignored. Please remove them from all
3 places to resolve the warning.

When a PR is merged, the HEAD of the target branch is changed. Any open PRs that were based on the previous HEAD are now outdated. A Maintainer has the right required to override the merge warnings and merge the outdated PR in GitHub. Merging an outdated PR is safe if the previously merged PRs didn't touch the same files.

To update the PR, select the Update Branch button. Choose Update with rebase option. For more information, see Updating your pull request branch.

Publishing to Live

Periodically, the changes accumulated in the main branch need to be published to the live website.

  • The main branch is merged to live each weekday at 3pm PST.
  • The main branch should be merged to live after any significant change.
    • Changes to 50 or more files
    • After merging a release branch
    • Changes to repo or docset configurations (docfx.json, OPS configs, build scripts, etc.)
    • Changes to the redirection file
    • Changes to the TOC
    • After merging a "project" branch (content reorg, bulk update, etc.)