Skip to content

Commit 29a5780

Browse files
chore: sync PowerShell standards 2.0.0 (#58)
Co-authored-by: fadwen <110697945+fadwen@users.noreply.github.com>
1 parent 2756e5f commit 29a5780

7 files changed

Lines changed: 73 additions & 9 deletions

File tree

‎.agents/skills/powershell-new-module/SKILL.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
2222
if the module defines a class. Do not create empty folders for things the module does not have.
2323
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
2424
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
25-
by name. Take `Author` and the project links from the user or the repository; leave out what you do
26-
not know.
25+
by name. Take `Author`, `CompanyName`, and the copyright holder from
26+
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
27+
the user or the repository; leave out what you do not know.
2728
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
2829
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
2930
`Public` dot-sourced in that order, failing the import if a file fails to load.

‎.claude/skills/powershell-new-module/SKILL.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
2222
if the module defines a class. Do not create empty folders for things the module does not have.
2323
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
2424
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
25-
by name. Take `Author` and the project links from the user or the repository; leave out what you do
26-
not know.
25+
by name. Take `Author`, `CompanyName`, and the copyright holder from
26+
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
27+
the user or the repository; leave out what you do not know.
2728
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
2829
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
2930
`Public` dot-sourced in that order, failing the import if a file fails to load.

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -168,7 +168,7 @@ counts as much as one listed here.
168168
- **DOC-05** Help MUST describe what the code does. Performance figures, compliance claims, and
169169
behaviour that the code does not have MUST NOT be invented. If a fact is not known, leave it out.
170170
- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is
171-
added only when the user supplies one.
171+
added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18).
172172

173173
## Function template
174174

‎.github/instructions/powershell-help.instructions.md‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ in `.github/instructions/powershell-platyps.instructions.md`.
2929
- **DOC-06** `.OUTPUTS` names the same type as `[OutputType()]`. `.INPUTS` names the type that can be
3030
piped in, or says `None`.
3131
- **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is
32-
added only when the user supplies one.
32+
added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18).
3333
- **DOC-08** Each `.EXAMPLE` starts with a command that runs as written, followed by a blank line and
3434
a sentence saying what it does. An explanatory line placed before that blank line MUST start with
3535
`#` and MUST NOT be the first line.
@@ -55,11 +55,16 @@ in `.github/instructions/powershell-platyps.instructions.md`.
5555
A `DURATION:` line is added only for a time that was measured.
5656
- **DOC-15** `.NOTES` holds security considerations (permissions and data handling), performance
5757
characteristics, and known limitations with their workarounds. It holds the author's name, blog,
58-
and LinkedIn address only when the user supplies them (DOC-07).
58+
LinkedIn address, and other profiles only when the user supplies them or the project's
59+
attribution file lists them (DOC-07, DOC-18).
5960
- **DOC-16** List references with one `.LINK` keyword for each: related commands, the online
6061
documentation of the command, and Microsoft documentation.
6162
- **DOC-17** Where they have been measured, help documents typical execution time, memory use, and
6263
scalability. It states no performance figure that was not measured (DOC-05).
64+
- **DOC-18** When the project has `.github/powershell-attribution.md`, take the author details from
65+
it: the `AUTHOR:` lines of `.NOTES` in new help, and the manifest keys of MOD-03. Use each line
66+
that has a value, with its label, in the file's order. A line without a value is left out and
67+
MUST NOT be filled in from anywhere else. Existing help is not changed only to add the details.
6368

6469
### Comments
6570

@@ -219,6 +224,39 @@ Test-Connection
219224
Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help` keeps these lines and the blank
220225
lines between them, and lists each `.LINK` as one related link.
221226

227+
**DOC-18.** The attribution file is a list of labelled lines that the project fills in:
228+
229+
```markdown
230+
- Author: Alex Example
231+
- Company:
232+
- Copyright holder: Alex Example
233+
- Blog: https://blog.example.com
234+
- LinkedIn: https://www.linkedin.com/in/alex-example
235+
```
236+
237+
New help then ends its `.NOTES` with the lines that have a value. `Company` is empty, so it is left
238+
out; `Copyright holder` belongs to the manifest only:
239+
240+
```powershell
241+
<#
242+
.NOTES
243+
KNOWN LIMITATIONS:
244+
- Computers must be reachable through WinRM.
245+
246+
AUTHOR:
247+
- Author: Alex Example
248+
- Blog: https://blog.example.com
249+
- LinkedIn: https://www.linkedin.com/in/alex-example
250+
#>
251+
```
252+
253+
Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help -Full` shows the `AUTHOR:` block as
254+
written, after the other notes.
255+
256+
The standards installer creates the file when it is missing and never changes it afterwards. It
257+
starts from the profile of the project's GitHub owner when the standards repository has one, and
258+
from an empty template otherwise.
259+
222260
**DOC-20.**
223261

224262
```powershell

‎.github/instructions/powershell-modules.instructions.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,11 @@ GUID, and it never changes afterwards. Set `Author`, `CompanyName`, `Copyright`,
132132
`Tags` from what the user or the repository provides; do not invent them. Write the copyright year
133133
as a literal: `'(c) $(Get-Date -Format yyyy) ...'` stays that literal text too.
134134

135+
When the project has `.github/powershell-attribution.md` (DOC-18), `Author` is its `Author` line,
136+
`CompanyName` its `Company` line, and the holder in `Copyright` its `Copyright holder` line. Leave
137+
out `CompanyName` when that line is empty, and name the author as the holder when the
138+
`Copyright holder` line is empty.
139+
135140
Leave out `HelpInfoURI` unless the project publishes updatable help at that address: `Update-Help`
136141
reports an error against a `HelpInfoURI` that has no `HelpInfo.xml` behind it. Shipping compiled
137142
help in `en-US/` does not need the key. Leave out `IconUri` when there is no icon (MOD-13).

‎.github/powershell-attribution.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Attribution
2+
3+
Coding agents that follow the PowerShell standards read this file when they write an author into
4+
new code: the `.NOTES` of comment-based help and of help Markdown, and the `Author`, `CompanyName`,
5+
and `Copyright` keys of a new module manifest (DOC-18). Fill in the values that should appear. A
6+
line with no value is left out, and an agent does not invent one.
7+
8+
The standards installer creates this file when it is missing and never changes it afterwards, so
9+
these details belong to this repository.
10+
11+
- Author: Jeffrey Stuhr
12+
- Company:
13+
- Copyright holder: Jeffrey Stuhr
14+
- Blog: https://techbyjeff.net
15+
- LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/
16+
- Bluesky: https://bsky.app/profile/techbyjeff.net
17+
18+
Add a line in the same form for another profile, for example `- GitHub: https://github.com/<name>`.

‎.github/skills/powershell-new-module/SKILL.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded:
2222
if the module defines a class. Do not create empty folders for things the module does not have.
2323
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
2424
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
25-
by name. Take `Author` and the project links from the user or the repository; leave out what you do
26-
not know.
25+
by name. Take `Author`, `CompanyName`, and the copyright holder from
26+
`.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from
27+
the user or the repository; leave out what you do not know.
2728
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
2829
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
2930
`Public` dot-sourced in that order, failing the import if a file fails to load.

0 commit comments

Comments
 (0)