Skip to content

📖 [Docs]: Release bumps now have a configurable default - #196

Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
default-release-bump
Open

📖 [Docs]: Release bumps now have a configurable default#196
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
default-release-bump

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Aug 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Repositories can configure their normal semantic version bump through DefaultBump, and release branches are keyed by the release type they publish. Explicit owned bump labels override the bump policy, release:prerelease reuses the resolved bump, and release:skip remains the publication stop.

Changed: Release bumps have a safe repository default

DefaultBump accepts patch, minor, or major and resolves to patch when omitted. A pull request can override it with one owned bump label; release:prerelease selects prerelease mode; conflicting owned labels fail; and bare or unrelated labels remain ignored.

Changed: Release types own their branch configuration

ReleaseType is keyed by Stable, Prerelease, and ReleaseCandidate. Each key owns its Branch property, so a branch cannot silently change release behavior through a separate type field. The stable branch defaults to the repository default branch; prerelease and release-candidate branches are optional.

DefaultBump: patch
ReleaseType:
  Stable:
    Branch: main
  Prerelease:
    Branch: dev
  ReleaseCandidate:
    Branch: rc
Technical details
  • The Release Management specification and design define the configuration, resolution order, validation, release types, and promotion behavior.
  • The canonical owned label set is release:patch, release:minor, release:major, release:skip, and release:prerelease.
  • Automation Labels, PR Format, Continuous Delivery and Release, Branching and Merging, Natural Language examples, and the VS Code Extension Framework use the same contract.
  • The optional workflow_dispatch path still requires an explicit bump and release-note context.
  • Empty pull requests and direct pushes remain excluded as ad hoc release interfaces.
  • Dependency-tool guidance, implementation repositories, and fleet labels are unchanged.
  • Issue convergence sweep: no open MSXOrg/docs issue matching DefaultBump, default bump, release label, release management, or release type is fully satisfied by this diff.
Changed surface Standards checked Framework docs checked Result
src/docs/Capabilities/release-management/** Natural Language, Markdown Release Management Aligned
src/docs/Capabilities/vscode-extension-framework/** Natural Language, Markdown Release Management, VS Code Extension Framework Aligned
src/docs/Ways-of-Working/** Natural Language, Markdown Release Management Aligned
src/docs/Coding-Standards/Natural-Language.md Natural Language, Markdown Release Management Aligned
Relevant issues (or links)

Related work

@MariusStorhaug Marius Storhaug (MariusStorhaug) added the release:skip Validate the change without publishing a release. label Aug 29, 2026
Copilot AI reviewed Aug 29, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the MSX documentation set to introduce a configurable repository-wide default semantic version bump (DefaultBump) for release automation, while keeping owned release:* labels as explicit overrides and updating prerelease semantics to reuse the resolved bump.

Changes:

  • Define DefaultBump (defaulting to patch) and the override / conflict rules in Release Management spec + design.
  • Update Ways of Working guidance (PR format, CD/release, branching/promotion, automation labels) to reflect “policy-first” bump selection and prerelease behavior.
  • Align the VS Code Extension Framework spec/design with the Release Management contract.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
src/docs/Ways-of-Working/PR-Format.md Documents how release:pre-release interacts with DefaultBump and owned bump-label overrides.
src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md Updates CD/release “decision at the gate” language to reference resolved release policy and DefaultBump.
src/docs/Ways-of-Working/Branching-and-Merging.md Updates promotion-model guidance to use the resolved policy / DefaultBump with explicit overrides.
src/docs/Ways-of-Working/Automation-Labels.md Reframes label meanings around DefaultBump + owned label overrides and conflict handling.
src/docs/Coding-Standards/Natural-Language.md Updates example language/error-message guidance to reflect conflicting owned bump labels and DefaultBump.
src/docs/Capabilities/vscode-extension-framework/spec.md Updates framework requirements/success criteria to match policy-driven bump selection.
src/docs/Capabilities/vscode-extension-framework/design.md Updates pipeline/design narrative to reference release policy and DefaultBump in version resolution.
src/docs/Capabilities/release-management/spec.md Defines the normative DefaultBump rules, override precedence, prerelease behavior, and label conflict handling.
src/docs/Capabilities/release-management/index.md Updates the section index descriptions to match the refreshed spec/design framing.
src/docs/Capabilities/release-management/design.md Documents configuration surface and pipeline behavior for resolving DefaultBump + owned label overrides.

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

Comment thread src/docs/Coding-Standards/Natural-Language.md Outdated
Comment thread src/docs/Ways-of-Working/Branching-and-Merging.md Outdated
Comment thread src/docs/Ways-of-Working/Automation-Labels.md Outdated
Comment thread src/docs/Capabilities/vscode-extension-framework/spec.md Outdated
Comment thread src/docs/Capabilities/vscode-extension-framework/design.md Outdated
Copilot AI reviewed Aug 29, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review August 29, 2026 12:43
Draft
Copilot AI reviewed Sep 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The documentation updates appear internally consistent across all touched pages and align with the stated DefaultBump/owned-label override/prerelease/skip contract.

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

Copilot AI reviewed Sep 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The changes are documentation-only and appear internally consistent with the new DefaultBump/ReleaseType contract, with only a minor wording nit noted.

Review details

Suppressed comments (1)

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

src/docs/Capabilities/release-management/spec.md:3

  • The front-matter description repeats “driven” twice (“policy-driven … releases driven …”), which reads awkwardly in generated index tables and summaries. Consider rephrasing the second instance (and then regenerating the affected INDEX tables).
  • Files reviewed: 10/10 changed files
  • Comments generated: 0 new
  • Review effort level: Lite

Closed
12 tasks
@MariusStorhaug

Marius Storhaug (MariusStorhaug) commented Sep 6, 2026

Copy link
Copy Markdown
Member Author

Coordination for #202: I am adding incremental consumer evidence and complete-note publication rules in PR Format and the release-management spec/design. This work leaves version selection, label names, DefaultBump, and ReleaseType ownership with this PR. The release-impact record reports the effective resolver decision and its source, so it remains compatible with either merge order. I will reference this PR and will not edit its branch or description.

Merged
@MariusStorhaug

Marius Storhaug (MariusStorhaug) commented Sep 6, 2026

Copy link
Copy Markdown
Member Author

Coordination from #204: the user confirmed that a release level can come from an explicit owned bump label or a repository-configured DefaultBump, but chose to fail when both are absent. The missing-decision error must also fail a required pre-merge CI check. This differs from the implicit patch fallback proposed here. I am aligning the release evidence contract and its dependent guidance in #204 with that confirmed rule, reusing the DefaultBump setting name. I am not changing this branch, its ReleaseType redesign, or its label rename; the default-fallback portion here needs reconciliation before merge to avoid restoring a conflicting rule.

Marius Storhaug (MariusStorhaug) added a commit that referenced this pull request Sep 6, 2026
@MariusStorhaug
📖 [Docs]: Release notes carry complete consumer adoption evidence (#204)
702be0f 
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 was referenced Sep 6, 2026
Open
Draft
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

At least 0 approving reviews are required to merge this pull request.

Assignees

@MariusStorhaug Marius Storhaug (MariusStorhaug)

Labels

release:skip Validate the change without publishing a release.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@MariusStorhaug