You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/agents/computePR.agent.md
+64-5Lines changed: 64 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,6 +49,9 @@ You are an engineering assistant helping Azure PowerShell contributors update or
49
49
1)**Changelog**
50
50
-`src/Compute/Compute/ChangeLog.md`
51
51
- Describe customer-visible changes (new parameter, behavior change, etc.).
52
+
- Keep entries concise - prefer a single, clear sentence per change.
53
+
- Focus on the user-facing impact: what changed and what the user can now do.
54
+
- Do not explain service-side decisions, internal implementation details, or backend logic - users only care about the cmdlet behavior they observe.
52
55
2)**Model Class** (Swagger mapping)
53
56
-`src/Compute/Compute/Models/<model>.cs`
54
57
- Add/adjust properties to represent the API schema.
@@ -60,18 +63,74 @@ You are an engineering assistant helping Azure PowerShell contributors update or
60
63
-`src/Compute/Compute/help/<command>.md`
61
64
- Regenerate using the module's help script: Update-MarkdownHelp -Path ./src/Compute/Compute/help/New-AzVM.md -AlphabeticParamsOrder -UseFullTypeName
62
65
- Ensure examples cover new parameters.
63
-
- New parameters should go at the end of the parameter list.
64
-
5)**Tests**
66
+
- Parameter ordering differs between the two sections of the help doc:
67
+
- In the `SYNTAX` section, add new parameters to the end of the parameter list, but before the common parameters (`-DefaultProfile`, `-WhatIf`, `-Confirm`, and `<CommonParameters>`).
68
+
- In the `PARAMETERS` section, place each new parameter in alphabetical order along with the rest of the parameters (`-Confirm` and `-WhatIf` stay at the end).
69
+
- See `src/Compute/Compute/help/New-AzDiskConfig.md` for an example of this ordering.
70
+
-**New commands only:** add the new cmdlet to the module landing page `src/Compute/Compute/help/Az.Compute.md`. Insert it in alphabetical order using the format `### [<Command>](<Command>.md)` followed by a line with the cmdlet's synopsis. Existing commands that only change parameters do not need an entry here.
71
+
5)**Module Manifest** (new commands only)
72
+
-`src/Compute/Compute/Az.Compute.psd1`
73
+
- Add the new cmdlet to the appropriate export list in alphabetical order: `CmdletsToExport` for C# cmdlets, or `FunctionsToExport` for function-based cmdlets.
74
+
- Match the existing style (single-quoted, comma-separated entries). Existing commands that only change parameters do not need an entry here.
- C# test reference: `src/Compute/Compute.Test/ScenarioTests/<resourceTests>.cs`
67
-
- Add cases for: presence/absence of the new parameter, parameter set routing, validation, and expected side effects. Use existing tests for reference on how to create new tests.
68
-
- Always create a new test instead of modifying existing tests.
78
+
- Every new `.ps1` scenario function MUST be wired into the `.cs` file as a `[Fact]` with `[Trait(Category.AcceptanceType, Category.CheckIn)]` that calls `TestRunner.RunTestScript("<Test-Name>")`. A `.ps1` function with no matching `.cs` entry never runs.
79
+
- Prefer creating new test functions instead of modifying existing tests.
80
+
81
+
## Do not stop at the happy path — enumerate the full test matrix
82
+
A single "it works" test is not sufficient. Before writing tests, list every new parameter and make sure the scenarios below are all covered. Parameters do not each need their own test — parameters that are part of the same feature can be exercised together in one test that walks through several combinations. Add separate tests only when scenarios can't reasonably share setup or would be clearer apart. What matters is that every scenario below is covered, not the number of tests:
83
+
84
+
-**Parameter coverage & combinations** — exercise each new parameter, both on its own and combined with the others when they can be used together (e.g., `-ParamA` alone, `-ParamB` alone, and `-ParamA -ParamB` together). Assert the resulting state for each combination. These can live in one test or several.
85
+
-**Every affected cmdlet** — if the feature touches multiple cmdlets (e.g., a `New-Az*` and its matching `Update-Az*`), cover the scenarios on each cmdlet, not just one. If the feature adds a new property to a `Get-*` cmdlet's output object, treat that `Get-*` as an affected cmdlet too: call it and assert the new property is populated with the expected value.
86
+
-**State transitions / merge semantics (Update)** — Update usually merges with existing state. Test that adding one thing preserves the others (e.g., setting one property on a resource that already has another set leaves both in place), not just create-from-scratch.
87
+
-**Removal / disable paths** — if the feature adds ways to remove or disable something (e.g., a `-Remove*` or `-Disable*` parameter), test each removal individually, combined removal, and removing everything (assert the property becomes null/empty).
88
+
-**Negative & edge cases** — mutually exclusive parameters used together should error (use `Assert-ThrowsContains` / `Assert-Throws`); explicitly passing `$null`/empty values should follow the cmdlet's validation attributes (many `string[]` params use `[ValidateNotNullOrEmpty]`, so `$null`/empty should throw); absence of the parameter should leave behavior unchanged.
89
+
90
+
## Set up real prerequisites — don't skip hard scenarios
91
+
Do not omit a scenario just because it needs supporting resources. If a parameter takes a resource id or reference to another resource, create that prerequisite inside the test (via the appropriate cmdlet, or `Invoke-AzRestMethod` when a cmdlet isn't available) and tear it down in `finally`. Skipping a scenario because its input is harder to set up is the most common coverage gap.
92
+
93
+
## Assert deeply, not just the top-level result
94
+
Verify the specific sub-properties the feature introduces, not only that an object is returned or its top-level type:
95
+
- Assert the concrete type/enum value the feature sets.
96
+
- Assert collection counts and membership (e.g., a returned collection's `.Count` and that it `ContainsKey`/contains the expected entries).
97
+
- Assert related computed or server-populated fields (fields the service fills in as a result of the change).
98
+
- After the mutation, always re-read the resource with a separate `Get-*` call and re-assert the values, to confirm the state persisted server-side (not just that it was echoed back by the create/update call).
99
+
100
+
## Structure each test
101
+
- Wrap the body in `try { ... } finally { Remove-AzResourceGroup -Name $rgname -Force -ErrorAction SilentlyContinue }` so resources are always cleaned up.
102
+
- Add a `<# .SYNOPSIS #>` header describing exactly which scenario the test covers.
103
+
- Use step comments (`# Step 1: ...`) for multi-stage tests (create → update → verify → remove).
104
+
- Use existing tests for reference on helpers (`Get-ComputeTestResourceName`, `Get-ComputeVMLocation`) and assertion style.
69
105
70
106
# Quality & Safety Checklist (enforce before finalizing)
71
107
- Cmdlet attribute matches `<Verb>-Az<Noun>` and correct parameter sets.
72
108
- New/changed parameters have clear `Parameter` metadata (sets, `Mandatory`, `HelpMessage` if applicable).
73
109
-`ExecuteCmdlet()` routes correctly; Default vs non-default paths updated.
74
110
-`IsParameterBound` used to detect passed values; no reliance on null for "not provided".
75
111
- Help regenerated and examples verified.
76
-
- Scenario tests cover success/failure paths.
112
+
- Scenario tests cover the **full matrix**, not just the happy path: each new parameter exercised alone and in combination (which may be within a single test), every affected cmdlet, Update merge semantics, removal/disable paths, and negative/edge cases (mutually exclusive params error, explicit `$null`/empty inputs validated per `[ValidateNotNullOrEmpty]` or other validation attributes).
113
+
- Test assertions verify concrete sub-properties (enum/type value, collection counts and membership, computed fields) and re-read the resource with a follow-up `Get-*` call to confirm the values persisted, not just that a non-null object was returned.
114
+
- Every new `.ps1` scenario function is wired into the `.cs` file as a `[Fact]` check-in test.
77
115
-`ChangeLog.md` describes changes simply, similar to existing changelog descriptions.
116
+
117
+
# Pull Request Description
118
+
- When opening the pull request, write a short summary of the changes, then end the description with a manual verification checklist.
119
+
- The checklist helps the developer confirm every necessary change was made, in case the AI missed something.
120
+
- Use GitHub markdown checkboxes (`- [ ]`) and leave every box **unchecked** so the developer can check them off manually after reviewing.
121
+
- Cover each required artifact and quality gate. Tailor items to the specific change and include at least the following:
122
+
-**This verification checklist is NOT your internal progress/task tracker.** If you track implementation progress in the PR body while working, that is a separate list. When you finalize the PR body (e.g., replacing the working notes with a `## Changes` summary), you MUST re-add the `## Verification Checklist` section as the **last** section of the final description, with every box left **unchecked**. Never let the final body-overwrite drop the verification checklist — the completed PR description must always contain both the change summary and the unchecked verification checklist.
123
+
124
+
```markdown
125
+
## Verification Checklist
126
+
-[ ] Cmdlet implementation updated with the new/changed parameter(s)
127
+
-[ ] Model class updated to represent the API schema.
128
+
-[ ] Help content regenerated: new parameter appears in the `SYNTAX` section and in alphabetical order in the `PARAMETERS` section.
129
+
-[ ] Examples updated to cover the new parameter(s).
130
+
-[ ] If adding a new command, add it to the help/Az.Compute.md file
131
+
-[ ] If adding a new command, register it in `Az.Compute.psd1` (`CmdletsToExport`, alphabetical order).
132
+
-[ ] New scenario tests cover the full matrix: each new parameter exercised alone and in combination (may share a single test), every affected cmdlet, Update merge semantics, removal/disable paths, and negative/edge cases (mutually exclusive params; `$null`/empty inputs validated per `[ValidateNotNullOrEmpty]` or other validation attributes).
133
+
-[ ] Test assertions check concrete sub-properties (type/enum, collection counts and membership, computed fields) and re-read the resource with a follow-up `Get-*` call to confirm the values persisted.
134
+
-[ ] Every new `.ps1` scenario function is wired into the `.cs` file as a `[Fact]` check-in test.
135
+
-[ ]`ChangeLog.md` updated with a concise, user-focused entry under `## Upcoming Release`.
0 commit comments