diff --git a/docs/content/reference/pipeline-stages.md b/docs/content/reference/pipeline-stages.md index 7611b9d5..16879f45 100644 --- a/docs/content/reference/pipeline-stages.md +++ b/docs/content/reference/pipeline-stages.md @@ -5,19 +5,16 @@ description: The job-by-job breakdown of the Process-PSModule workflow, from Pla # Pipeline stages -The Process-PSModule workflow composes its work from a set of reusable jobs. Each -one is described below, in the order it runs, with a link to the workflow that -implements it. +The Process-PSModule workflow uses reusable jobs. The sections below describe the jobs in the order they run and link to their workflows. -For which of these jobs run in a given trigger scenario, see the [scenario matrix](scenario-matrix.md). +The [scenario matrix](scenario-matrix.md) defines which jobs run for each trigger scenario. ## Plan [workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Plan.yml) -The Plan job is the single decision point of the workflow. It reads the settings file (`.github/PSModule.yml`), -collects event context from GitHub, and decides what should happen in the rest of the process. Using that -situational awareness, it calculates the next module version. +The Plan job is the workflow's single decision point. It reads the settings file (`.github/PSModule.yml`), +collects GitHub event context, and decides what should happen in the rest of the process. It uses this context to calculate the next module version. The user-facing settings file stays in `.github/PSModule.yml`. The workflow enriches that input into an internal runtime `Settings` object passed between jobs. In this runtime contract, execution decisions are phase-owned (`*.Enabled`), test @@ -65,7 +62,7 @@ suite matrices are computed under each owning test phase, and resolved version m - Tests the source code in parallel (matrix) using: - [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Test-PSModule/src/tests/SourceCode) -- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests. +- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results. For the coding practices this step enforces, see [framework test IDs](framework-test-ids.md#source-code-tests). @@ -75,7 +72,7 @@ For the coding practices this step enforces, see [framework test IDs](framework- - Lints the source code in parallel (matrix) using: - [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer) -- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the linter. +- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the linter results. ## Framework test @@ -84,7 +81,7 @@ For the coding practices this step enforces, see [framework test IDs](framework- - Tests and lints the module in parallel (matrix) using: - [PSModule framework settings for style and standards for modules](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Test-PSModule/src/tests/Module) - [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer) -- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests. +- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results. - **Code coverage for framework-generated code**: This step collects code coverage for framework-generated boilerplate. During the [build step](#build-module), [Build-PSModule](https://github.com/PSModule/Build-PSModule) injects boilerplate code into the compiled `.psm1` file — including type accelerator registration for public classes @@ -106,7 +103,7 @@ For the checks this step enforces on the built module, see [framework test IDs]( - `tests/BeforeAll.ps1`: Runs once before all module-local test matrix jobs to set up the test environment. - `tests/AfterAll.ps1`: Runs once after all module-local test matrix jobs complete to clean up the test environment. - The workflow checks only those exact repository-root paths; phase detection is non-recursive. -- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) to evaluate the results of the tests. +- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results. How to write these tests, including the Pester version requirement and shared-infrastructure patterns, is covered in [Writing module tests](../guides/writing-module-tests.md). @@ -116,7 +113,7 @@ How to write these tests, including the Pester version requirement and shared-in [workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Get-TestResults.yml) - Gathers the test results from the previous steps and creates a summary of the results. -- If any tests have failed, the workflow will fail here. +- If any tests fail, the workflow fails here. ## Get code coverage @@ -126,7 +123,7 @@ How to write these tests, including the Pester version requirement and shared-in - Aggregates coverage from the [Framework test](#framework-test) step (framework-generated boilerplate) and the [Test module](#test-module) step (module author code). A command executed in either step counts as covered, so framework-generated lines do not count against the module author's coverage target. -- If the code coverage is below the target, the workflow will fail here. +- If the code coverage is below the target, the workflow fails here. ## Publish module diff --git a/docs/content/reference/powershell-module-standard.md b/docs/content/reference/powershell-module-standard.md index 70a109bc..a155f098 100644 --- a/docs/content/reference/powershell-module-standard.md +++ b/docs/content/reference/powershell-module-standard.md @@ -44,7 +44,7 @@ The framework treats `src/` as the source for the compiled module. Place code in Layout rules: - **One declaration per file.** Filename matches the declared symbol exactly, including casing. -- **Group by domain.** Use resource or behaviour groups — not verb folders, not endpoint paths. +- **Group by domain.** Use resource or behavior groups — not verb folders, not endpoint paths. - **Mirror public and private domains.** Public command under `src/functions/public/Projects/` has related private helpers under `src/functions/private/Projects/`. - **No nested functions.** Do not define helper functions inside other functions. Extract helper logic to a separate function file and decide whether it belongs in `src/functions/private//` (internal-only) or `src/functions/public//` (part of the module API). - **Declare dependencies where they are used.** Use `#Requires -Modules ` at the top of each function file that needs an external module. Do not add `RequiredModules` to `src/manifest.psd1` — the build collects all `#Requires` declarations automatically and writes them into the compiled manifest. Entries in `src/manifest.psd1` are silently ignored for this purpose. @@ -65,7 +65,7 @@ Layout rules: ## SOLID applied -- **Single Responsibility.** One file, one function. One function, one user-visible behaviour. If the synopsis needs "and", split it. +- **Single Responsibility.** One file, one function. One function, one user-visible behavior. If the synopsis needs "and", split it. - **Open/Closed.** Extend via parameter sets, private helpers, or new files — not boolean switches that fork large blocks. - **Liskov.** A derived class must work wherever the base is expected. - **Interface Segregation.** Narrow, intent-named parameter sets. @@ -79,9 +79,9 @@ Every parameter that has a natural default should declare one. The most common u - Prefer `= 'main'` over making `-Branch` mandatory in commands that act on branches. - Prefer sensible page sizes, counts, or ranges over requiring callers to specify them. -- Prefer `= $false` for switches rather than leaving the behaviour implicit. +- Prefer `= $false` for switches rather than leaving the behavior implicit. -This is a usability expression of the **Open/Closed** principle: the common path is open by default; callers that need different behaviour extend it by supplying alternatives — they are never forced to know the default just to get started. +Parameter defaults apply the **Open/Closed** principle. The common path is open by default. Callers that need different behavior extend it with alternative inputs. They are never forced to know the default to get started. ### Object-first parameters @@ -91,7 +91,7 @@ Parameters represent attributes of a real-world entity. Design them to reflect t - **Group flat parameters by their conceptual object.** When a typed object is not available, prefix each parameter with the name of the entity it belongs to: `$ServerHost`, `$ServerPort`, `$ServerTls` rather than `$Host`, `$Port`, `$Tls`. The prefix makes the grouping explicit, prevents collisions with unrelated parameters, and avoids shadowing PowerShell built-in variables (`$Host`). - **Offer both modes when callers need both.** A parameter set that accepts an object and a parallel parameter set that accepts its individual attributes are equally valid; use both when that genuinely serves users. -This mirrors **Interface Segregation**: each parameter set represents one coherent input contract — not a flat list of loosely related knobs — so callers only touch what they need. +This applies **Interface Segregation**: each parameter set represents one coherent input contract, not a flat list of loosely related inputs. Callers supply only the inputs they need. > Note: the rule "avoid repeating the noun" (e.g. `-ID` not `-ProjectID` in `Get-ContosoProject`) applies to a command's *own* noun. The object-prefix convention above applies when a single command spans *multiple* conceptual objects (`$ServerHost` vs `$ClientID`) — the prefix is the object name, not the command noun, so there is no conflict. diff --git a/docs/content/reference/repository-standard.md b/docs/content/reference/repository-standard.md index 53e90e76..eca744d7 100644 --- a/docs/content/reference/repository-standard.md +++ b/docs/content/reference/repository-standard.md @@ -1,10 +1,10 @@ # Repository Standard -This is the PSModule organization's Repository Standard. It applies to the PSModule organization and is the standard for PowerShell module repositories. It describes what a newly created or maintained module repository should look like before module-specific code, tests, documentation, and managed repository files are considered. +This standard defines repository requirements for PowerShell modules in the PSModule organization. It describes how a newly created or maintained module repository should look. It defines the baseline before module-specific code, tests, documentation, and managed repository files are considered. -This standard operates at the same altitude as the [MSX Enterprise Repository Standard](https://msx.no/docs/Ways-of-Working/Repository-Standard/): MSX sets the enterprise-wide default, and this standard adds to and adjusts that default for PowerShell module repositories. Rules this standard does not change are inherited from the MSX default; where this standard adds or overrides a rule, it governs PowerShell module repositories. +This standard complements the [MSX Enterprise Repository Standard](https://msx.no/docs/Ways-of-Working/Repository-Standard/). MSX defines the enterprise-wide default. This standard adds requirements and overrides for PowerShell module repositories. Unchanged MSX rules still apply. Additions and overrides on this page govern PowerShell module repositories. -The implementation standard still lives in [PowerShell module standard](powershell-module-standard.md). Type-specific conventions for integration (API) and data modules live in [Module types](module-types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution. +The implementation standard is in [PowerShell module standard](powershell-module-standard.md). Type-specific conventions for integration (API) and data modules are in [Module types](module-types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution. ## Scope @@ -17,7 +17,9 @@ It does not apply directly to: - Template repositories other than `Template-PSModule`. - Test, archive, service, or infrastructure repositories that are not published as module artifacts. -Two baseline expectations still apply to every PSModule repository, including the types listed above. Each repository stands on its own: it carries its own governance and community files instead of relying on the organization `.github` fallback, and each repository ships the [agent onboarding files](#agent-onboarding-files) so an agent can work in it without prior context. What differs by type is the concrete file set and layout: the required files, README shape, and framework wiring on the rest of this page are the module standard, and non-module repositories keep only the equivalent baseline appropriate to their own type. This documentation project, maintained in `PSModule/Process-PSModule`, follows those two baseline expectations itself. +Two baseline expectations apply to every PSModule repository, including the types above. Each repository carries its own governance and community files instead of relying on the organization `.github` fallback. Each repository also ships the [agent onboarding files](#agent-onboarding-files) so an agent can work without prior context. + +The required file set, README shape, and framework wiring on this page apply to module repositories. Non-module repositories keep the equivalent baseline for their type. This documentation project, maintained in `PSModule/Process-PSModule`, also follows the two baseline expectations. Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth. @@ -306,7 +308,7 @@ Keep, trim, or relocate content — do not delete it: - **Trim:** exhaustive command inventories, parameter tables, and repetitive examples that differ only by a parameter. These come from comment-based help — point to `Get-Help` and the documentation site instead of restating them. - **Keep content in a published home — never drop it:** long-form guides and unique conceptual content (authentication and setup walkthroughs, deep operational detail, end-to-end scenarios) belong in a surface that is actually published: a command group's overview page under `src/functions/public//.md`, comment-based help, or published documentation in `docs/` or `examples/`. When no published home exists, keep the full content in the README to ensure it reaches users. A longer landing page is acceptable and expected for feature-rich modules; do not shorten by deleting. -Retain upstream attribution and licensing context. Credit, acknowledgements, donation notes, and third-party license notices for wrapped or bundled work must stay in the README or appear in a clearly linked location. The rule below about community and policy sections does not apply to attribution the project is expected to carry. +Retain upstream attribution and licensing context. Credit, acknowledgments, donation notes, and third-party license notices for wrapped or bundled work must stay in the README or appear in a clearly linked location. The rule below about community and policy sections does not apply to attribution the project is expected to carry. README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help. @@ -357,7 +359,7 @@ For an implemented module, also confirm the README keeps a capabilities or usage ## Documentation ownership -Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail. +Command details belong in comment-based help and generated documentation. The README can showcase capability, then point to those sources for reference detail. Use these defaults: diff --git a/docs/content/reference/settings.md b/docs/content/reference/settings.md index c2121220..e39c3a06 100644 --- a/docs/content/reference/settings.md +++ b/docs/content/reference/settings.md @@ -5,8 +5,8 @@ description: The Process-PSModule settings file — every available setting in . # Settings -The workflow is configured using a settings file in the module repository. -The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`. +The workflow uses a settings file in the module repository. +The file can use `JSON`, `YAML`, or `PSD1`. The default path is `.github/PSModule.yml`. The settings listed on this page are the user-facing configuration contract in `.github/PSModule.yml`. During the Plan phase, Process-PSModule enriches this input into an internal runtime `Settings` object that downstream workflows diff --git a/docs/content/reference/versioning.md b/docs/content/reference/versioning.md index ee2eafdd..c6259048 100644 --- a/docs/content/reference/versioning.md +++ b/docs/content/reference/versioning.md @@ -48,7 +48,7 @@ A **major version bump** signifies a breaking change in the module’s public in ## Minor Version (Y) – Backward-Compatible Additions -A **minor version bump** is used for new features and additions that are backward compatible with the existing public API. These changes enhance the module’s functionality without breaking any existing usage. In other words, existing scripts will continue to work as before, and new capabilities are introduced. Changes that trigger a MINOR version increase include: +A **minor version bump** applies to new features and additions that are backward compatible with the existing public API. Existing scripts continue to work. Changes that trigger a MINOR version increase include: - **Adding New Exported Functions/Cmdlets**: Introducing a new function or cmdlet to the module is a backward-compatible addition. Since it does not remove or change existing functions, nothing breaks; users simply have an additional function available. *Example:* Adding a new cmdlet `New-Report` to the module (where it didn’t exist before) would be a new feature. This warrants a minor version bump because it’s an additive, non-breaking change. @@ -70,11 +70,11 @@ A **minor version bump** is used for new features and additions that are backwar - **Non-Breaking Changes to Existing Features**: In some cases, a change might alter behavior but still be backward compatible. For instance, making an existing parameter accept a new type of input in addition to existing types (broadening what is accepted) could be considered a new capability that doesn’t break old usage. Such changes can fall under minor version if they extend functionality without removal or contradiction of the old behavior. *(However, caution is advised: changing behavior can sometimes surprise users. If in doubt, treat as major if it might disrupt assumptions.)* -In summary, **any new functionality that does not force existing users to change their usage is a candidate for a minor version increment** ([Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/#:~:text=Given%20a%20version%20number%20MAJOR,increment%20the)). Minor releases accumulate enhancements and new features, signalling to users that new capabilities are available, but all existing scripts should continue to work as they did in the previous version. Users can upgrade to the new minor version and gain new functions or options without needing to modify their existing code. This aligns with the SemVer guideline that *“MINOR version [increments] when you add functionality in a backward compatible manner”* ([Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/#:~:text=Given%20a%20version%20number%20MAJOR,increment%20the)). +In summary, **any new functionality that does not force existing users to change their usage is a candidate for a minor version increment** ([Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/#:~:text=Given%20a%20version%20number%20MAJOR,increment%20the)). Minor releases add enhancements and new features. All existing scripts should continue to work as they did in the previous version. Users can upgrade to the new minor version and use added functions or options without changes to their existing code. This follows the SemVer guideline that *“MINOR version [increments] when you add functionality in a backward compatible manner”* ([Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/#:~:text=Given%20a%20version%20number%20MAJOR,increment%20the)). ## Patch Version (Z) – Bugfixes and Improvements -A **patch version bump** is used for changes that do not affect the module's public API or add new features, but rather fix issues or improve internal implementation. Patch updates are meant to be safe, drop-in updates for users, with no risk of breaking functionality or changing how features are used. Scenarios for a PATCH version increment include: +A **patch version bump** fixes issues or improves the internal implementation without changing the module's public API or adding features. Patch updates are intended to preserve compatibility without changing how features are used. Scenarios for a PATCH version increment include: - **Bugfixes**: Correcting any bugs in existing functions or features, provided the fix does not alter the function's signature or expected input/output in a way that would break compatibility. The behavior might change (from incorrect to correct), but since the original behavior was unintended (a bug), this is considered a backward-compatible fix. For example: - Fixing a logic error in a function so that it now produces the correct result. @@ -156,7 +156,7 @@ If we only fixed a bug inside `Get-Data` but made no changes to its parameters o ## Conclusion -This specification provides a clear framework for versioning a PowerShell module in accordance with Semantic Versioning principles, tailored to the specific elements of a PowerShell module’s public interface. By classifying changes into major, minor, or patch categories, we ensure that the module’s version number accurately communicates the impact of changes: +This specification classifies changes to a PowerShell module's public interface by their Semantic Versioning impact: - **Major** versions for breaking changes (removals, renames, incompatible alterations). - **Minor** versions for new features and additions that are backward compatible. @@ -164,4 +164,4 @@ This specification provides a clear framework for versioning a PowerShell module Developers maintaining the module can use these guidelines to decide the appropriate version number for each release. Automated scripts will assist in detecting the scope of changes, but sound judgment will be applied in edge cases. Users of the module can rely on the version number to understand the significance of an update. Ultimately, this practice enables a predictable upgrade path where users only need to be concerned about potential breaking changes when the major version increases, and are otherwise free to take minor and patch updates confidently. -By adhering to this specification, we uphold a contract of compatibility and improvement with our users, making module releases transparent and manageable in the long run. +This specification defines a contract of compatibility and improvement between module maintainers and users. The version categories make releases easier to understand and manage. diff --git a/docs/content/reference/workflow-inputs.md b/docs/content/reference/workflow-inputs.md index a7c0d932..a349a336 100644 --- a/docs/content/reference/workflow-inputs.md +++ b/docs/content/reference/workflow-inputs.md @@ -5,8 +5,7 @@ description: The inputs, secrets, and permissions declared by the Process-PSModu # Workflow inputs -The reusable workflow lives at `PSModule/Process-PSModule/.github/workflows/workflow.yml`. This page is the exact -interface it exposes to a caller workflow. For how to wire it up, see +The reusable workflow is at `PSModule/Process-PSModule/.github/workflows/workflow.yml`. This page describes its exact caller interface. For caller configuration, see [Calling the workflow](../guides/calling-the-workflow.md). ## Inputs @@ -23,8 +22,8 @@ interface it exposes to a caller workflow. For how to wire it up, see ## Secrets -The workflow declares four workflow-call secrets, which keeps the calling workflow in full control of the -credentials that are exposed. `secrets: inherit` is intentionally not required. +The workflow declares four workflow-call secrets. The caller controls which credentials it exposes. +`secrets: inherit` is intentionally not required. | Name | Location | Description | Required | | ---- | -------- | ----------- | -------- | @@ -47,7 +46,7 @@ permissions: id-token: write # to verify the Pages deployment originates from an appropriate source ``` -For more info, see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site). +For more information, see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site). ## GitHub App permissions diff --git a/docs/content/specification/design.md b/docs/content/specification/design.md index 521b71b7..9e9e0940 100644 --- a/docs/content/specification/design.md +++ b/docs/content/specification/design.md @@ -5,7 +5,7 @@ description: How Process-PSModule delivers the spec — a single reusable GitHub # Process-PSModule — Design -The behaviour in the [spec](spec.md) is delivered by a **single reusable GitHub Actions workflow** at `PSModule/Process-PSModule/.github/workflows/workflow.yml`. A repository using the workflow provides a caller workflow and a minimal `.github/PSModule.yml` settings file; everything else uses sensible defaults. +The **single reusable GitHub Actions workflow** at `PSModule/Process-PSModule/.github/workflows/workflow.yml` delivers the behavior in the [spec](spec.md). Repositories that use the workflow provide a caller workflow and a minimal `.github/PSModule.yml` settings file. Other settings use defaults. ## Workflow architecture @@ -19,7 +19,7 @@ documented in [Workflow inputs](../reference/workflow-inputs.md). ### Composed reusable workflows -The main workflow composes work across specialized reusable workflows, each owning a pipeline stage: +The main workflow coordinates specialized reusable workflows. Each workflow owns a pipeline stage: - **Plan** — reads the settings file and event context, decides what runs, computes the next version - **Lint-Repository** — validates repository structure and configuration @@ -32,7 +32,7 @@ The main workflow composes work across specialized reusable workflows, each owni - **Publish-Module** — publishes the module to the PowerShell Gallery - **Publish-Site** — generates and publishes documentation to GitHub Pages -Each workflow is reusable so it can be tested and versioned independently, invoked by name in the main orchestration workflow. +Each workflow is reusable so it can be tested and versioned independently. The main orchestration workflow calls each workflow by name. ## Settings file contract @@ -40,7 +40,7 @@ The caller provides `.github/PSModule.yml`. Every key is optional and every sett start with an effectively empty file and opt out of individual phases as needed. The authorable contract is documented in [Settings](../reference/settings.md). -The Plan job reads this settings file, enriches it with computed values (phase enables, test matrices, resolved version, release decision), and passes the enriched settings to downstream jobs as a JSON string in workflow outputs. +The Plan job reads this settings file and adds phase enables, test matrices, the resolved version, and the release decision. It passes the enriched settings to downstream jobs as a JSON string in workflow outputs. That enriched object is an internal inter-workflow contract, not an authoring format. It is documented in [Pipeline stages](../reference/pipeline-stages.md#internal-runtime-settings-contract). @@ -76,13 +76,13 @@ Each stage of the pipeline is a reusable workflow so it can be tested independen **Alternative: Single monolithic workflow** -All logic in one workflow file. Pros: simpler to read end-to-end. Cons: harder to test, version, and reuse; changes in one stage risk all stages; every module repo copies the full logic. +All logic is in one workflow file. Pros: simpler to read end-to-end. Cons: harder to test, version, and reuse; changes in one stage risk all stages; every module repo copies the full logic. ### Settings file format **Chosen: YAML with runtime enrichment** -The caller provides a simple YAML file; the Plan job enriches it with computed values and passes the enriched settings to all downstream jobs. Pros: simple, readable, minimal to start. Cons: only the Plan job computes the settings; other jobs consume them. +The caller provides a YAML file. The Plan job enriches it with computed values and passes the enriched settings to all downstream jobs. Pros: simple, readable, minimal to start. Cons: only the Plan job computes the settings; other jobs consume them. **Alternative: JSON in workflow outputs** diff --git a/docs/content/specification/index.md b/docs/content/specification/index.md index 0b90c3a1..91e46416 100644 --- a/docs/content/specification/index.md +++ b/docs/content/specification/index.md @@ -6,7 +6,7 @@ description: The requirements and architecture behind Process-PSModule, for thos # Specification These pages describe **why** Process-PSModule exists, **what** it must guarantee, and **how** those guarantees are -delivered. They are aimed at people maintaining Process-PSModule itself. Module authors normally only need the +delivered. They are for maintainers of Process-PSModule. Module authors normally need only the [guides](../guides/calling-the-workflow.md) and [reference](../reference/settings.md). | Page | Description | diff --git a/docs/content/specification/principles-and-practices.md b/docs/content/specification/principles-and-practices.md index 4f942cd8..7b4faa17 100644 --- a/docs/content/specification/principles-and-practices.md +++ b/docs/content/specification/principles-and-practices.md @@ -7,10 +7,9 @@ description: The versioning, branching, and colocation principles behind Process ## Linear versioning -The contribution and release process is based on the idea that a PR is a release, and we only maintain a single linear ancestry of versions, not going -back to patch and update old versions of the modules. This means that if we are on version `2.1.3` of a module and there is a security issue, we only -patch the latest version with a fix, not releasing new versions based on older versions of the module, i.e. not updating the latest 1.x with the -patch. +The contribution and release process treats a PR as a release and maintains one linear version history. Only the latest version receives patches and updates. + +For example, if version `2.1.3` has a security issue, the fix applies to the latest version. The 1.x series does not receive the patch. ## Trunk-based development @@ -22,10 +21,9 @@ feature pull request when a preview version is needed before merging to `main`. ## Colocation of concerns -Colocate concerns for long-term maintainability. For example, `#Requires -Modules` statements belong in the function files that use them, not in a -central manifest — this makes it immediately visible which functions drive each external dependency, and avoids silent drift between the manifest and -the actual code. Another example is how parameter descriptions are placed as comments in the `param()` block directly above each parameter -declaration, rather than in the comment-based help at the top of the function — this keeps the description next to the code it documents. +Colocate concerns for long-term maintainability. For example, `#Requires -Modules` statements belong in the function files that use them, not in a central manifest. This shows which functions use each external dependency and prevents silent drift between the manifest and the code. + +Parameter descriptions are comments in the `param()` block, directly above each parameter declaration. This keeps each description next to its code, rather than in the comment-based help at the top of the function. ## Compatibility