Skip to content

Commit 34af15a

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
committed
feat: add Process-PSModule v8 upgrade skill
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 5ce33d7 commit 34af15a

4 files changed

Lines changed: 196 additions & 4 deletions

File tree

‎.github/plugin/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,10 @@ copilot plugin install PSModule/Process-PSModule:.github/plugin/psmodule
2424
The plugin provides the
2525
[`psmodule-pester-migration`](./psmodule/skills/psmodule-pester-migration/SKILL.md)
2626
skill for migrating every Pester test set in a PSModule repository to Pester
27-
6.1.0. Verify the installation with:
27+
6.1.0, and the
28+
[`psmodule-v8-upgrade`](./psmodule/skills/psmodule-v8-upgrade/SKILL.md)
29+
skill for upgrading Process-PSModule consumer repositories to framework v8.
30+
Verify the installation with:
2831

2932
```console
3033
copilot plugin list

‎.github/plugin/marketplace.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@
66
},
77
"metadata": {
88
"description": "Agent plugins for the PSModule repository process.",
9-
"version": "1.0.0"
9+
"version": "1.1.0"
1010
},
1111
"plugins": [
1212
{
1313
"name": "psmodule",
1414
"description": "PSModule process guidance and reusable skills for PowerShell module repositories.",
15-
"version": "1.0.0",
15+
"version": "1.1.0",
1616
"source": ".github/plugin/psmodule"
1717
}
1818
]

‎.github/plugin/psmodule/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
33
"name": "psmodule",
44
"description": "PSModule process guidance and reusable skills for PowerShell module repositories.",
5-
"version": "1.0.0",
5+
"version": "1.1.0",
66
"author": {
77
"name": "PSModule",
88
"url": "https://github.com/PSModule"

‎.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
name: psmodule-v8-upgrade
3+
description: Upgrade a Process-PSModule consumer repository to framework version 8 while preserving repository intent, enforcing the caller workflow contract, migrating Pester tests to v6, and retaining the repository's Zensical documentation design.
4+
---
5+
6+
# Upgrade a Process-PSModule consumer to v8
7+
8+
Use this skill when a consumer repository needs to move its
9+
`Process-PSModule.yml` caller to `PSModule/Process-PSModule/.github/workflows/workflow.yml@v8`.
10+
Keep the change limited to the requested framework upgrade. Do not migrate
11+
consumer repositories while developing or validating this skill.
12+
13+
## Operating contract
14+
15+
1. Inspect the consumer repository before editing. Read its local guidance,
16+
workflow, documentation configuration and content, tests, settings,
17+
dependencies, and existing validation commands.
18+
2. Work on a dedicated branch, open a draft pull request early, and use small
19+
commits. Include the required Copilot co-author trailer in every commit.
20+
3. Preserve test intent, fixtures, secrets, variables, documentation content,
21+
custom theme assets, and repository-owned automation unless the upgrade
22+
requires a direct change.
23+
4. Report preserved TestData, Pester migration details, Zensical/theme changes,
24+
validation results, and blockers in the pull request.
25+
26+
Use the repository's applicable MSX workflow and PR format guidance. Do not
27+
silently broaden the scope when the consumer has unrelated failures.
28+
29+
## Caller workflow contract
30+
31+
Replace `.github/workflows/Process-PSModule.yml` with exactly this template:
32+
33+
```yaml
34+
name: Process-PSModule
35+
36+
on:
37+
workflow_dispatch:
38+
schedule:
39+
- cron: '0 0 * * *'
40+
push:
41+
branches:
42+
- main
43+
pull_request:
44+
branches:
45+
- main
46+
types:
47+
- closed
48+
- opened
49+
- reopened
50+
- synchronize
51+
- labeled
52+
- unlabeled
53+
54+
concurrency:
55+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
56+
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
57+
58+
permissions: {}
59+
60+
jobs:
61+
Process-PSModule:
62+
permissions:
63+
contents: read
64+
pages: write
65+
id-token: write
66+
uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
67+
secrets:
68+
PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
69+
GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
70+
GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
71+
```
72+
73+
The only permitted variation is an optional `TestData` entry under
74+
`jobs.Process-PSModule.secrets`. Do not add `with:` inputs, extra jobs,
75+
conditions, schedule changes, `run-name`, permission changes, trigger changes,
76+
concurrency changes, debug options, or version overrides. Repository-owned
77+
automation belongs in separate workflow files.
78+
79+
### TestData preservation
80+
81+
First determine whether the current caller passes secrets or variables to the
82+
framework. Preserve a required payload by translating it to this compact JSON
83+
shape:
84+
85+
```yaml
86+
TestData: >-
87+
{"secrets":{"SERVICE_TOKEN":"SERVICE_TOKEN"},"variables":{"ENVIRONMENT":"production"}}
88+
```
89+
90+
Include only the `secrets` and/or `variables` maps that the consumer uses. Keep
91+
the existing names and semantics. Omit `TestData` entirely when the repository
92+
does not use it. Never move secrets into source files, workflow `env`, or
93+
committed settings.
94+
95+
## Documentation integration
96+
97+
Treat `docs/zensical.toml` as authoritative. Do not create or maintain
98+
`mkdocs.yml`, introduce MkDocs configuration, or replace the consumer's
99+
documentation design with a parallel theme.
100+
101+
Compare the consumer's configuration with the Process-PSModule template and
102+
preserve or migrate these surfaces deliberately:
103+
104+
- `docs/zensical.toml`, including `docs_dir` and navigation.
105+
- `docs/content/` as the documentation source directory.
106+
- `docs/overrides/` and custom templates.
107+
- `docs/overrides/assets/stylesheets/navigation.css`.
108+
- `docs/assets/`, logo, favicon, palette, fonts, and custom JavaScript/CSS.
109+
- Existing navigation labels, page paths, and custom theme behavior.
110+
111+
Do not delete existing custom CSS/assets merely because the default theme also
112+
provides an equivalent feature. Resolve duplicate configuration in favor of
113+
the existing consumer source of truth, then validate the generated site.
114+
115+
## Pester v6 migration
116+
117+
The framework upgrade does not permit leaving tests on an undeclared or
118+
unsupported Pester version. Inspect module requirements, dependency manifests,
119+
local setup, CI installation, and every test entry point. Declare and run the
120+
repository's supported Pester 6 dependency.
121+
122+
Rewrite tests using native Pester v6 terminology and APIs:
123+
124+
- Prefer `New-PesterConfiguration` and
125+
`Invoke-Pester -Configuration`.
126+
- Update discovery, run configuration, output, result, and coverage handling
127+
without changing test intent.
128+
- Make each test file safe under Pester v6 per-file discovery and execution.
129+
- Preserve explicit fixture ownership and loading; do not silently import the
130+
target module as a fallback for a broken framework setup.
131+
- Keep setup and teardown deterministic and scoped.
132+
- Preserve data-driven cases, mocks, pending behavior, names, tags, coverage,
133+
and result reporting while applying the v6 compatibility rules.
134+
135+
Do not merely rename commands. Run the migrated tests with the declared Pester
136+
6 dependency and investigate failures as migration or repository issues.
137+
138+
## Repository integration inventory
139+
140+
Before editing, record the current state and the intended v8 result for:
141+
142+
| Surface | Inspect | Required result |
143+
| --- | --- | --- |
144+
| Caller workflow | Triggers, permissions, concurrency, secrets, `with:` inputs | Exact v8 contract; only documented `TestData` may vary |
145+
| TestData | Secret and variable names and consumers | Explicit compact JSON maps, or omitted when unused |
146+
| Pester dependency | `#Requires`, manifests, install steps, lock files | Pester 6 is declared and installed consistently |
147+
| Pester configuration | `Invoke-Pester`, output, result, coverage | Native configuration object and v6-compatible output |
148+
| Test setup | Before/After blocks, module load, fixtures, services | Explicit ownership and deterministic per-file behavior |
149+
| Documentation | Zensical config, content, overrides, assets | Existing Zensical design remains authoritative |
150+
| Repository automation | Other workflows and scripts | Unrelated automation remains separate and unchanged |
151+
| Validation | Existing tests, lint, site build, workflow checks | Existing repository-native validation is rerun |
152+
153+
## Validation
154+
155+
Run the smallest existing checks that cover the changed surfaces, then escalate
156+
when a targeted check reveals a broader dependency:
157+
158+
1. Validate YAML syntax and confirm the caller has no forbidden variation.
159+
2. Run the existing Process-PSModule workflow or its repository-native
160+
equivalent when available.
161+
3. Run the Pester v6 test suites with the repository's declared configuration.
162+
4. Run the repository's existing lint and test commands.
163+
5. When documentation exists, run:
164+
165+
```powershell
166+
Push-Location docs
167+
zensical build --clean
168+
Pop-Location
169+
```
170+
171+
6. Review the diff for accidental workflow permissions, trigger changes,
172+
secret exposure, fixture removal, generated files, or unrelated refactoring.
173+
174+
Report commands and outcomes, including blocked checks and why they were
175+
blocked. A green documentation build does not substitute for Pester or
176+
workflow validation.
177+
178+
## References
179+
180+
- [PSModule repository standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/repository-standard.md)
181+
- [PSModule workflow inputs](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/workflow-inputs.md)
182+
- [PSModule pipeline stages](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/pipeline-stages.md)
183+
- [PSModule module test guidance](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/guides/writing-module-tests.md)
184+
- [PSModule workflow and test data guidance](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/guides/calling-the-workflow.md)
185+
- [Zensical setup basics](https://zensical.org/docs/setup/basics/)
186+
- [Pester v6 quick start](https://pester.dev/docs/v6/quick-start)
187+
- [Pester `New-PesterConfiguration` command](https://pester.dev/docs/commands/New-PesterConfiguration)
188+
- [Pester `Invoke-Pester` command](https://pester.dev/docs/commands/Invoke-Pester)
189+
- [MSX PR format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/)

0 commit comments

Comments
 (0)