Repository navigation
📖 [Docs]: Release notes carry complete consumer adoption evidence - #204
Conversation
There was a problem hiding this comment.
🟡 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 releaseand## Release impactsections, 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 baselineheading, 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 evidenceheading, 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.
There was a problem hiding this comment.
🟢 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
There was a problem hiding this comment.
🟡 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
There was a problem hiding this comment.
🔵 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
|
Addressed the configured-default inconsistency from Copilot's review summary in |
There was a problem hiding this comment.
🟢 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
Consumers gain one staged procedure for upgrading from the upstream source they actually use to a fixed target, with every applicable release accounted for. Use producer-owned discovery to establish the baseline, compose the required actions, preserve local intent, and verify the result; a version bump or the newest release note alone is not evidence of adoption. The shared `msx` plugin adds an optional discovery shortcut. Connected guidance explains qualification, automated-update gates, safe propagation, and completion ownership. This change delivers documentation and a thin skill pointer, not a consumer migration or an updater, publisher, or evidence-validator implementation. <!-- ANNOUNCEMENT STOP --> ## New: Consumers can compose a complete upgrade The [Consumer Upgrades procedure](https://github.com/MSXOrg/docs/blob/main/src/docs/Ways-of-Working/Consumer-Upgrades.md) gives humans and agents one method for dependencies, frameworks, Actions, reusable workflows, and other versioned products. It connects immutable provenance, complete release history, an applicability-aware action ledger, the compatible target template, existing validation, and an explicit completion outcome. Each consumer establishes its own baseline even when a fleet shares one target. Follow these stages when adopting an upstream change: 1. Inventory the consumed references and establish the exact upstream version and authoritative immutable identity that actually resolved or ran. Distinguish that identity from the consumer's own package version. Use full commits for Git-distributed sources and authoritative digests or equivalent immutable identities for artifact-only products; do not invent Git mappings. A floating alias's present destination does not prove its past destination. Unknown baseline provenance blocks the upgrade. 2. Resolve and record one target: latest stable by default under the producer's version ordering and stable lineage, or an explicit stable/prerelease target. Exhaust paginated discovery and inspect every applicable release in `(baseline, target]`, in semantic and lineage order rather than API order or timestamps. Include no-action records; exclude unrelated backports and prerelease streams. Older targets use immutable target-era source, documentation, release snapshots, and templates, not today's aliases or final PR body. 3. Compose the required actions and record each disposition: completed with evidence, not applicable with a reason, no action required, or blocked with an owner. Reconcile renames, reversals, and superseded steps without deleting their evidence. Preserve mandatory intermediate conversions, installations, or runs; reading the complete history does not require installing every intermediate version. Equivalent authoritative external evidence is accepted without requiring MSX headings or tables. 4. Compare the consumer with the target's recorded compatible immutable template, distinguishing required integration surfaces, optional scaffolding, and intentional local differences. Never copy a template wholesale. Preserve consumer-owned code, tests, configuration intent, secrets, documentation, and assets. Record secret names and provisioning obligations, never values. If no template applies, state why; missing compatibility evidence is not a no-template result. 5. Run the existing relevant consumer tests, builds, linting, and integration checks against the exact target identity. Reconcile every ledger entry with the final diff and observed results, including no-action ranges. Keep introduced and pre-existing failures distinct; missing or failed required validation blocks readiness. 6. Carry the proven range, identities, complete release links, reconciled actions, template comparison, validation outcomes, and remaining blockers into the upgrade PR. Keep the consumer's release decision separate from its upstream target. Record review, merge, publication, and completion as distinct milestones. An identical target is already current; a lower target is superseded, not permission to downgrade. Retain the proven baseline, target, comparison, and reason in the delivery issue. Close only an unneeded open leaf with no remaining local work as not planned, without an empty PR or a shipped-upgrade claim. Preserve existing closed records, and reconcile an existing PR or unmet local acceptance criteria with its owner before changing its disposition. <details> <summary>Technical details</summary> The implementation adds the common playbook and routes existing discovery and adoption guidance to it. Missing provenance, release/action evidence, applicable template compatibility, or required prerequisites remains a stop condition. Changed inputs invalidate affected downstream evidence; the target is not silently changed. | Evidence | Source or scope | | --- | --- | | Exact candidate | MSXOrg/docs at `a8cecfddaf1a80efd6d5758e159844572d2b1e66`, branch `consumer-upgrades`. | | Current target observed during metadata revision | `main` at `5f64e8253b7bc2838c8c2bfb90e8ccd0a9d0e08d`. | | Scoped implementation comparison | Merge base `180f78a0b75b59149edca07280eca055ea303d82` through the candidate; the actual PR delta contains 19 files. This is PR evidence, not a fabricated consumer-publication baseline. | | Actual publication route | The candidate and current target use the native `Docs` workflow to build and deploy Pages. No versioned immutable artifact publication or Release Management decision path is configured in these workflows. Pages publication alone does not establish a managed release. | | Integration template | Not applicable to this documentation and thin-pointer delivery. Authoring structures are standards, not a product integration template; no pilot consumer or producer/template repository is modified. | No managed release decision or predicted release coordinate is asserted. The existing release-label mismatch remains a format-finalization blocker because this revision is limited to title and description. The first five implementation-plan steps in #203 are recorded complete. Walkthrough reconciliation, alignment, and scoped convergence evidence is retained here; the final normal review/handoff item remains incomplete. This metadata revision does not complete it or claim that the candidate contains later changes from `main`. The earlier eighteen documentation walkthroughs are retained in the issue's [range cases](#203 (comment)), [review edge cases](#203 (comment)), [conditional flows](#203 (comment)), [evidence isolation](#203 (comment)), and [entry gates](#203 (comment)). They exercise the written procedure, not a real consumer, pilot, live delegation, or security evaluation. | Cases | Required outcome | | --- | --- | | No-action patch and skipped releases | Retain every applicable record, reconcile the range, and run relevant existing validation. | | Breaking transition and renamed/reversed actions | Preserve local values and mandatory intermediate operations; classification does not hide incompatible behavior, including before 1.0. | | Prerelease and non-latest targets | Use source-specific snapshots and target-era evidence without merging unrelated streams or substituting final-PR prose. | | Floating baselines and artifact-only sources | Require past-execution provenance; accept authoritative immutable artifact identities without invented Git mappings. | | Missing evidence/template and no-template applicability | Block unknown required facts; distinguish justified non-applicability from missing evidence. | | Equal/lower targets and changed inputs | Record no-upgrade outcomes without empty PRs or downgrades; invalidate stale evidence without silently retargeting. | | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Consumer Upgrades playbook | Natural Language, Markdown, orchestration-playbook structure, evidence trust boundaries | PR Format; Release Management; Dependencies; Contribution Workflow | Aligned | | Navigation and discovery indexes | Existing front matter, navigation, and generated-index conventions | Documentation Model | Aligned | Source-bound validation remains available in the [earlier verification record](#205 (comment)). For the exact candidate above, the [Docs run](https://github.com/MSXOrg/docs/actions/runs/41505041468) and [cross-repository-links run](https://github.com/MSXOrg/docs/actions/runs/41505041504) completed successfully; Pages publication was skipped for the PR event. Earlier local checks and review records describe their tested revisions, not a newly added documentation-content assertion or index-drift enforcement policy. The recorded convergence search covered consumer, template, and downstream work. #143 needs separate standard-to-artifact inventory/enforcement, #136 owns Gallery updater delivery, and #187 needs router/published-URL enforcement. No additional issue was fully delivered by this diff; only #203 is a closing reference. </details> <details> <summary>Related references</summary> - Resolves #203 - References #202 - References #204 - References #143 - References #136 - References #187 </details> ## New: A shared skill exposes the procedure without owning producer discovery `msx-ways-of-working-consumer-upgrades` adds a thin pointer to the common procedure. Once the candidate is available through the marketplace, plugin consumers can refresh `msx@msxorg` to discover the intent; humans and agents can also follow the procedure directly without installing anything. Existing skill names remain supported. Producer or initiative guidance still owns authoritative repositories and registries, version/source mapping, release lineages, target-era guidance, and compatible immutable template discovery. The shared skill contains neither initiative-specific authority nor version-specific migration instructions. Its version does not prove template compatibility or that any producer implements the documented controls. <details> <summary>Technical details</summary> The eight-line skill points to one canonical document. Plugin and marketplace-entry metadata both change from `0.1.2` to `0.2.0` in the scoped comparison. These are repository manifest values, not evidence that a package or GitHub Release has been published, and not a selected consumer upstream target. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Plugin README, skill, and manifests | Natural Language, Markdown, existing names/layout/version conventions | Plugin Marketplaces; Plugin Distribution; existing marketplace validation | Aligned | | Plugin Marketplaces and Plugin Distribution | Natural Language, Markdown, thin-pointer ownership | Agentic Development; Agent Plugins and Agent Skills | Aligned | Existing marketplace validation covers source resolution, synchronized versions, unique plugin names, and valid skill metadata. No new runtime or plugin installation is required by this PR. </details> ## Changed: Update and fleet guidance qualifies work before implementation Dependency and fleet guidance now routes each actual consumer through the complete procedure instead of treating a reference change or the newest note as adoption. For a fleet upgrade, establish the pre-upgrade baseline and fixed target before creating or adopting a branch/PR. Do not use an existing PR's proposed references as proof of what the consumer consumed, discard unmet local acceptance work, or copy another consumer's edits. When implementing automated dependency-update handling, create proposals as drafts or immediately convert them to draft if the native updater cannot do so. Keep them draft until the normal readiness gate holds. Before enabling automatic readiness, approval, or merge, bind adoption verification to an existing required PR check, or a separate required check when none owns it. Missing, stale, pending, or failed evidence must hold those actions even if builds pass; keep automation outside those actions until enforcement exists. The draft flag preserves the review signal but is not that independent enforcement mechanism. A proven no-upgrade outcome needs no reference-change campaign or empty PR. Campaign issues retain their prefix, PRs retain reader-facing titles and verified native Development links, and target-specific issue-linking/closure rules still apply. Advancing a controlled compatible owned-major alias alone does not require a consumer reference-change campaign; deliberate pinned upgrades and breaking-major adoption still need per-consumer evidence. <details> <summary>Technical details</summary> This PR specifies adoption and automation gates; it does not implement a required evidence validator, updater, receiving workflow, ruleset change, or consumer campaign. The documented green-build/incomplete-evidence case must remain blocked in a conforming implementation. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Dependency Updates spec/design | Natural Language, Markdown, existing spec/design structure | Consumer Upgrades; Release Management; Merge Automation; review readiness | Aligned | | Fleet Orchestration | Natural Language, Markdown, fleet and delivery-leaf conventions | Consumer Upgrades; controlled owned-major policy; native issue linking; completion ownership | Aligned | The fleet view distinguishes integration, an evidenced not-needed result, and delivery completion. A merged reference bump or automatically closed issue alone does not prove required publication, deployment, or template work. </details> ## Changed: Propagation guidance preserves stable targets and isolated evidence Downstream-propagation guidance qualifies the actual consumer before Build and uses one durable delivery identity for a producer version and dependent. Implementations must validate stable release kind at both release-triggered and manual-backfill entry points, before fan-out or issue creation: skip prerelease events and reject prerelease backfill requests with a clear error. Keep the event or explicit backfill target fixed; delayed notifications never authorize downgrades. Standalone consumer prerelease upgrades do not widen this stable-only capability. The notifier creates or reuses the Task or Bug before engaging an agent. If authoritative provenance already proves no upgrade is needed, record that outcome without delegation. Otherwise use the producer's configured mode. Issue-first uses issue pickup only after delegation is selected. Task-first starts a read-only qualification task with `create_pull_request: false`, then creates or reuses one correlated PR-delivery task with `create_pull_request: true` only for a verified needed upgrade. That task uses the same issue and qualified plan and produces the closing PR, which remains draft until readiness. For retries, serialize discovery and handoff for that producer version and dependent; verify the issue's immutable target and retain execution correlation there. Issue existence, request acceptance, and task completion alone are not successful handoff. Reuse active execution and any matching PR or verified no-upgrade outcome. Retain an `idle` task for designated-owner re-engagement; a `waiting_for_user` task needs an authorized answer in that same task. Neither permits replacement. Failed, timed-out, canceled, missing, or uncertain outcomes require reconciliation before a safe retry; preserve partial consumer work rather than creating duplicate issues, tasks, or PRs. Carry the complete source-bound release record and publication envelope losslessly as untrusted evidence, separate from application-owned task instructions. A runtime data/attachment boundary or collision-safe quotation must prevent embedded directives or delimiters from changing scope, permissions, secret handling, or validation/review gates. Extract proposed actions and validate them against the consumer's governing instructions. A summary cannot replace the complete record or the consumer's full crossed range; unsafe isolation blocks delegation rather than truncating content or trusting it as instructions. For implementations, keep `PROPAGATION_TOKEN` as the explicitly passed secret name, scoped only to necessary dependents, with `Issues: write`, `Pull requests: read`, and mode-specific permissions. Task-first also needs the Agent Tasks API's accepted user credential with `Agent tasks: write`; Issue-first uses its configured pickup mechanism instead of unconditional task creation. Keep least-privilege workflow permissions and do not use `secrets: inherit`. The notification credential does not itself push or open PRs; execution does that in its own session. This documentation change provisions no credential, permission, setting, or task. <details> <summary>Technical details</summary> The spec/design and capability indexes now describe both a needed-upgrade PR and an evidenced no-upgrade outcome. The issue is durable identity; live execution state and actual handoff are read from their platform, not maintained in a second status store. Missing provenance, required actions, template evidence, or validation remains blocking; genuinely independent work alone can move to a follow-up. The recorded conditional-flow, adversarial-record, backfill, and paused-task walkthroughs distinguish the notifier, qualification, PR delivery, retries, and final consumer completion. They are documentation reasoning, not proof of an implemented Agent Tasks integration or runtime security control. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Downstream Release Propagation spec/design/index and capability discovery | Natural Language, Markdown, evidence trust boundaries | Consumer Upgrades; qualification/idempotency; configured delegation; Continuous Practices | Aligned | </details> ## Changed: Completion guidance keeps evidence and publication separate Review readiness now explicitly requires complete consumer evidence; an upgrade also reconciles its full baseline-to-target range. Applicable producer/template work needs demonstrated compatibility with an immutable reviewed identity. Verified candidate or prerelease evidence can support review without inventing final coordinates, creating a circular pre-merge prerequisite, or waiving a native blocker. Before review, name the issue and responsible owner for the whole required outcome. If source integration and necessary template or other delivery work span separate leaves, use a PBI with required native children and keep it open until the combined criteria are verified; each PR closes only its own Task or Bug and references the PBI without closing it. For a single leaf awaiting its own publication/deployment without an aggregate owner, the owner reopens it if PR closure precedes that evidence, then closes it only after verification. Reconcile template compatibility with the actual published producer identity and deliver necessary linked template changes before claiming completion; rerun affected validation when that identity differs. The existing Implement alignment pass carries these obligations in its normal PR sections and evidence rows, without a second checklist. Keep resource documentation current and retain release-specific transitions, migration history, and delivery plans in their GitHub records. Decision records and research retain their distinct purposes. A normative contract is not proof of implementation or CI enforcement; consumers adopting older targets still need immutable historical source/docs and release records. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Definition of Ready and Done; Implement | Natural Language, Markdown, readiness and issue hierarchy | PR Format; Release Management; Consumer Upgrades; Task/PBI completion | Aligned | | Documentation Model | Natural Language, Markdown, artifact tiers | Spec-Driven Development; source-bound release evidence | Aligned | #203, assigned to MariusStorhaug, remains the completion owner for this single-leaf documentation delivery and its required Pages publication. If PR closure precedes publication evidence, the owner follows the reopen path. No applicable integration template or additional delivery leaf calls for a PBI here. The old governance exception is resolved: #166 is closed, and current effective `main` rules require Lint, Links, Test, Build, and Cross-repository links. Passing candidate runs do not establish publication, complete the Task's remaining handoff item, or authorize merging. The PR is currently non-draft; this title/body revision leaves that state, labels, source, and native maintenance settings unchanged. The existing release-label mismatch on the Pages-only route is still a format blocker, not a supported release decision. Current canonical PR Format and Release Management, including the accepted defaults, keyed routing, lifecycle, and producer-conformance boundaries, govern finalization instead of the Task's historical kickoff policy. The scoped candidate diff changes no release resolver, PR Format, issue-type or community-file policy, tests, validation script, or workflow. This metadata revision does not restore documentation-content assertions or index-drift enforcement, change producer behavior, or claim conformance from documentation or plugin version numbers. Out of scope remain PSModule pilot selection/execution, historical release or PR backfill, version-specific skills, updater/publisher/validator implementations, automatic template synchronization, and unrelated governance changes. </details> <details> <summary>Related references</summary> - References #166 - References #196 - References #208 - References #230 - References #231 </details>
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
DefaultBumpin.github/release.config.yml. The setting acceptspatch,minor, ormajor. If neither supplies a level and no validrelease:skipis 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
DefaultBumpin the release settings. An explicit level wins; neither source is an error, not a patch default. Selectrelease:skipfor a no-release decision. Verify the resolved level against the audience impact.Release impact
release:skip, documentation only.Technical details
Consumer change record
DefaultBump; neither source fails. Required CI validates the decision and blocks merge on missing/invalid/conflicting input.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
6c07314/354dd8c, audience clarification inb1a8262/e55c80b, and decision/gate correction infd32b41.5124988102identified 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.DefaultBumpreuses the setting name from Release guidance uses keyed release types #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 walkthroughs below assess the documentation contract, not a running producer or the PSModule pilot:
Relevant issues (or links)
Related work