Skip to content

Build-PolicyDocumentation produces non-deterministic parameter ordering causing excessive wiki diff noise #1284

@oWretch

Description

@oWretch

Describe the bug

Build-PolicyDocumentation iterates policy parameters using $parameters.Keys
(unordered hashtable/PSCustomObject enumeration) without sorting. PowerShell does
not guarantee a stable key enumeration order across runs, so the generated markdown
shuffles parameter entries within table cells each time the command runs — even when
the underlying policy configuration has not changed.

This produces large, noisy wiki diffs on every scheduled documentation run, making
it very difficult to identify genuine changes.

To Reproduce

  1. Run Build-PolicyDocumentation against any EPAC environment that includes
    policies with multiple non-effect parameters (e.g. Guest Configuration or
    Kubernetes policies).
  2. Run Build-PolicyDocumentation again without making any configuration changes.
  3. Diff the two output files — parameter entries within table cells will appear in
    a different order between runs.

Expected behavior

Parameters within each table cell should be emitted in a consistent, deterministic
order (e.g. alphabetical by parameter name) so the markdown output is stable across
runs and the wiki diff only reflects genuine policy changes.

Screenshots

Actual wiki diff showing the same Kubernetes policy row with parameters reordered —
zero real change:

- | Kubernetes | **Kubernetes cluster containers CPU and memory resource limits...** | memoryAndCPULimitsInKubernetesClusterLa... = **`{}`**<br/>excludedImagesInKubernetesCluster = **`[]`**<br/>CPUInKubernetesClusterLimit = **`32`**<br/>memoryInKubernetesClusterLimit = **`64Gi`** |
+ | Kubernetes | **Kubernetes cluster containers CPU and memory resource limits...** | excludedImagesInKubernetesCluster = **`[]`**<br/>memoryInKubernetesClusterLimit = **`64Gi`**<br/>CPUInKubernetesClusterLimit = **`32`**<br/>memoryAndCPULimitsInKubernetesClusterLa... = **`{}`** |

Suggested fix

Sort the keys before iterating — a one-line change in each affected location:

- foreach ($parameterName in $parameters.Keys) {
+ foreach ($parameterName in ($parameters.Keys | Sort-Object)) {

Affected files

File Line
Scripts/Helpers/Out-DocumentationForPolicySets.ps1 169
Scripts/Helpers/Out-DocumentationForPolicyAssignments.ps1 406
Scripts/Helpers/Convert-PolicyResourcesDetailsToFlatList-Documentation.ps1 249, 478

EPAC Version

11.3.1

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions