Make release impact and user adoption explicit in PR release notes

[MariusStorhaug]

Problem

The PR Format makes the pull request the release note but does not require one ordered adoption path, an effective release decision, or a complete incremental consumer-change record. Consumers cannot reliably compose the changes across releases when required actions remain scattered through implementation notes or version-specific skills.

Evidence

The original request reports a review of 242 pull requests in PSModule/Process-PSModule: 235 had non-empty descriptions, 24 used both ending details blocks, and 60 used the current user-facing change sections. Those are the original audit's observations, not counts re-established by this delivery.

The original examples remain supporting context: PSModule/Process-PSModule#524, PSModule/Process-PSModule#529, and PSModule/Process-PSModule#531 distribute or omit adoption/version information; PSModule/Process-PSModule#535 illustrates an ordered consumer-change section.

The release-authoring work in PSModule/Process-PSModule#537 needs an artifact-neutral MSX contract to reference. MSXOrg/docs#196 independently changes release-policy resolution; this delivery reports the effective policy decision without redesigning it or taking ownership of that PR.

Request

Make a release-bound PR sufficient incremental evidence for a consumer to adopt that release, and require publication to preserve that evidence. Retain the summary, applicable user-facing change sections, and final Technical details / Relevant issues blocks. Add required Adopting this release and Release impact blocks and distinguish consumer evidence from maintainer evidence inside Technical details.

Acceptance criteria

• An author can describe a release for any artifact type using one complete example, including ordered adoption or an explicit no-action outcome.
• Change classification is based on the declared target audience's supported use and integration contracts. Users and integrators can be the same people; both Process-PSModule and PowerShell modules illustrate this. Each initiative defines its audience, and each repository states or explicitly adopts and specializes that definition in its README.
• Each affected consumer surface records its identifier, before/after behavior, applicability and prerequisites, exact action, and verification. Breaking behavior remains visible even when the version policy selects Minor, including pre-1.0 releases.
• Release impact records the effective release decision and its source, semantic effect, and release/base coordinates without inventing final versions before publication.
• An explicit owned bump label overrides an optional, valid repository-configured DefaultBump. If neither supplies a level, there is no implicit patch fallback: the decision is missing. Explicit release:skip remains a valid no-release decision.
• Missing decisions, invalid defaults, and conflicting owned labels fail a named required PR CI check before merge. Source, release-label, and settings changes re-evaluate the decision. Branch protection/rulesets require that check, so an absent, pending, or failed result cannot permit merge; release-time validation remains mandatory.
• Applicable framework releases identify a verified compatible immutable template commit, producer version/source identity, compatibility evidence, and linked template work or a justified no-change result.
• The release-management contract preserves the release-bound title and complete authored body, including adoption and technical details. Actual coordinates and provenance are finalized by the release process in a distinct envelope.
• Bundled, optional ad hoc, and source-ref-specific prerelease notes retain the same evidence obligations. Published-note corrections have an audit trail and never change artifacts, tags, SHAs, or historical behavior.
• Release-label names, SemVer arithmetic, pre-1.0 classification, and issue-reference/closure rules remain unchanged. Audience-based impact determines the type; the explicit label or configured default supplies the effective release level. The common consumer procedure, producer/template completion gates, pilot execution, and historical backfill are not implemented in this PR.

Technical decisions

• Edit src/docs/Ways-of-Working/PR-Format.md and src/docs/Capabilities/release-management/{spec,design}.md, extending their existing shape rather than reformatting unrelated requirements.
• Give audience declarations one rule in Readme-Driven-Context.md, linked from Repository-Standard.md and Organization-Standard.md. Apply it in the MSX Docs README and the PSModule initiative overview. Keep initiative-specific operational guidance producer-owned; no fleet of consumer README edits is included.
• Keep the contract in structured Markdown inside the PR body; no JSON/YAML sidecar, release-history file, migration cookbook, updater, publisher implementation, or synchronization service is added.
• Describe the delta introduced by one release. Consumers compose multiple release records; this authoring slice does not implement that traversal procedure.
• Name changed public inputs, APIs, configuration keys, paths, permissions, secret names without values, runtime/tool requirements, defaults, removals, and behavior. Changed filenames alone are insufficient.
• Report the effective release resolver decision and its source. Reuse the optional DefaultBump setting name from 📖 [Docs]: Release bumps now have a configurable default #196 in .github/release.config.yml; accept patch, minor, or major only, with no built-in fallback. Keep the existing label names and branch/type model; 📖 [Docs]: Release bumps now have a configurable default #196 still owns its separate redesign and must reconcile its conflicting implicit-patch proposal before merge.
• Align PR Format, readiness/Implement wording, Automation Labels, branching/promotion and continuous-delivery guidance, Natural Language error examples, and the VS Code framework with the shared resolver. Document the required pre-merge decision check through the existing merge-automation contract; do not add a publisher or CI implementation to this docs repository.
• Keep .github/plugin/msx/skills/msx-ways-of-working-pr-format/SKILL.md as a thin pointer. Its existing discovery wording is sufficient, so plugin metadata and versions do not change.
• Prepare the common upgrade procedure and completion gates as a separate native Task, with execution order represented by a native dependency. PSModule pilot work and historical writes remain separately refined delivery work.
• The existing repository-protection gap in MSXOrg/docs#166 prevents safe auto-merge: the active main ruleset has no required-status-check rule. Correcting governance is outside this PR; auto-merge remains disabled while that prerequisite is unresolved.

Implementation plan

• Inspect the existing issue, PR format, publication contract, thin pointer, and in-flight release-policy diff; establish authoring cases for a no-action patch, breaking transition, skipped releases, prerelease target, and non-latest target.
• Add the incremental PR evidence contract and complete artifact-neutral example in src/docs/Ways-of-Working/PR-Format.md; preserve version and issue rules.
• Compare publication requirements against the authoring cases, including full-body retention, provenance, bundled/ad hoc/prerelease mapping, and metadata-only correction.
• Align src/docs/Capabilities/release-management/spec.md and design.md with the PR evidence contract.
• Establish audience-classification cases for shared user/integrator roles, a breaking manifest or workflow edit, a mixed breaking/fix change, and missing audience context.
• Clarify audience ownership in the README/organization/repository standards and PSModule overview, then make PR classification follow supported audience impact rather than path-only inference.
• Establish decision cases for explicit level, configured default, precedence, missing/invalid/conflicting inputs, skip, prerelease, unowned labels, and CI re-evaluation that blocks merge.
• Correct the release spec/design and all directly affected authoring, gate, and consuming guidance; regenerate indexes for changed descriptions.
• Run the existing documentation index check, relative-link and applicable cross-repository-link checks, and targeted Markdown linting. Run existing documentation tests where applicable; do not introduce a validation toolchain.
• Reconcile the extended authoring cases and standards/framework alignment and repeat the scoped issue-convergence sweep. The dependent common-procedure Task remains prepared.
• Complete the current-head Copilot review loop, read its full summary including suppressed comments, and address every concern. Zero new inline comments alone is not a clean review.
• Complete the normal review handoff once the native repository-governance prerequisite is satisfied. Leave auto-merge disabled and preserve the user-selected PR readiness state while reporting unmet prerequisites.

[MariusStorhaug]

Refined this existing request into one native Task for incremental PR consumer evidence and lossless release publication, retaining the original audit as attributed context. The version/label policy remains unchanged; #196 owns that separate work. The common upgrade procedure is being prepared as a separate dependent Task. Pilot execution and historical writes are outside this delivery.

[MariusStorhaug]

PR authoring is implemented in commit 6c07314 and the draft #204. The first two plan steps are complete; index freshness, relative links, and targeted Markdown lint pass. The pre-implementation case set covers no-action patch evidence, pre-1.0 breaking behavior, composed skipped releases, source-specific prerelease snapshots, and a non-latest target with immutable template evidence. Release-management alignment follows in the same scoped PR; the common procedure remains separate in #203.

[MariusStorhaug]

Commit 354dd8c completes the release-management contract and clarifies both first-round review findings in #204. Plan steps 3-5 are complete. The five documentation walkthroughs preserve no-action evidence, pre-1.0 breaking behavior, intervening release deltas, source-specific prerelease snapshots, and immutable non-latest target/template evidence; no consumer pilot was run. Local index/relative-link/Markdown checks pass, and the current PR head has successful cross-repository-link and Pester CI jobs. The alignment pass found the already-tracked #166 gate gap: active main rules have no required-status-check rule. A native prerequisite now records that blocker; this PR stays draft and does not enable auto-merge or change governance. #203 remains the separate common-procedure Task.

[MariusStorhaug]

Authoring and verification are complete at 354dd8c. The current-head Copilot round completed at 2026-09-06T09:20:32Z with no new comments, and all review threads are resolved. Build, Links, Test, and Lint pass in the Docs run; cross-repository links pass in the link run. Publication is correctly skipped for this documentation PR. The final plan item is split to distinguish completed authoring/review work from the remaining handoff gate. #204 remains draft with auto-merge disabled because #166 is still open. The worktree is clean, both commits are pushed, and #203 retains its native dependency. No pilot, historical metadata, plugin, publisher, or repository-governance changes were made.

[MariusStorhaug]

The user clarified that change type must reflect the target user/integrator, and that these roles are the same audience for Process-PSModule and PSModule PowerShell modules. This extends the authoring slice with explicit initiative/repository audience declarations and impact-based classification. Path names and edit size become evidence-navigation hints, not release-impact rules. The existing label vocabulary, version resolver, and pre-1.0 mapping remain unchanged; validation and review steps are reopened for the extended diff. The governance prerequisite and separate common-procedure delivery are unchanged.

[MariusStorhaug]

Commit b1a8262 adds the requested audience contract and classification rules. Initiative docs declare audiences; repository READMEs state or explicitly adopt and specialize them. The PSModule overview identifies PowerShell users and module maintainers as users/integrators of their respective products. Breaking supported contracts outrank compatible fixes regardless of path or edit size. The release spec and path-filter design also clarify that caller workflows and artifact-producing configuration are not automatically internal tooling; this closes the same path-only inference gap without changing label vocabulary, pre-1.0 mapping, or version computation. The eight changed Markdown files pass targeted linting, the index check is current, and relative links resolve. The current-head review and CI handoff remain pending; governance and pilot work are unchanged.

[MariusStorhaug]

The audience clarification is complete in b1a8262 and e55c80b. Review prompted a safer workflow-producer example: the public caller and local implementation are included explicitly, without a blanket .github exclusion. All nine documentation walkthroughs are reconciled. At e55c80b, the current-head Copilot round is clean (2026-09-06T09:55:16Z) and every thread is resolved. Build, Links, Test, and Lint pass in the Docs run; cross-repository links pass in the link run. The worktree is clean and both follow-up commits are pushed. Only the existing governance handoff remains open: #166 is still unresolved, so #204 remains draft with auto-merge disabled. No pilot, fleet README rollout, publisher implementation, or historical backfill was performed.