Fixes #12841 - Update macOS install docs and move Brew to alternate doc#12842
Conversation
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
There was a problem hiding this comment.
Pull request overview
Updates the installation documentation to address broken macOS Homebrew instructions by moving Homebrew guidance out of the main macOS install article and consolidating “alternate install methods” content.
Changes:
- Updates macOS install instructions to focus on manual pkg/tar and points readers to an alternate methods page.
- Expands/retitles the alternate install methods doc to include macOS Homebrew plus existing Linux alternate methods.
- Updates TOC and adds a redirection entry for the prior Linux alternate install page.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| reference/docs-conceptual/toc.yml | Updates TOC link for “Alternate ways to install on Linux” to point to the new alternate-install-methods doc. |
| reference/docs-conceptual/install/install-powershell-on-macos.md | Removes embedded Homebrew instructions; updates links and guidance; points to alternate-install-methods. |
| reference/docs-conceptual/install/install-powershell-on-linux.md | Renumbers link references (but still links to the old alternate page). |
| reference/docs-conceptual/install/alternate-install-methods.md | Retitles and expands alternate install guidance, adding macOS Homebrew section. |
| redir/.openpublishing.redirection.json | Adds redirect from the old install-other-linux.md path to the new alternate-install-methods page. |
Comments suppressed due to low confidence (4)
reference/docs-conceptual/install/alternate-install-methods.md:74
- Grammar issue: "There are two PowerShell for Linux is published..." should be rewritten (for example, "Two PowerShell snaps are published..."), since the current sentence is ungrammatical.
reference/docs-conceptual/install/alternate-install-methods.md:230 - The link reference section contains duplicate definitions for the same numeric labels (an older block followed by an "updated" block). This can produce incorrect link targets and can fail link/lint validation. Please remove the obsolete block and keep a single, consistent set of link reference definitions.
reference/docs-conceptual/install/install-powershell-on-macos.md:165 - This uninstall guidance only covers pkg/tar installs (rm of /usr/local/...); however, the article also documents installing via .NET Global tool. Please add uninstall instructions for the .NET tool method or clearly scope this section to pkg/tar installs so readers don't apply the rm command incorrectly.
If you manually installed PowerShell 7, you must manually remove it. The following command removes
the symbolic link and PowerShell files.
```sh
sudo rm -rf /usr/local/bin/pwsh /usr/local/microsoft/powershell
reference/docs-conceptual/install/alternate-install-methods.md:12
- The intro states these methods "aren't officially supported by Microsoft", but later sections explicitly describe Microsoft support boundaries (for example, supported Snap channels). This is internally inconsistent; please reword the intro to reflect per-method support status (or remove/adjust the blanket unsupported claim).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Update PowerShell 7 | ||
|
|
||
| Run the following commands to update the installed version of PowerShell to the latest release. | ||
|
|
||
| ```sh | ||
|
|
||
| brew update | ||
| brew upgrade powershell | ||
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > When updating to a newer version of PowerShell, use the same method, cask or the tap, that you | ||
| > used to perform the initial install. If you use a different method, opening a new pwsh session | ||
| > continues to use the older version of PowerShell. | ||
| > | ||
| > If you decide to use different methods, there are ways to correct the issue using the | ||
| > [Homebrew link method][05]. | ||
| To update PowerShell, download the new version of the package or binary archive and install it. |
There was a problem hiding this comment.
The doc includes installation via .NET Global tool, but the "Update PowerShell 7" guidance only mentions downloading a new package/archive. Please either add update instructions for the .NET tool installation method (for example, using dotnet tool update) or clarify that this update section only applies to pkg/tar installs.
|
Learn Build status updates of commit d8f653a: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
Co-authored-by: Copilot <[email protected]>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit c87b88e: ✅ Validation status: passed
For more details, please refer to the build report. |
michaeltlombardi
left a comment
michaeltlombardi
left a comment
There was a problem hiding this comment.
No additional notes not already covered by copilot, content LGTM
|
Learn Build status updates of commit 9dbbdd0:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| reference/docs-conceptual/install/install-powershell-on-linux.md | View (>=powershell-5.1) | Details | |
| redir/.openpublishing.redirection.json | ✅Succeeded | View (>=powershell-5.1) | |
| reference/docs-conceptual/install/alternate-install-methods.md | ✅Succeeded | View (>=powershell-5.1) | |
| reference/docs-conceptual/install/install-other-linux.md | ✅Succeeded | n/a (file deleted or renamed) | |
| reference/docs-conceptual/install/install-powershell-on-macos.md | ✅Succeeded | View (>=powershell-5.1) | |
| reference/docs-conceptual/toc.yml | ✅Succeeded | View (>=powershell-5.1) |
reference/docs-conceptual/install/install-powershell-on-linux.md
- Line 71, Column 18: [Warning: file-not-found - See documentation]
Invalid file link: 'install/alternate-install-methods.md'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
PR Summary
Update macOS install docs and move Brew to alternate doc
PR Checklist