📖 [Docs]: Pull requests now control user-ready release notes - #537
Draft
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Draft
📖 [Docs]: Pull requests now control user-ready release notes#537Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
Conversation
Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
Super-linter summary
All files and directories linted successfully For more information, see the GitHub Actions workflow run Powered by Super-linter |
Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
changed the title
This was referenced Sep 6, 2026
Marius Storhaug (MariusStorhaug)
added a commit
to MSXOrg/docs
that referenced
this pull request
Sep 6, 2026
Release-bound pull requests classify changes for their declared user/integrator audience and describe the incremental actions that audience needs to adopt them. Release levels come from an explicit decision or an opt-in repository default; missing decisions must block merge in CI. Published notes preserve the complete authored record and its source/template evidence. ## Changed: Change type follows the target audience Each initiative describes its audience and supported jobs; each repository README states its audience or explicitly adopts that definition and records any specialization. Users and integrators can be the same people: PSModule module users integrate commands into their work, and Process-PSModule users integrate the delivery workflow into their module repositories. Change type follows the highest impact on supported uses, not file location, edit size, or the reviewer's perspective. An incompatible output, runtime requirement, or caller interface remains breaking even when an interactive command still works or only a manifest or `.github/` file changes. ## Changed: Repository defaults are explicit policy decisions For PR-driven releases, an owned bump label overrides the optional `DefaultBump` in `.github/release.config.yml`. The setting accepts `patch`, `minor`, or `major`. If neither supplies a level and no valid `release:skip` is selected, the decision is missing: there is no implicit patch fallback. Prerelease mode can use an explicit or configured bump, but the mode alone is not a level. Invalid defaults and conflicting owned labels fail rather than selecting a convenient fallback. The declared default is not evidence of compatibility: authors still assess the audience impact and override the default when needed. Release-label names, SemVer arithmetic, and pre-1.0 mapping remain unchanged. The optional ad hoc dispatch keeps its existing explicit-bump requirement. ## Changed: Missing decisions block merge, not only publication The release contract requires a named PR decision-validation check, enforced by the target branch's ruleset or protection. Missing, invalid, or conflicting decisions fail it before merge. The check re-evaluates source, release-label, and settings changes; a failed, pending, or absent required result prevents manual and automatic merge. A valid skip passes with a no-release outcome instead of skipping validation. Publication validates its actual inputs again. This PR documents that contract; it does not implement producer CI workflows or change repository rulesets. ## Changed: Consumer adoption and publication evidence are complete PR descriptions include Adopting this release and Release impact sections, an applicability-aware consumer change record, and a verified immutable template baseline where applicable. Public interfaces belong in user-facing prose, and breaking behavior remains explicit independently of version classification. The release-management contract preserves the release-bound title and complete description. Actual coordinates and provenance remain separate from authored prose, and version-computation and consumer-change baselines remain distinct. Bundled, optional ad hoc, and source-specific prerelease records retain equivalent evidence. Metadata corrections preserve an audit without changing artifacts or historical behavior. Release filters reflect product contracts, not directory names alone. ## Adopting this release 1. Initiative owners declare their audience and supported jobs. Repository maintainers state the audience, jobs, and interfaces in the README, or explicitly adopt the initiative definition and record any specialization. Detailed users and jobs stay in the linked capability specification. 2. For each PR release decision, select an owned level or intentionally configure `DefaultBump` in the release settings. An explicit level wins; neither source is an error, not a patch default. Select `release:skip` for a no-release decision. Verify the resolved level against the audience impact. 3. Use the PR Format structure: ordered adoption or an explicit no-action outcome, effective release impact and its source without predicting a final version, and each changed surface's before/after behavior, applicability, exact action, and verification. Include a verified immutable template baseline where applicable, or explain why none applies. 4. Producer CI maintainers run the same decision resolver during PR validation, make its named check required in branch protection/rulesets, and cover relevant source and metadata changes. Missing, invalid, conflicting, pending, and absent results must not permit merge; a valid skip must produce an explicit successful result. 5. Publisher maintainers preserve the complete source-bound record, resolve actual publication coordinates, audit metadata corrections, and keep consumer-facing interfaces in release filters. Implementation and governance changes remain separately scoped in their owning repositories. ## Release impact | Field | Value | | --- | --- | | Effective decision | `release:skip`, documentation only. | | Semantic effect | No versioned artifact release. The documented PR decision contract permits an opt-in default and requires a merge-blocking CI gate; it does not install that gate in producers. | | Release/base coordinates | No version is produced by this PR. | --- <details> <summary>Technical details</summary> ### Consumer change record | Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification | | --- | --- | --- | --- | --- | --- | | AUDIENCE-CONTEXT / initiative docs and READMEs | Audience context is not required as an input to classification. | Explicit audience, jobs, and interfaces anchor classification; user/integrator roles may overlap. | Initiative owners, maintainers, and PR authors. | Adoption steps 1-2. | Readers identify supported uses without inferring them from ownership or filenames. | | RELEASE-DECISION / release settings and PR CI | The spec forbids defaults while PR evidence permits configured policy; missing decisions lack an explicit required pre-merge check contract. | An explicit bump overrides optional `DefaultBump`; neither source fails. Required CI validates the decision and blocks merge on missing/invalid/conflicting input. | Producers implementing Release Management and consuming frameworks. | Adoption steps 2 and 4. | Explicit/default/override/skip/mode/error cases agree; the decision check is required, not merely advisory. | | PR-EVIDENCE / release-bound PR bodies | Adoption may be scattered and path/size heuristics can obscure impact. | Ordered adoption, resolved release impact, consumer/template evidence, and highest-impact classification are required. | Authors following MSX PR Format. | Adoption steps 2-3. | Every changed surface records applicability, action, and result; no-action and breaking cases stay explicit. | | NOTE-PUBLICATION / publication contract | Complete-body, source-snapshot, correction, and product-aware filter obligations are not explicit. | Full authored records retain actual coordinates and source identity; corrections preserve artifacts; filters include shipped interfaces. | Publisher maintainers. | Adoption step 5. | Published content matches its source-bound snapshot, and metadata corrections leave artifact/source identities intact. | ### Template baseline Not applicable: this PR changes shared standards, not a versioned framework integration or its template. The PR-format skill remains an unchanged thin pointer; no plugin metadata or version change is needed. ### Maintainer evidence - Delivery: #202, refined to a native Task and updated with the user's audience, opt-in default, and pre-merge CI requirements. The initial contract is in `6c07314` / `354dd8c`, audience clarification in `b1a8262` / `e55c80b`, and decision/gate correction in `fd32b41`. - Copilot review `5124988102` identified the default-policy contradiction in its suppressed summary. The earlier zero-inline-comment verdict missed that concern. Review now includes the complete summary, including suppressed comments; zero inline comments alone is not a clean round. - The shared resolver is defined in Release Management. PR Format, Automation Labels, readiness/Implement wording, promotion/continuous-delivery guidance, Natural Language error examples, and the VS Code framework agree with it. Generated release navigation is current. - `DefaultBump` reuses the setting name from #196, but the user explicitly rejected that PR's implicit patch fallback. Coordination is recorded there. Its branch, release-type redesign, and label rename remain untouched and need reconciliation before merge. - The existing index, relative-link, and targeted Markdown checks pass. CI uses the existing cross-repository-link and Pester jobs; no validation toolchain or publisher implementation was added. - Convergence: release/adoption/PR-format and audience issues were inspected. #67 still needs repository-standard files, #143 still needs downstream-artifact mapping/enforcement, and #203 owns the common consumer procedure. No additional issue is fully satisfied. - **Repository gate:** #166 remains a native prerequisite of #202 and tracks missing required CI enforcement. The user marked this PR ready; this session preserves that state and leaves auto-merge disabled rather than changing governance or bypassing the prerequisite. - Delivery B remains prepared as #203, with a native dependency on #202. The PSModule pilot, fleet README rollout, and historical backfill remain outside this delivery. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | PR Format and related workflow/gate guidance | Natural Language, Markdown, Documentation Model, standard template, issue/PR conventions | Release Management; Merge Automation; audience contract | Aligned | | Release Management spec/design/index | Natural Language, Markdown, Documentation Model, spec/design templates | PR Format; Merge Automation | Aligned | | VS Code framework spec/design | Natural Language, Markdown, Documentation Model, spec/design templates | Shared Release Management contract | Aligned | | README/organization/repository standards and audience examples | Natural Language, Markdown, README-Driven Context | MSX documentation purpose; PSModule initiative boundary | Aligned | | Natural Language error examples | Natural Language, Markdown | Release-decision validation contract | Aligned | The walkthroughs below assess the documentation contract, not a running producer or the PSModule pilot: | Case group | Reconciled outcome | | --- | --- | | No-action patch; pre-1.0 break | No-action is explicit; Minor mapping does not hide breaking behavior or required actions. | | Skipped releases; prerelease; non-latest target | Each applicable delta and source/template identity remains recoverable; latest metadata does not replace historical evidence. | | Shared user/integrator roles; path/size; mixed changes; missing audience | Supported audience impact controls classification; absent audience context is resolved rather than guessed. | | Explicit level; configured default; override | A valid explicit label wins; a configured default supplies a missing bump and is recorded as the source. | | Missing/invalid/conflicting decisions | The required PR check fails and merge is blocked. No built-in patch or conflict fallback is permitted. | | Skip; prerelease; unowned labels | Valid skip passes without a bump; a mode needs a resolved bump; unowned labels never supply a decision. | | Changed labels/settings/source | Validation re-evaluates the candidate inputs; publication revalidates its actual inputs too. | </details> <details> <summary>Relevant issues (or links)</summary> - Resolves #202 ### Related work - Depends on #166 - Followed by #203 - References #196 - References #143 - References #67 - References PSModule/Process-PSModule#537 </details>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contributors now have a final pull-request content-control plan for the title, description, and label that automated releases reuse as user-facing GitHub Release notes. The guide governs those three fields before review; it is not a separate release-note artifact.
New: Pull-request formatting guide
The documentation now gives authors one artifact-neutral format for PowerShell modules, reusable workflows, GitHub Actions, libraries, services, and infrastructure modules. It keeps the user outcome and the technical delivery evidence distinct while making the release message an intentional author decision.
New: Release-note authoring skill and template
The
psmodule-release-note-authoringskill and the repository pull-request template now guide authors through the same content-control plan while the pull request is being written. They require an explicit adoption path and prevent the published body from retaining placeholders or reviewer-oriented prose.Changed: PR-based release notes show the complete transition
The release configuration guide and versioning guide now establish that automation reuses the pull request title as the release-note heading and its description as the body by default. Authors record the configured label, SemVer effect, current published version, and planned released version together with the user adoption path.
Adopting this release
psmoduleplugin when this change is available to your repository.No caller workflow, module configuration, command invocation, or existing release behavior changes in this documentation release.
Release impact
NoReleaseTechnical details
docs/content/guides/formatting-release-note-prs.md, exposes it in the Guides navigation, and links the release configuration and versioning guides to it..github/PULL_REQUEST_TEMPLATE.mdand the thinpsmodule-release-note-authoringplugin skill; both defer shared policy to the documentation guide.PSModule/Release-GHRepositoryv2.0.3.docs/content/guides/**docs/zensical.toml.github/PULL_REQUEST_TEMPLATE.md.github/plugin/**Relevant issues (or links)
Related work