diff --git a/AGENTS.md b/AGENTS.md index b4763bd..a3c149d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ If you find a problem, fix it if it's small; otherwise, register it as an issue 2. Clone the ecosystem locally: 1. — requires PRs to be updated. - Clone as bare and use worktrees. - - Create a worktree for all branches - worktree = name of the branch. + - Create a worktree for every branch. Use a concise `-` worktree folder for a topic branch named `/-`. 2. — work directly towards main. - Simple clone, only main. diff --git a/src/docs/Coding-Standards/PowerShell/Functions.md b/src/docs/Coding-Standards/PowerShell/Functions.md index 3ecc3f2..1848f6a 100644 --- a/src/docs/Coding-Standards/PowerShell/Functions.md +++ b/src/docs/Coding-Standards/PowerShell/Functions.md @@ -115,6 +115,8 @@ Send each kind of message to the stream built for it, so a caller can capture, r Every function carries comment-based help — including internal and private helpers, not only the public surface. It is what lets a reader or an agent understand what the function does and how to call it without reading its body, and a private helper needs that as much as a public command does. Put it first inside the body, with sections in this order: `.SYNOPSIS` (one imperative sentence), `.DESCRIPTION`, at least one `.EXAMPLE` per behaviour, then `.INPUTS`, `.OUTPUTS` (matching `[OutputType()]`), `.NOTES`, `.LINK`. Document each parameter with an inline comment above it rather than a `.PARAMETER` block, and let comments explain *why*, not *what*. +Functions in modules built with the PSModule framework use the generated online reference URL in `.LINK`: `https://psmodule.io//Functions/` or, for a grouped command, `https://psmodule.io//Functions//`. A private helper links to the published public function it supports. + ### `.INPUTS` and `.OUTPUTS` **`.INPUTS`** documents **pipeline input only** — types accepted via `ValueFromPipeline` or `ValueFromPipelineByPropertyName` parameters. It does not document ordinary parameters. diff --git a/src/docs/Frameworks/Process-PSModule/skipping-framework-tests.md b/src/docs/Frameworks/Process-PSModule/skipping-framework-tests.md index da111c4..d7810c5 100644 --- a/src/docs/Frameworks/Process-PSModule/skipping-framework-tests.md +++ b/src/docs/Frameworks/Process-PSModule/skipping-framework-tests.md @@ -58,38 +58,135 @@ Here's an example of a function file that skips the `FunctionCount` test because function Get-ComplexData { <# .SYNOPSIS - Retrieves complex data using helper functions. + Get formatted data from a file. + + .DESCRIPTION + Read data from a file and format it as a structured object. + + .EXAMPLE + Get-ComplexData -Path '.\data.txt' + + Get the file content and its character count. + + .INPUTS + None + + You can't pipe objects to Get-ComplexData. + + .OUTPUTS + System.Management.Automation.PSCustomObject + + The formatted file data. + + .NOTES + This file intentionally skips only the FunctionCount framework test. + + .LINK + https://psmodule.io//Functions/Get-ComplexData #> + [OutputType([PSCustomObject])] [CmdletBinding()] param( + # The path to the data file. [Parameter(Mandatory)] + [ValidateNotNullOrEmpty()] [string] $Path ) $data = Get-RawData -Path $Path - $processed = Format-ComplexData -Data $data - return $processed + Format-ComplexData -Data $data } function Get-RawData { + <# + .SYNOPSIS + Get unformatted data from a file. + + .DESCRIPTION + Read the complete content of a data file as one string. + + .EXAMPLE + Get-RawData -Path '.\data.txt' + + Get the complete content of the data file. + + .INPUTS + None + + You can't pipe objects to Get-RawData. + + .OUTPUTS + System.String + + The unformatted file content. + + .NOTES + This function is a private helper for Get-ComplexData. + + .LINK + https://psmodule.io//Functions/Get-ComplexData + #> + [OutputType([string])] [CmdletBinding()] param( + # The path to the data file. [Parameter(Mandatory)] + [ValidateNotNullOrEmpty()] [string] $Path ) - # Helper function implementation + + Get-Content -LiteralPath $Path -Raw } function Format-ComplexData { + <# + .SYNOPSIS + Format raw data as a structured object. + + .DESCRIPTION + Add useful metadata to raw data while preserving its content. + + .EXAMPLE + Format-ComplexData -Data 'example' + + Format the string and include its character count. + + .INPUTS + None + + You can't pipe objects to Format-ComplexData. + + .OUTPUTS + System.Management.Automation.PSCustomObject + + The formatted data and its character count. + + .NOTES + This function is a private helper for Get-ComplexData. + + .LINK + https://psmodule.io//Functions/Get-ComplexData + #> + [OutputType([PSCustomObject])] [CmdletBinding()] param( + # The raw content to format. [Parameter(Mandatory)] - $Data + [ValidateNotNullOrEmpty()] + [string] $Data ) - # Helper function implementation + + [PSCustomObject] @{ + Content = $Data + CharacterCount = $Data.Length + } } ``` +Replace `` with the module's published name. If the public function belongs to a group, insert `/` between `Functions/` and `Get-ComplexData`. + +The skip exempts only `FunctionCount`. Every function in the file must still follow the [PowerShell function standard](../../Coding-Standards/PowerShell/Functions.md), including complete comment-based help, matching `[OutputType()]` and `.OUTPUTS` metadata, typed parameters, and implicit output. + ## Best Practices - **Use skip comments sparingly**: Framework tests exist to maintain code quality and consistency. Only skip tests when absolutely necessary. diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md index 1087f45..53aa28e 100644 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ b/src/docs/Ways-of-Working/Git-Worktrees.md @@ -35,14 +35,14 @@ In a single ordinary clone the opposite is forced: one branch checked out at a t ├── .bare/ # bare git data (the actual repository) ├── .git # file containing: gitdir: ./.bare ├── / # worktree: default branch (always clean, never worked in directly) -├── 42-add-pagination/ # worktree: issue #42 in progress -└── 99-fix-null-ref/ # worktree: issue #99 in progress +├── 42-add-pagination/ # worktree folder; branch: feat/42-add-pagination +└── 99-null-ref/ # worktree folder; branch: fix/99-null-ref ``` - **`.bare/`** — the shared git object store. All worktrees share this. - **`.git`** — a file (not a directory) that points git tooling to `.bare/`. - **`/`** — the default branch worktree (e.g. `main` or `master`). Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to. -- **`-/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name. +- **`-/`** — one worktree folder per issue in flight, named by issue number and a short slug. The folder is a concise local path; its branch uses the required `/-` name, so the two names do not need to match. ## Remotes @@ -105,14 +105,16 @@ git -C .bare config "branch.$defaultBranch.merge" "refs/heads/$defaultBranch" ```powershell # From the repo root (where .bare/ lives) $defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' } -git -C .bare worktree add ../42-add-pagination -b 42-add-pagination $defaultBranch +$worktreeName = '42-add-pagination' +$branchName = 'feat/42-add-pagination' +git -C .bare worktree add "../$worktreeName" -b $branchName $defaultBranch # Set upstream tracking (prevents "Publish Branch" prompt in VS Code) -git -C .bare config branch.42-add-pagination.remote origin -git -C .bare config branch.42-add-pagination.merge refs/heads/42-add-pagination +git -C .bare config "branch.$branchName.remote" origin +git -C .bare config "branch.$branchName.merge" "refs/heads/$branchName" # Open in VS Code -code 42-add-pagination +code $worktreeName ``` Then follow the normal Implement flow: initial commit → push → draft PR → build → finalize. @@ -124,7 +126,7 @@ Then follow the normal Implement flow: initial commit → push → draft PR → git -C .bare worktree remove 42-add-pagination # Delete the local branch ref -git -C .bare branch -D 42-add-pagination +git -C .bare branch -D feat/42-add-pagination # Prune if needed (removes stale worktree references) git -C .bare worktree prune diff --git a/src/docs/Ways-of-Working/Issue-Format.md b/src/docs/Ways-of-Working/Issue-Format.md index ab98b49..43441a7 100644 --- a/src/docs/Ways-of-Working/Issue-Format.md +++ b/src/docs/Ways-of-Working/Issue-Format.md @@ -229,10 +229,11 @@ The task-level roadmap. Implementers track progress here; reviewers use it to un Structure: - Every discrete piece of work is a checkbox: `- [ ]`. -- Tasks are grouped under subheadings when work spans multiple areas (files, components, tests). +- Tasks are grouped under subheadings when work spans multiple behaviors or dependencies. Keep each behavior's tests with its implementation tasks. - Each task is specific and actionable — file paths, function names, modules. - All tasks start unchecked. Checking happens during implementation. -- Tasks are ordered logically — dependencies first, tests last. +- Order groups and tasks so scope and dependencies are clear; the checklist layout is not a mandatory execution sequence. +- Follow [test-first development](../Coding-Standards/Testing.md#test-first): define and run a behavior's test before implementing that behavior, regardless of how its checkboxes are organized. For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](Issue-Hierarchy.md). @@ -243,17 +244,17 @@ For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline ## Implementation plan -### Core changes +### Paged responses +- [ ] Add unit test for single-page response +- [ ] Add unit test for multi-page response - [ ] Add a paged-request helper in `src/lib/` - [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/` -- [ ] Add a `--limit` option with integer type and validation -### Tests +### Result limiting -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response - [ ] Add unit test for `--limit` option limiting results +- [ ] Add a `--limit` option with integer type and validation ### Documentation @@ -375,17 +376,17 @@ multi-page, and `--limit` limiting. ## Implementation plan -### Core changes +### Paged responses +- [ ] Add unit test for single-page response +- [ ] Add unit test for multi-page response - [ ] Add a paged-request helper in `src/lib/` - [ ] Update the `repo list` command to call the paged variant in `src/commands/repository/` -- [ ] Add a `--limit` option with integer type and validation -### Tests +### Result limiting -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response - [ ] Add unit test for `--limit` option limiting results +- [ ] Add a `--limit` option with integer type and validation ### Documentation diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index 3f8f750..fa4f105 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -110,7 +110,7 @@ Default title pattern: []: ``` -The description should lead with user-facing impact, then issue links when available, then user-facing change sections, with technical details at the bottom. +The description should lead with user-facing impact, continue with user-facing change sections, include optional technical details after those sections, and end with the related-issues block. Repository templates may be simpler than the full PR Manager body, but they must gather enough information to reconstruct it.