Update internal PowerShell script documentation#1993
Conversation
microsoft-github-policy-service
bot
added
Micro PR 🔬
microsoft-github-policy-service
bot
added
the
Skill: DevOps
There was a problem hiding this comment.
Pull request overview
Updates comment-based help and script documentation under src/scripts so Get-Help output and the scripts README better match the actual PowerShell parameters supported by the build/publish tooling.
Changes:
- Expanded
.PARAMETERdocumentation for several scripts (added missing parameters; removed non-existent ones). - Cleaned up wording/typos and reordered help sections for more accurate
Get-Helpoutput. - Updated
src/scripts/README.mdparameter table forPublish-Toolkit.ps1.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/scripts/README.md | Updates Publish-Toolkit parameter table to reflect current params and descriptions. |
| src/scripts/Publish-Toolkit.ps1 | Aligns comment-based help with actual params (adds AppInsightsRepo/DocsRepo, fixes wording, notes Branch alias). |
| src/scripts/Build-Bicep.ps1 | Adjusts Module parameter documentation and removes the documented Debug parameter. |
| src/scripts/Build-Workbook.ps1 | Moves/updates parameter help content and removes documented Debug parameter. |
| src/scripts/Invoke-Task.ps1 | Adds missing version-related parameter docs and removes the documented Silent parameter. |
| src/scripts/New-Directory.ps1 | Adds missing Path parameter documentation and fixes indentation/formatting. |
| src/scripts/Build-Toolkit.ps1 | Adds missing version-related parameter docs. |
| src/scripts/Build-PowerBI.ps1 | Fixes parameter names in help (no leading dashes) and clarifies optionality. |
| ## 🚚 Publish-Toolkit | ||
|
|
||
| [Publish-Toolkit.ps1](./Publish-Toolkit.ps1) publishes a toolkit template, module, or documentation to its destination repo. | ||
|
|
||
| | Parameter | Description | | ||
| | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | | ||
| | `‑Template` | Name of the template or module to publish. Default = * (all templates). | | ||
| | `‑QuickstartRepo` | Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates. | | ||
| | `‑RegistryRepo` | Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules. | | ||
| | `‑Build` | Optional. Indicates whether the the Build-Toolkit command should be executed first. Default = false. | | ||
| | `‑Branch` | Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Default = false. | | ||
| | Parameter | Description | | ||
| | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `‑Template` | Optional. Name of the template or module to publish. Default = * (all templates). | | ||
| | `‑QuickstartRepo` | Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates. | | ||
| | `‑RegistryRepo` | Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules. | | ||
| | `‑AppInsightsRepo` | Optional. Name of the folder where the Application Insights Workbooks repo is cloned. Default = Application-Insights-Workbooks. | | ||
| | `‑DocsRepo` | Optional. Name of the folder where the Partner Center documentation repo is cloned. Default = partner-center-pr. | | ||
| | `‑Build` | Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false. | | ||
| | `‑Branch` | Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Alias: Commit. Default = false. | |
There was a problem hiding this comment.
PR description indicates no changelog entry is needed, but repo guidance requires documenting every change in docs-mslearn/toolkit/changelog.md (see .github/copilot-instructions.md). Please add a brief entry (likely under the next release section) noting the internal PowerShell help/documentation updates.
| .PARAMETER Workbook | ||
| Optional. Name of the workbook folder to build. | ||
|
|
There was a problem hiding this comment.
.PARAMETER Workbook is documented as optional, but $Workbook has no default and is used to build paths like $outDir/$srcDir; running without it will either fail or produce unintended paths. Update the help text to mark it as required (or implement a safe default/"build all" behavior).
|
|
||
| .PARAMETER Task | ||
| Required. Name of the task to execute. | ||
| Optional. Name of the task to execute. |
There was a problem hiding this comment.
Task is documented as optional, but the script is effectively a no-op unless $Task is provided (if ($Task) { ... }). Consider marking it as required in help (or explicitly stating that omitting it results in no action / prints usage).
| Optional. Name of the task to execute. | |
| Required. Name of the task to execute. |
| Optional. Increments the prerelease version number (0.0.0-ooo.x). | ||
|
|
||
| .PARAMETER Label | ||
| Optional. Indicates the label to use for prerelease versions. Allowed: dev, alpha, preview. |
There was a problem hiding this comment.
Label help text omits rc, but Build-Toolkit passes -Label through to Update-Version.ps1, which allows dev, rc, alpha, preview. Update the allowed-values list here to match Update-Version to avoid misleading Get-Help output.
| Optional. Indicates the label to use for prerelease versions. Allowed: dev, alpha, preview. | |
| Optional. Indicates the label to use for prerelease versions. Allowed: dev, rc, alpha, preview. |
| .PARAMETER Module | ||
| Path to the module to build. | ||
| Optional. Name of the module to build. Default = * (all modules). | ||
|
|
There was a problem hiding this comment.
The help text removed the .PARAMETER Debug section, but the script still documents usage of -Debug in an example later in the same help block and uses $DebugPreference to drive debug behavior. Either re-add the Debug parameter documentation and make the script an advanced script ([CmdletBinding()]) so -Debug works, or remove the -Debug example/behavior to keep Get-Help consistent.
2 participants
🛠️ Description
Updated inline
.PARAMETERdocumentation in PowerShell scripts to match actual parameters. This ensuresGet-Helpoutput is accurate and consistent across all scripts.Changes
Publish-Toolkit.ps1AppInsightsRepoandDocsRepoparams; fixed "the the" typo; added alias note for BranchBuild-Bicep.ps1Debugparam that doesn't exist; clarifiedModuledescriptionBuild-Workbook.ps1.PARAMETERorder (should come before.EXAMPLE); removed nonexistentDebugparamInvoke-Task.ps1Major,Minor,Patch,Prerelease,Label,Version); removedSilentparam that doesn't existNew-Directory.ps1Pathparam; fixed indentation formattingBuild-Toolkit.ps1Major,Minor,Patch,Prerelease,Label)Build-PowerBI.ps1-KQL→KQL,-Storage→Storage); added "Optional." prefixREADME.md📋 Checklist
🔬 How did you test this change?
🙋♀️ Do any of the following that apply?
📑 Did you update
docs/changelog.md?📖 Did you update documentation?
🤖 Generated with Claude Code