📖 [Docs]: Release notes carry complete consumer adoption evidence

[Marius Storhaug (MariusStorhaug)]

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.

---

Technical details

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: Make release impact and user adoption explicit in PR release notes #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 📖 [Docs]: Release bumps now have a configurable default #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. Missing required repository-standard files in MSXOrg/docs #67 still needs repository-standard files, Name the downstream artifacts a standard governs, so changing it has a known blast radius #143 still needs downstream-artifact mapping/enforcement, and Define the evergreen consumer upgrade procedure and completion gates #203 owns the common consumer procedure. No additional issue is fully satisfied.
• Repository gate: Require status checks in the main ruleset #166 remains a native prerequisite of Make release impact and user adoption explicit in PR release notes #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 Define the evergreen consumer upgrade procedure and completion gates #203, with a native dependency on Make release impact and user adoption explicit in PR release notes #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.

Relevant issues (or links)

• Resolves Make release impact and user adoption explicit in PR release notes #202

Related work

• Depends on Require status checks in the main ruleset #166
• Followed by Define the evergreen consumer upgrade procedure and completion gates #203
• References 📖 [Docs]: Release bumps now have a configurable default #196
• References Name the downstream artifacts a standard governs, so changing it has a known blast radius #143
• References Missing required repository-standard files in MSXOrg/docs #67
• References 📖 [Docs]: Pull requests now control user-ready release notes PSModule/Process-PSModule#537

[Copilot]

🟡 Changes recommended

The updated guidance contains internal inconsistencies (notably release-impact “published coordinates” requirements and mismatched heading levels vs the example) that could mislead authors following the template.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the MSX PR Format documentation to treat release-bound PR bodies as the authoritative, consumer-facing adoption record, and to require explicit adoption and release-impact evidence that publication preserves.

Changes:

• Adds “source of truth” guidance connecting PR bodies to Release Management’s publication/provenance responsibilities.
• Requires structured ## Adopting this release and ## Release impact sections, plus a consumer change record/template baseline/maintainer evidence split under Technical details.
• Expands the example PR body to demonstrate the new required sections and evidence tables.

File summaries

File	Description
src/docs/Ways-of-Working/PR-Format.md	Clarifies PR bodies as authored release notes and adds explicit adoption, release-impact, and evidence-record requirements.

Review details

Suppressed comments (2)

src/docs/Ways-of-Working/PR-Format.md:166

• The guidance section uses a #### Template baseline heading, but the Example block below uses ### Template baseline. Aligning these heading levels avoids ambiguity about the expected structure inside the Technical details block.

#### Template baseline

src/docs/Ways-of-Working/PR-Format.md:179

• The guidance section uses a #### Maintainer evidence heading, but the Example block below uses ### Maintainer evidence. Using the same heading level in both places will make the template easier to follow.

#### Maintainer evidence

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The documentation updates are internally consistent, links/anchors resolve correctly, and the described authoring/publication contracts align across PR Format and Release Management spec/design.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Two documentation issues in changed lines (path-filter snippet copy/paste hazard and minor wording/grammar inconsistencies) should be corrected to avoid propagating incorrect guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

There is at least one internal inconsistency in the updated documentation contract wording that could mislead authors about required release-decision evidence.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/docs/Ways-of-Working/PR-Format.md:130

• The “Effective decision” row currently reads as if a configured policy could supply the release decision instead of an explicit owned release:* label. That conflicts with the Release Management spec’s requirement that a bump label is mandatory (no default) and risks confusing authors about what must appear in the PR body.

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Marius Storhaug (MariusStorhaug)]

Addressed the configured-default inconsistency from Copilot's review summary in fd32b41. The spec/design now require an explicit bump or an opt-in repository DefaultBump; there is no implicit patch fallback. Missing, invalid, or conflicting decisions must fail a required pre-merge CI check, while a valid release:skip reports a successful no-release decision. Related authoring and framework guidance is aligned. These are documentation requirements; producer CI and ruleset implementation remain separately scoped.

[Copilot]

🟢 Approved

The changes are documentation-only, internally consistent across the touched standards/specs, and introduce no verified broken links or formatting defects in the modified sections.

Review details

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Lite