Skip to content

Commit f782069

Browse files
Address Copilot review: examples/ not a published surface; complete round-trip grammar
- Repository-Defaults README validation no longer calls examples/ a published surface; it now aligns with the 'relocate only to a published home' rule (group overview page or comment-based help) and states repository-only locations such as examples/ must still be linked from the README. - Naming.md and Module-Types.md: complete the 'so data round-trips' clause -> 'so data can round-trip between the format and the object model'.
1 parent 828fe3a commit f782069

3 files changed

Lines changed: 3 additions & 3 deletions

File tree

src/docs/PowerShell/Modules/Module-Types.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ format-specific representation *into* an object; `ConvertTo-<Format>` renders an
6868
format. Converting through the object as a common pivot means any format interoperates with any
6969
other, instead of writing a direct converter for every pair.
7070

71-
Always ship **both** directions so data round-trips.
71+
Always ship **both** directions so data can round-trip between the format and the object model.
7272

7373
### Verb vocabulary
7474

src/docs/PowerShell/Modules/Repository-Defaults.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@ git diff --check -- README.md
307307

308308
`Template-PSModule` is the exception: it intentionally keeps `{{ NAME }}` and `{{ DESCRIPTION }}` tokens because those are template inputs.
309309

310-
For an implemented module, also confirm the README keeps a `## Usage` showcase and that any unique content removed from the previous version — prerequisites, setup or authentication guidance, operational notes, or upstream attribution — was relocated to a published surface (`src/functions/public/<Group>/<Group>.md`, `examples/`, or comment-based help) rather than deleted.
310+
For an implemented module, also confirm the README keeps a `## Usage` showcase and that any unique content removed from the previous version — prerequisites, setup or authentication guidance, operational notes, or upstream attribution — was kept on the landing page or relocated to a published home (`src/functions/public/<Group>/<Group>.md` or comment-based help) rather than deleted. Repository-only locations such as `examples/` are not published on their own, so content moved there must still be linked from the README.
311311

312312
## Documentation ownership
313313

src/docs/PowerShell/Standard/Naming.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ function Get-ContosoProjectByID { } # Named after lookup mechanism
2727

2828
## Data conversion and I/O verbs
2929

30-
**Practice:** In data modules, use a fixed verb vocabulary. `ConvertFrom-<Format>` turns a format-specific representation into a neutral `[PSCustomObject]`/`[hashtable]`; `ConvertTo-<Format>` does the reverse. Use `Import-`/`Export-` for file or store round-trips, `Format-` for a normalized rendering, and `Merge-`, `Compare-`, `Test-`, or `Remove-…Entry` to manipulate a structure. Always provide both `ConvertTo-` and `ConvertFrom-` so data round-trips.
30+
**Practice:** In data modules, use a fixed verb vocabulary. `ConvertFrom-<Format>` turns a format-specific representation into a neutral `[PSCustomObject]`/`[hashtable]`; `ConvertTo-<Format>` does the reverse. Use `Import-`/`Export-` for file or store round-trips, `Format-` for a normalized rendering, and `Merge-`, `Compare-`, `Test-`, or `Remove-…Entry` to manipulate a structure. Always provide both `ConvertTo-` and `ConvertFrom-` so data can round-trip between the format and the object model.
3131

3232
**Why:** `ConvertTo`/`ConvertFrom` around the neutral PowerShell object model let any format interoperate with any other through a common pivot — the object — instead of N×N direct converters. A predictable verb set makes a data module's surface obvious to humans and agents.
3333

0 commit comments

Comments
 (0)