Edit

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. It's published here to provide process transparency for our public contributors.

Best practices

  • 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. Be sure to @mention the reviewer. For example, if the change is minor and you don't need a full technical review, explain this in a comment.
  • Reviewers should use the comment suggestion feature, when appropriate, 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 Admin: Merge PR (see below for criteria)

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 sentence(s)
    • 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's merged into live. Merges from short-lived (working) branches should be squashed.

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. The outdated PR can be merged using Admin rights to override the merge warnings in GitHub. This is safe to do if the previously merged PRs haven't touched the same files. Clicking the Update Branch button is the safest option. 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.)