Repository navigation
Release authors can write self-contained upgrade notes - #537
Draft
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Draft
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Marius Storhaug (MariusStorhaug) wants to merge 6 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>
Marius Storhaug (MariusStorhaug)
changed the title
This branch has not been deployed
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
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.
Release authors get a documentation and PR-authoring contract for complete, incremental upgrade records. The guidance makes published notes the sufficient reference for what changed, why, affected uses, compatibility, and exact consumer actions or an explicit no-action result.
Use the updated guide, PR template, and optional authoring skill for the next release-bound PR. Existing consumers need no workflow, configuration, code, or invocation changes from this documentation-only PR.
New: Authors can write complete consumer upgrade records
The authoring guide, repository PR template, and
psmodule-release-note-authoringskill give authors one entry path into the shared format. The guide is discoverable from documentation navigation, the index, versioning and configuration guides, repository-standard references, and the plugin README. The skill stays a thin pointer with agent-specific handoff and stop conditions.For the next release-bound PR:
Breaking,Removed,New,Changed, thenFixedorder. Put each result's rationale, applicability, compatibility, exact actions or explicit no-action result, prerequisites, order, verification, and necessary old-to-new examples in its reader-facing prose. Keep its implementation evidence and related references scoped to that result.Consumers read every applicable release after their actual baseline through the target in order and compose the actions. Reading a record does not require installing that version. Later supersession instructions explain which edits remain while preserving explicitly required intermediate installations or runs. Missing required instructions are evidence gaps, not implicit no-action results. PRs and commit diffs remain optional depth.
This adds authoring guidance and scaffolding, not release-runtime behavior. Existing release-note settings, version resolution, labels, defaults, workflows, and publisher behavior remain unchanged. No integration-template update applies because this change does not alter a producer runtime or caller contract. No intermediate installation or consumer upgrade is required to adopt the guidance.
Technical details
mainmerge base3505ca4b68b5c79e0b2a3051d0c33f2e9b275358.40346e7e03e05c218e1f365f604623d00d7e0acf, including PR Format, Release Management spec/design, and Documentation Model.NoReleaselabel is retained. This target route does not invoke shared MSX Release Management, so the conditionalRelease decisionsblock and namespaced release labels are omitted. No release resolver, publication envelope, workflow, or historical release-note correction is implemented here.docs/content/guides/**.github/PULL_REQUEST_TEMPLATE.md.github/plugin/**docs/zensical.toml,docs/content/index.md,docs/content/reference/repository-standard.mdValidation
npx --no-install markdownlint-cli2 --config .github/linters/.markdown-lint.yml .github/PULL_REQUEST_TEMPLATE.md .github/plugin/README.md .github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md docs/content/guides/formatting-release-note-prs.md docs/content/guides/configuring-the-pipeline.md docs/content/guides/versioning-and-releases.md docs/content/index.md docs/content/reference/repository-standard.mdnpm exec --offline --yes --package=textlint --package=textlint-rule-terminology --package=textlint-filter-rule-comments -- textlint --config .github/linters/.textlintrc .github/PULL_REQUEST_TEMPLATE.md .github/plugin/README.md .github/plugin/psmodule/skills/psmodule-release-note-authoring/SKILL.md docs/content/guides/formatting-release-note-prs.md docs/content/guides/configuring-the-pipeline.md docs/content/guides/versioning-and-releases.md docs/content/index.md docs/content/reference/repository-standard.mdcd docs && zensical build --cleanpython3 -m json.tool .github/plugin/psmodule/plugin.json >/dev/nullandpython3 -m json.tool .github/plugin/marketplace.json >/dev/nullgit diff --check origin/main...HEADThe illustrative content walkthrough reads the breaking
v2.0.0timeout-key transition and no-actionv2.0.1record from baselinev1.4.2. A consumer withtimeout: 20composes the notes, changes it totimeoutSeconds: 20with the target upgrade, selectsv2.0.1directly, and verifies accepted configuration and timeout cancellation. A consumer omitting the key retains the 30-second default; a consumer already onv2.0.0needs no configuration edit. No intermediate installation or PR/diff lookup is required. These are fictional published coordinates and a content check, not executed product tests or repository release history.PowerShell/Pester tests, release publishers, and actual consumer upgrades were not run because this PR changes documentation, the PR template, and authoring prompts only.
Related references