Skip to content

Comments

Update reference document Copilot review guidelines#29183

Open
isra-fel wants to merge 1 commit intomainfrom
isra-fel-patch-2
Open

Update reference document Copilot review guidelines#29183
isra-fel wants to merge 1 commit intomainfrom
isra-fel-patch-2

Conversation

@isra-fel
Copy link
Member

Description

Added guideline for handling -ProgressAction parameter.
There's a limitation in v0.x of PlatyPS that could not handle the -ProgressAction parameter 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

  • SHOULD update ChangeLog.md file(s) appropriately
    • Update src/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.
      • A snippet outlining the change(s) made in the PR should be written under the ## Upcoming Release header in the past tense.
    • Should not change ChangeLog.md if no new release is required, such as fixing test case only.
  • SHOULD regenerate markdown help files if there is cmdlet API change. Instruction
  • SHOULD have proper test coverage for changes in pull request.
  • SHOULD NOT adjust version of module manually in pull request

Added guideline for handling -ProgressAction parameter.
Copilot AI review requested due to automatic review settings February 18, 2026 15:41
@azure-client-tools-bot-prd
Copy link

Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.md instructing reviewers to allow/ignore placeholder descriptions for the -ProgressAction parameter 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.
Copy link

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Suggested change
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.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants