Update reference document Copilot review guidelines#29183
Update reference document Copilot review guidelines#29183
Conversation
Added guideline for handling -ProgressAction parameter.
| Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status. |
There was a problem hiding this comment.
Pull request overview
This PR adds a guideline to the Copilot review instructions to prevent automated review comments about -ProgressAction parameter placeholders in PowerShell help documentation. The change addresses a known limitation in PlatyPS v0.x tooling where the -ProgressAction parameter generates placeholder descriptions that are automatically removed during the build process.
Changes:
- Added guideline #2 to
.github/instructions/reference-doc.instructions.mdinstructing reviewers to allow/ignore placeholder descriptions for the-ProgressActionparameter in help markdown files
| When writing reference documents for PowerShell cmdlets, please follow these guidelines to ensure readability and helpfulness: | ||
|
|
||
| 1. **Avoid over-simplified description** - For parameters and cmdlets, avoid over-simplified description such as "Some help", or simply repeating the parameter name. | ||
| 2. **Allow placeholders for -ProgressAction** - there's a limitation in the tooling that the `-ProgressAction` parameter will have a placeholder description in the documents, e.g. `{{ Fill ProgressAction Description }}`. This is expected so do not leave review comments on that. |
There was a problem hiding this comment.
The wording "Allow placeholders for -ProgressAction" could be misleading. The actual behavior is that the build tooling (Remove-CommonParameterFromMarkdown in tools/BuildScripts/HelpMarkDown.psm1) automatically REMOVES the entire ProgressAction parameter section from help files during the build process. Consider revising to more accurately reflect that these placeholders are temporary and will be automatically removed, for example: "Ignore placeholders for -ProgressAction in PRs - the build tooling automatically removes this parameter section before release" or "Do not comment on -ProgressAction placeholders - they are automatically removed during the build process".
| 2. **Allow placeholders for -ProgressAction** - there's a limitation in the tooling that the `-ProgressAction` parameter will have a placeholder description in the documents, e.g. `{{ Fill ProgressAction Description }}`. This is expected so do not leave review comments on that. | |
| 2. **Ignore placeholders for -ProgressAction in PRs** - temporary placeholder descriptions for the `-ProgressAction` parameter (for example, `{{ Fill ProgressAction Description }}`) are expected, and the build tooling automatically removes this entire parameter section before release, so do not leave review comments on them. |
Description
Added guideline for handling -ProgressAction parameter.
There's a limitation in v0.x of PlatyPS that could not handle the
-ProgressActionparameter and leaves a placeholder.We've added tools to handle that as part of the release process, so it doesn't make sense for copilot to leave review comments like this: https://github.com/Azure/azure-powershell/pull/29123/changes#r2747019780
Mandatory Checklist
Please choose the target release of Azure PowerShell. (⚠️ Target release is a different concept from API readiness. Please click below links for details.)
Check this box to confirm: I have read the Submitting Changes section of
CONTRIBUTING.mdand reviewed the following information:ChangeLog.mdfile(s) appropriatelysrc/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.## Upcoming Releaseheader in the past tense.ChangeLog.mdif no new release is required, such as fixing test case only.