diff --git a/.agents/skills/powershell-new-module/SKILL.md b/.agents/skills/powershell-new-module/SKILL.md index a756dd9..27af578 100644 --- a/.agents/skills/powershell-new-module/SKILL.md +++ b/.agents/skills/powershell-new-module/SKILL.md @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded: if the module defines a class. Do not create empty folders for things the module does not have. 3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions - by name. Take `Author` and the project links from the user or the repository; leave out what you do - not know. + by name. Take `Author`, `CompanyName`, and the copyright holder from + `.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from + the user or the repository; leave out what you do not know. 4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and `Public` dot-sourced in that order, failing the import if a file fails to load. diff --git a/.claude/skills/powershell-new-module/SKILL.md b/.claude/skills/powershell-new-module/SKILL.md index a756dd9..27af578 100644 --- a/.claude/skills/powershell-new-module/SKILL.md +++ b/.claude/skills/powershell-new-module/SKILL.md @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded: if the module defines a class. Do not create empty folders for things the module does not have. 3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions - by name. Take `Author` and the project links from the user or the repository; leave out what you do - not know. + by name. Take `Author`, `CompanyName`, and the copyright holder from + `.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from + the user or the repository; leave out what you do not know. 4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and `Public` dot-sourced in that order, failing the import if a file fails to load. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2b39de1..59b7a61 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -168,7 +168,7 @@ counts as much as one listed here. - **DOC-05** Help MUST describe what the code does. Performance figures, compliance claims, and behaviour that the code does not have MUST NOT be invented. If a fact is not known, leave it out. - **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is - added only when the user supplies one. + added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18). ## Function template diff --git a/.github/instructions/powershell-help.instructions.md b/.github/instructions/powershell-help.instructions.md index a6efde1..b34e253 100644 --- a/.github/instructions/powershell-help.instructions.md +++ b/.github/instructions/powershell-help.instructions.md @@ -29,7 +29,7 @@ in `.github/instructions/powershell-platyps.instructions.md`. - **DOC-06** `.OUTPUTS` names the same type as `[OutputType()]`. `.INPUTS` names the type that can be piped in, or says `None`. - **DOC-07** Help MUST NOT contain a version number, a date, or a change history. An author name is - added only when the user supplies one. + added only when the user supplies one or `.github/powershell-attribution.md` lists one (DOC-18). - **DOC-08** Each `.EXAMPLE` starts with a command that runs as written, followed by a blank line and a sentence saying what it does. An explanatory line placed before that blank line MUST start with `#` and MUST NOT be the first line. @@ -55,11 +55,16 @@ in `.github/instructions/powershell-platyps.instructions.md`. A `DURATION:` line is added only for a time that was measured. - **DOC-15** `.NOTES` holds security considerations (permissions and data handling), performance characteristics, and known limitations with their workarounds. It holds the author's name, blog, - and LinkedIn address only when the user supplies them (DOC-07). + LinkedIn address, and other profiles only when the user supplies them or the project's + attribution file lists them (DOC-07, DOC-18). - **DOC-16** List references with one `.LINK` keyword for each: related commands, the online documentation of the command, and Microsoft documentation. - **DOC-17** Where they have been measured, help documents typical execution time, memory use, and scalability. It states no performance figure that was not measured (DOC-05). +- **DOC-18** When the project has `.github/powershell-attribution.md`, take the author details from + it: the `AUTHOR:` lines of `.NOTES` in new help, and the manifest keys of MOD-03. Use each line + that has a value, with its label, in the file's order. A line without a value is left out and + MUST NOT be filled in from anywhere else. Existing help is not changed only to add the details. ### Comments @@ -219,6 +224,39 @@ Test-Connection Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help` keeps these lines and the blank lines between them, and lists each `.LINK` as one related link. +**DOC-18.** The attribution file is a list of labelled lines that the project fills in: + +```markdown +- Author: Alex Example +- Company: +- Copyright holder: Alex Example +- Blog: https://blog.example.com +- LinkedIn: https://www.linkedin.com/in/alex-example +``` + +New help then ends its `.NOTES` with the lines that have a value. `Company` is empty, so it is left +out; `Copyright holder` belongs to the manifest only: + +```powershell +<# +.NOTES +KNOWN LIMITATIONS: +- Computers must be reachable through WinRM. + +AUTHOR: +- Author: Alex Example +- Blog: https://blog.example.com +- LinkedIn: https://www.linkedin.com/in/alex-example +#> +``` + +Tested on PowerShell 7.6 and Windows PowerShell 5.1: `Get-Help -Full` shows the `AUTHOR:` block as +written, after the other notes. + +The standards installer creates the file when it is missing and never changes it afterwards. It +starts from the profile of the project's GitHub owner when the standards repository has one, and +from an empty template otherwise. + **DOC-20.** ```powershell diff --git a/.github/instructions/powershell-modules.instructions.md b/.github/instructions/powershell-modules.instructions.md index c3ac0b9..2d8dc40 100644 --- a/.github/instructions/powershell-modules.instructions.md +++ b/.github/instructions/powershell-modules.instructions.md @@ -132,6 +132,11 @@ GUID, and it never changes afterwards. Set `Author`, `CompanyName`, `Copyright`, `Tags` from what the user or the repository provides; do not invent them. Write the copyright year as a literal: `'(c) $(Get-Date -Format yyyy) ...'` stays that literal text too. +When the project has `.github/powershell-attribution.md` (DOC-18), `Author` is its `Author` line, +`CompanyName` its `Company` line, and the holder in `Copyright` its `Copyright holder` line. Leave +out `CompanyName` when that line is empty, and name the author as the holder when the +`Copyright holder` line is empty. + Leave out `HelpInfoURI` unless the project publishes updatable help at that address: `Update-Help` reports an error against a `HelpInfoURI` that has no `HelpInfo.xml` behind it. Shipping compiled help in `en-US/` does not need the key. Leave out `IconUri` when there is no icon (MOD-13). diff --git a/.github/powershell-attribution.md b/.github/powershell-attribution.md new file mode 100644 index 0000000..20188e5 --- /dev/null +++ b/.github/powershell-attribution.md @@ -0,0 +1,18 @@ +# Attribution + +Coding agents that follow the PowerShell standards read this file when they write an author into +new code: the `.NOTES` of comment-based help and of help Markdown, and the `Author`, `CompanyName`, +and `Copyright` keys of a new module manifest (DOC-18). Fill in the values that should appear. A +line with no value is left out, and an agent does not invent one. + +The standards installer creates this file when it is missing and never changes it afterwards, so +these details belong to this repository. + +- Author: Jeffrey Stuhr +- Company: +- Copyright holder: Jeffrey Stuhr +- Blog: https://techbyjeff.net +- LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ +- Bluesky: https://bsky.app/profile/techbyjeff.net + +Add a line in the same form for another profile, for example `- GitHub: https://github.com/`. diff --git a/.github/skills/powershell-new-module/SKILL.md b/.github/skills/powershell-new-module/SKILL.md index a756dd9..27af578 100644 --- a/.github/skills/powershell-new-module/SKILL.md +++ b/.github/skills/powershell-new-module/SKILL.md @@ -22,8 +22,9 @@ Read these before writing files, unless they are already loaded: if the module defines a class. Do not create empty folders for things the module does not have. 3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions - by name. Take `Author` and the project links from the user or the repository; leave out what you do - not know. + by name. Take `Author`, `CompanyName`, and the copyright holder from + `.github/powershell-attribution.md` when the project has one (DOC-18), and the project links from + the user or the repository; leave out what you do not know. 4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and `Public` dot-sourced in that order, failing the import if a file fails to load.