diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 959ba7b..43de0c3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,7 +2,9 @@ Every change lands through a pull request — nothing goes directly to `main`. See the [Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/) -for the full process: draft first, the Copilot review loop, then human review. +for the full process: draft first, the Copilot review loop, then human review. Write the +title and description according to +[PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/). Everything here is a work in progress and can be improved. Fix a small problem when it is directly in scope; register a larger or unrelated one as an issue in the repository that @@ -50,6 +52,17 @@ owns it. 7. Open the pull request as a draft and follow the [Contribution Workflow](https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/). +## Pull request template + +This repository intentionally has no local pull request template. GitHub inherits +the [MSX organization +template](https://github.com/MSXOrg/.github/blob/main/.github/pull_request_template.md) +from the special `MSXOrg/.github` repository. Treat that template as a starting +scaffold; the canonical [PR +Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/) controls the +final title and description. Start from its +[complete description template](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/#copy-the-complete-template). + ## Authoring conventions The docs are built for recursive navigation, so a reader or an agent can start at the top @@ -113,6 +126,6 @@ conventional-commit prefixes. See Push every commit, so the remote branch, CI, and the draft pull request always reflect the current state of the work. -See the [README](README.md) for what this repository is and how it is laid out, and the +See the [README](../README.md) for what this repository is and how it is laid out, and the [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) for the conventions every pull request follows — issue format, PR format, branching, and review etiquette. diff --git a/src/docs/Capabilities/dependency-updates/design.md b/src/docs/Capabilities/dependency-updates/design.md index 56f4797..d0dcbeb 100644 --- a/src/docs/Capabilities/dependency-updates/design.md +++ b/src/docs/Capabilities/dependency-updates/design.md @@ -80,14 +80,16 @@ flowchart TD pr --> ci["Required checks run
(same gate as any PR)"] ci --> review["Review and merge"] review --> merged["Merged"] - merged --> release["Separate release decision
see Release Management"] + merged --> release["Conditional release decision
see Release Management"] ``` ### Release decision -Dependency changes are collected before the repository release decision is -made. The repository-wide effect follows [Release -Management](../release-management/design.md). +Dependency changes are collected before any repository release decision is +made. When the target route invokes [Release +Management](../release-management/design.md), that capability resolves the +repository-wide effect. Otherwise the pull request omits the `Release decisions` +block and all `release:*` labels. ## Review and merge @@ -97,8 +99,8 @@ gates. Automatic merge, where configured, never bypasses those gates. ## Security updates Raised on advisory disclosure, independently of the schedule, and -**prioritised**. They otherwise follow the same review policy and release path as -any other update. +**prioritised**. They otherwise follow the same review policy and any applicable +release path as another update. ## Configuration surface @@ -108,7 +110,7 @@ any other update. | Unsupported ecosystems | Central exception register | Centrally managed shared mechanism | | Schedule (`interval`, `day` and `time`, or `cronjob`) and `timezone` | `.github/dependabot.yml` | Organization configuration | | Cooldown | Updater default (three days); explicit mapping only for a deliberate non-default duration | Organization configuration | -| Release decision | Release Management | Decided for the collected repository change | +| Release decision | Release Management, when invoked for the target route | Decided for the collected repository change | | Merge policy | Branch protection and merge automation | Organization configuration | | Security updates | Repository security settings | On by default | @@ -121,6 +123,6 @@ rather than overwrite. - [Spec](spec.md) — the requirements this design delivers. - [Repository Governance](../repository-governance/design.md#drift-detection-and-reconciliation) — the reconciliation that compares generated configuration against what is committed. -- [Release Management](../release-management/design.md) — the release an update PR cuts. +- [Release Management](../release-management/design.md) — the conditional release decision and output for an update pull request. - [Downstream Release Propagation](../downstream-release-propagation/design.md) — the internal counterpart; propagation PRs are dependency updates too. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#keep-pinned-actions-current) — the Action-pin specifics this builds on. diff --git a/src/docs/Capabilities/dependency-updates/spec.md b/src/docs/Capabilities/dependency-updates/spec.md index 419d833..e4425b0 100644 --- a/src/docs/Capabilities/dependency-updates/spec.md +++ b/src/docs/Capabilities/dependency-updates/spec.md @@ -11,15 +11,18 @@ Every repository pins dependencies by version — Action SHAs, image digests, package versions, provider constraints. Those pins age: a newer version fixes a bug the repository still carries, and a disclosed advisory turns a safe pin into a vulnerability. Keeping them current MUST be automatic and driven on the GitHub -platform, producing ordinary pull requests that are reviewed and released -through the same gate as any change — never a side channel that bypasses review. +platform, producing ordinary pull requests that are reviewed through the same +gate as any change — never a side channel that bypasses review. When the target +route invokes Release Management, its release decision and publication path are +resolved separately from the updater; a route without that invocation carries +no `release:*` metadata. ### Principles This capability rests on the [Principles](../../Ways-of-Working/Principles/index.md): - **[Everything as Code](../../Ways-of-Working/Principles/Engineering-Practices.md#everything-as-code).** What is checked and how often is version-controlled configuration, not a manual audit. -- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** Every update is a pull request; its review gate approves the bump, while its release impact is decided separately. +- **[Decision before change](../../Ways-of-Working/Principles/AI-First-Development.md#decision-before-change).** Every update is a pull request; its review gate approves the dependency change, while any applicable release decision is resolved separately. - **[Least-privilege](../../Ways-of-Working/Principles/Purpose-and-Direction.md#least-privilege).** The updater and any auto-merge automation carry only the permissions they need. - **[Extensible by default](../../Ways-of-Working/Principles/Software-Design.md#extensible-by-default).** Adding a package ecosystem is a configuration entry, not new machinery. @@ -31,9 +34,9 @@ other ecosystem the repository actually uses. Two questions are asked of every p **currency** (is a newer version available?) and **security** (does the pinned version carry a known advisory?). -Out of scope: what an update *does* to the artifact. That is the release the update -produces, and it is governed by [Release -Management](../release-management/spec.md). +Out of scope: what an update *does* to the artifact. Where the target route +invokes [Release Management](../release-management/spec.md), that capability +governs the release decision and output. ## Requirements @@ -69,7 +72,7 @@ Management](../release-management/spec.md). ### Review and release - **FR10 — One reviewed pull request per update.** Each dependency update is a pull request that passes the full check suite before merge. Nothing is applied unreviewed, and no update takes a side channel around the gate. -- **FR11 — Release impact is decided separately.** The dependency updater MUST NOT choose the repository's release bump. After dependency changes are collected, the repository-wide effect is decided according to [Release Management](../release-management/spec.md). +- **FR11 — Release decisions stay independent.** The dependency updater MUST NOT choose the repository's release bump or apply `release:*` labels. After dependency changes are collected, the repository-wide effect is decided according to [Release Management](../release-management/spec.md) only when the target route invokes it. - **FR12 — Review and merge follow the repository gate.** An update MUST pass the repository's normal review and required-check policy before merge. - **FR13 — Automatic merge is never a bypass.** Where automatic merge is configured, it MUST preserve review requirements and required checks. @@ -83,12 +86,12 @@ Management](../release-management/spec.md). - An outdated or vulnerable pin produces a pull request with no human trigger. - An ecosystem added to a repository without a corresponding updater entry is a detectable finding, not a silent gap. -- The repository-wide release impact of dependency changes is decided separately under Release Management. +- When the target route invokes Release Management, the repository-wide release decision for dependency changes is resolved separately under that capability. - No dependency pull request merges without passing the same checks as any other pull request. ## Where this connects - [Design](design.md) — the updater, review, and automatic-merge policy. -- [Release Management](../release-management/spec.md) — the separate repository-wide release decision for merged dependency changes. +- [Release Management](../release-management/spec.md) — the conditional, separate repository-wide release decision for merged dependency changes. - [Repository Governance](../repository-governance/spec.md) — the reconciliation that detects an uncovered ecosystem. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#keep-pinned-actions-current) — keeping pinned Actions current. diff --git a/src/docs/Capabilities/merge-automation/design.md b/src/docs/Capabilities/merge-automation/design.md index 72abac7..9d30134 100644 --- a/src/docs/Capabilities/merge-automation/design.md +++ b/src/docs/Capabilities/merge-automation/design.md @@ -103,5 +103,5 @@ approval to the eligible set the ruleset actually lets it satisfy. - [Spec](spec.md) — the requirements this design delivers. - [GitHub Actions](../../Coding-Standards/GitHub-Actions.md#gate-merges-with-a-named-status-check) — authoring the named checks this consumes. - [Dependency Updates](../dependency-updates/design.md) — the auto-merge policy this generalises; dependency update PRs are the canonical eligible set. -- [Release Management](../release-management/design.md) — the release a merge triggers. +- [Release Management](../release-management/design.md) — the release a merge triggers on an invoked route. - [Branching and Merging](../../Ways-of-Working/Branching-and-Merging.md) — pull-request-only integration and readable history. diff --git a/src/docs/Capabilities/release-management/design.md b/src/docs/Capabilities/release-management/design.md index ff0a24f..b55178b 100644 --- a/src/docs/Capabilities/release-management/design.md +++ b/src/docs/Capabilities/release-management/design.md @@ -6,9 +6,26 @@ description: How release management is built — a shared reusable workflow that # Release Management — Design The behaviour in the [spec](spec.md) is delivered by a **shared reusable release -workflow**. A repository opts in with a short caller workflow and a small -`.github/release.config.yml`. The workflow supplies the shared mechanics; an -explicit label or an intentionally configured default supplies the release level. +workflow**. A repository opts a target route in with a short caller workflow. +The optional `.github/release.config.yml` file refines that invocation; it does +not opt a route in, and its absence does not opt an invoked route out. The +workflow supplies the shared mechanics; an explicit label or an intentionally +configured default supplies the release level. + +## Applicability + +Inspect the effective workflow configuration for the pull request's target +route before reading release settings or labels. + +- When the route invokes the shared Release Management workflow, evaluate its + release decision and require the configured pre-merge check. This remains true + when `.github/release.config.yml` is absent. +- When the route does not invoke the workflow, Release Management does not + apply. Omit the `Release decisions` block and every `release:*` label, + including `release:skip`. + +Configuration can change branch types, paths, a default bump, and other release +behavior only after the invocation establishes that the route is managed. ## Branching model @@ -71,10 +88,11 @@ Two consequences follow, and they are the point of the model: ## Version computation -For PR-driven releases, the shared resolver reads the owned labels and optional -`DefaultBump` in `.github/release.config.yml`. The setting accepts `patch`, -`minor`, or `major`; omitting it does not supply a level. For example, this -configuration explicitly chooses patch releases when no bump label is provided: +For PR-driven releases on an invoked route, the shared resolver reads the owned +labels and optional `DefaultBump` in `.github/release.config.yml`. The setting +accepts `patch`, `minor`, or `major`; omitting the file or field does not supply a +level and does not skip evaluation. For example, this configuration explicitly +chooses patch releases when no bump label is provided: ```yaml # .github/release.config.yml @@ -120,6 +138,24 @@ Resolve the decision in this order: - The tag is created on the commit now at the head of the release branch — squash, merge-commit, and rebase strategies alike. +### Pull request decision record + +After inspecting the complete change, an author on an invoked route records the +human-readable decision in the conditional `Release decisions` block from [PR +Format](../../Ways-of-Working/PR-Format.md#record-release-decisions-only-when-invoked). +The block and the effective resolver inputs must agree: + +- `Release: Yes` states why the change affects the artifact or a supported + consumer contract, then records `Version bump`, `Mode`, and `Labels`. +- `Release: No` states the no-release evidence and reports only + `release:skip`. +- `Labels` names the exact applied `release:*` labels. Use `None` when a valid + configured default supplies a release level without an override label. + +The resolver still reads labels and configuration as its machine inputs; the +block makes the reviewed decision and its evidence visible. A route without an +invocation has neither the block nor any `release:*` labels. + ### Required pre-merge decision check PR CI runs the resolver read-only against the candidate release settings and @@ -128,12 +164,13 @@ An existing version-resolution check may own this validation; do not duplicate the resolver. The check reports the effective decision and its source, not a promised final stable version. -The validator runs for every PR targeting a release branch, including changes -that will not publish. It re-runs when source, release labels, or release settings -change, so a stale result is not evidence for different inputs. Missing, -invalid, or conflicting decisions produce a failed check with an actionable -error. A valid skip reports success with a no-release result; path filters do -not skip the validator. +The validator runs for every PR targeting an invoked release route, including +changes that will not publish and invoked repositories without a release +configuration file. It re-runs when source, release labels, release settings, or +the effective workflow invocation changes, so a stale result is not evidence for +different inputs. Missing, invalid, or conflicting decisions produce a failed +check with an actionable error. A valid skip reports success with a no-release +result; path filters do not skip the validator. Configure the check's exact name as required in the protected branch's ruleset or branch protection, following [Merge Automation](../merge-automation/spec.md). @@ -182,13 +219,13 @@ either: rerun the existing release with the same artifact and version under the ## Path filtering -`.github/release.config.yml` declares `release-paths` as ordered include/exclude -globs (excludes win). The workflow **always runs** so validation executes on -every merge; only the release step is skipped when no artifact-affecting path -changed. +When present, `.github/release.config.yml` declares `release-paths` as ordered +include/exclude globs (excludes win). On an invoked route, the workflow +**always runs** so validation executes on every merge; only the release step is +skipped when no artifact-affecting path changed. Derive these paths from the delivered product and its -[audience-facing contracts](../../Ways-of-Working/PR-Format.md#detecting-the-change-type), +[audience-facing contracts](../../Ways-of-Working/PR-Format.md#identify-the-readers), not directory names alone. Include callable workflows and build configuration that changes delivered runtime requirements or behavior. Do not retain an exclusion that overrides an included consumer interface or artifact input. @@ -207,20 +244,22 @@ release-paths: The GitHub Release **name** is the resolved version. Its **body** preserves the release-bound PR title and complete description, using -[PR Format](../../Ways-of-Working/PR-Format.md#description-structure) as the -authoring contract. Summary, user-facing changes, adoption, release impact, -consumer change records, template evidence, and both ending details blocks stay -intact. There is no parallel JSON/YAML contract and no extraction of only the -user-facing headings. +[PR Format](../../Ways-of-Working/PR-Format.md#write-the-description) as the +authoring contract. The concise summary, shareable-summary marker, non-empty +classified change sections, reader-facing prose, section-scoped `Technical +details` and `Related references`, and conditional `Release decisions` block +stay intact. There is no parallel JSON/YAML contract and no extraction of only +selected headings or evidence blocks. ### Bind the note to the released source 1. **Resolve the evidence with the version.** Identify the release-bound PR or ad hoc context and the immutable source to build. Resolve the version base - and the source comparison baseline; confirm that the consumer record - describes that delta. Capture the applicable title and complete body together - with the PR URL or context reference, source identity, and snapshot time. - Retain that snapshot as release evidence. + and the source comparison baseline; confirm that each applicable change + section's technical details describe and support that delta. Capture the + applicable title and complete body together with the PR URL or context + reference, source identity, and snapshot time. Retain that snapshot as + release evidence. 2. **Keep identity separate from authored prose.** Resolve the actual publication coordinates through the existing version pipeline, not a number assigned by the PR author. Carry them and the snapshot through Build and Test with the @@ -246,10 +285,10 @@ release note: Version base and change baseline can differ, particularly for prereleases and bundled promotion. Recording both avoids presenting a versioning calculation as -proof of the code a consumer crosses. The target template identity and -compatibility evidence come from the authored record; a publisher does not -substitute the latest template or infer historical compatibility from current -documentation. +proof of the code a consumer crosses. When a result affects an integration +template, its identity and compatibility evidence come from that result's +technical details; a publisher does not substitute the latest template or infer +historical compatibility from current documentation. ### Release-bound records @@ -257,13 +296,13 @@ documentation. | --- | --- | | Single merged PR | That PR's complete title and description, reconciled with the resolved source comparison. | | Bundled release | The release-bound integration PR covers every bundled delta from the declared change baseline, not just the most recent feature PR. It links the contributing work as supporting evidence. | -| Optional ad hoc dispatch | Complete reviewed release-note context with the same adoption, consumer-change, template, and release-impact evidence. Record the dispatch source and reason; do not create or imply an empty PR. | +| Optional ad hoc dispatch | Complete reviewed release-note context with the same classified structure and applicable result-specific evidence. Record the dispatch source and reason; do not create or imply an empty PR. | | Prerelease | The PR or integration record appropriate to that published source, captured for that release. Later edits to the final PR do not overwrite the prerelease snapshot or attribute unreleased behavior to it. | If the relationship between a record and its source cannot be established, stop the affected publication and register the evidence gap. The process does -not substitute the newest note, guess a baseline, or treat an empty adoption -section as a no-action result. +not substitute the newest note, guess a baseline, or treat a missing applicable +technical-details block as a no-action result. ### Correct published metadata without changing history @@ -379,9 +418,10 @@ release, and its runs are serialised like any other. | Surface | Where | | --- | --- | -| Release branches + type | `.github/release.config.yml` | +| Release Management applicability | target-route caller workflow invoking the shared Release Management workflow | +| Release branches + type | optional `.github/release.config.yml`; the default branch is stable when omitted | | Optional default bump | `DefaultBump` in `.github/release.config.yml` | -| Explicit bump / prerelease / skip | `release:` PR label | +| Explicit bump / prerelease / skip | `release:` PR label on an invoked route | | Pre-merge decision validation | named PR check required by the branch ruleset or protection | | Optional ad hoc release | `workflow_dispatch` inputs | | Path filter | `.github/release.config.yml` | diff --git a/src/docs/Capabilities/release-management/spec.md b/src/docs/Capabilities/release-management/spec.md index 67579fd..d9f6680 100644 --- a/src/docs/Capabilities/release-management/spec.md +++ b/src/docs/Capabilities/release-management/spec.md @@ -13,6 +13,11 @@ releasing. Releasing MUST be automatic, predictable, and driven entirely on the GitHub platform — a contributor focuses on the code they contribute, not a release CLI, a hand-edited version file, or a tagging convention. +A target route participates in this capability only when it invokes the shared +Release Management workflow. That invocation is authoritative: the optional +`.github/release.config.yml` file refines an invocation but does not create one, +and its absence does not opt an invoked route out. + ### Principles This capability rests on the [Principles](../../Ways-of-Working/Principles/index.md): @@ -23,25 +28,28 @@ This capability rests on the [Principles](../../Ways-of-Working/Principles/index ## Scope -Applies to any repository that produces a versioned artifact on merge to a -release branch. One test decides applicability: **does merging produce a -versioned, immutable output that something else consumes by version?** If yes, -this capability governs the release. If no, there is nothing to release. +Applies to a target route that invokes Release Management to produce a versioned +artifact. One product test decides whether a route should opt in: **does merging +produce a versioned, immutable output that something else consumes by version?** +If yes, configure the invocation. If no, there is nothing to release and the +pull request carries neither the `Release decisions` block nor `release:*` +labels. ## Requirements - **Semantic versioning.** Versions follow [SemVer 2.0.0](https://semver.org/) (`vMAJOR.MINOR.PATCH`), derived automatically — never written by hand. +- **Invocation determines applicability.** Release Management MUST evaluate every pull request targeting a route that invokes its shared workflow, including when `.github/release.config.yml` is absent. A route without that invocation MUST NOT require, apply, or report the `Release decisions` block or any `release:*` label. - **A resolved PR release decision.** The repository MAY configure `DefaultBump` as `patch`, `minor`, or `major`; invalid values MUST fail. Multiple owned bump labels, or `release:skip` combined with another owned release label, MUST fail. A valid `release:skip` MUST select no release without resolving a bump. For publishing decisions, one owned `release:patch`, `release:minor`, or `release:major` label MUST take precedence over the configured default; without a bump label, a valid `DefaultBump` MUST supply the level; without either source, automation MUST fail with a missing-decision error, never assume `patch`. `release:pre-release` MAY use either the explicit or configured bump; the mode alone does not supply a level. Bare or unrelated labels MUST be ignored. Conventional commit messages are **not** required. -- **A release per merge.** One eligible merged PR with a resolved bump to a release branch is one release, and the PR review gate is the release gate. `release:skip` validates without publishing. This pull-request path is the required release interface. -- **Decision validation blocks merge.** Every PR targeting a release branch MUST receive a named release-decision CI check required by the branch ruleset or protection. Missing decisions, invalid defaults, and conflicting owned labels MUST fail that check before merge, not only during publication. Source, release-label, and release-settings changes MUST re-evaluate the decision. A failing, pending, or absent required result MUST block both manual and automated merge; a log message, warning, or skipped validator is not enforcement. A valid `release:skip` MUST report a successful no-release decision, not skip the check. +- **A release per merge.** One eligible merged PR with a resolved bump to an invoked release route is one release, and the PR review gate is the release gate. `release:skip` validates without publishing. This pull-request path is the required release interface. +- **Decision validation blocks merge.** Every PR targeting an invoked release route MUST receive a named release-decision CI check required by the branch ruleset or protection. Missing decisions, invalid defaults, and conflicting owned labels MUST fail that check before merge, not only during publication. Source, release-label, and release-settings changes MUST re-evaluate the decision. A failing, pending, or absent required result MUST block both manual and automated merge; a log message, warning, or skipped validator is not enforcement. A valid `release:skip` MUST report a successful no-release decision, not skip the check. - **Ad hoc release is optional.** An implementation MAY expose `workflow_dispatch` when its product needs an ad hoc release outside the merge flow; implementations are not required to support it. A dispatch MUST require an explicit release decision and release-note context, and MUST use the same version, build, validation, immutability, and publication controls as a merged pull request. A direct push MUST NOT be an ad hoc release interface, and an empty pull request MUST NOT be created solely to trigger a release. - **Version before build.** The version MUST be resolved before the artifact is built, so the version is part of the artifact's identity rather than a label attached afterwards. - **Build once.** The artifact MUST be built exactly once and MUST NOT be altered after it is built. The same bytes flow through validation and publishing. Rebuilding to publish means the tested artifact and the published artifact are different artifacts. - **Stable and prerelease.** Every release is either **stable** (the latest version to adopt) or a **prerelease** (testable, not promoted to latest). A prerelease MUST be obtainable from an open pull request carrying `release:pre-release`, using its explicit or configured bump, and/or from a prerelease branch. - **Serialised releases.** Only one release process runs against a given version of the codebase (the same ref) at a time. A release mutates shared, version-anchored state — the tag, the version counter, the published artifact — so overlapping runs on the same ref MUST NOT race, and an in-flight release is never interrupted. - **A single production authority.** Exactly one branch is in charge of the production (stable) version, so consumers get one unambiguous latest stable release and two branches can never publish competing production releases. -- **Notes from the contributor's own words.** The GitHub Release name is the version; its body MUST preserve the release-bound pull request title and complete description, or equivalent complete release-note context for an optional ad hoc dispatch. The authored record follows [PR Format](../../Ways-of-Working/PR-Format.md#description-structure); adoption and technical details MUST NOT be omitted or summarized away. -- **Only artifact-affecting changes release.** A change that does not affect the delivered artifact or its supported consumer contracts MUST carry `release:skip` and MUST NOT produce a release — though validation still runs on every merge. Documentation and internal CI configuration qualify only when they meet that condition. An Action or reusable workflow is itself a product for its callers; its interface and behavior MUST NOT be dismissed as internal tooling because of the file path. +- **Notes from the contributor's own words.** The GitHub Release name is the version; its body MUST preserve the release-bound pull request title and complete description, or equivalent complete release-note context for an optional ad hoc dispatch. The authored record follows [PR Format](../../Ways-of-Working/PR-Format.md#write-the-description); classified results and their section-scoped technical details and related references MUST NOT be omitted or summarized away. +- **Only artifact-affecting changes release.** On an invoked release route, a change that does not affect the delivered artifact or its supported consumer contracts MUST carry `release:skip` and MUST NOT produce a release — though validation still runs on every merge. Documentation and internal CI configuration qualify only when they meet that condition. An Action or reusable workflow is itself a product for its callers; its interface and behavior MUST NOT be dismissed as internal tooling because of the file path. - **Immutable references.** Consumers pin to the most immutable reference available — a container digest or a commit SHA — never a mutable tag. - **Publish through a target contract.** Every publishing destination is reached through the same [publishing-target contract](design-publishing-targets.md), so the release process stays one process regardless of how many destinations a repository has. Adding a destination supplies a contract and a publish step; it MUST NOT change the release process. - **All-or-nothing across targets.** Where a repository publishes one artifact to more than one destination, a version MUST NOT end up present on some destinations and absent from others. Partial publication is a failure, reported as one, and resumed by completing the remaining destinations with the same immutable artifact and version. @@ -50,7 +58,8 @@ this capability governs the release. If no, there is nothing to release. ### Release evidence -- **Incremental consumer contract.** Every release MUST describe its consumer-facing delta against an identified release/source baseline, including applicability, exact actions, and verification, or explicit no-action evidence. Breaking behavior MUST be documented independently of its semantic-version classification. An applicable integration template MUST be identified by repository and verified compatible immutable commit, with producer-source compatibility evidence and linked template work or a justified no-change result. +- **Evidence stays with the result it supports.** Evidence MUST appear in the applicable change classifier's section-scoped `Technical details` block after the reader-facing prose. A single global consumer, template, or maintainer evidence block MUST NOT substitute for result-specific evidence. +- **Incremental consumer contract.** When a result changes a consumer contract, its technical details MUST identify the release/source baseline and describe applicability, exact actions, and verification. Breaking behavior MUST be explicit independently of its semantic-version classification. When an integration template is affected, identify its repository and verified compatible immutable commit, with producer-source compatibility evidence and linked template work or a justified no-change result. - **Resolved coordinates.** The release process MUST record the actual target version, tag, immutable source and artifact identity, effective release decision and its source, version-computation base, and consumer-change baseline. The version base and change baseline MUST be distinguished when they differ. A first release MUST identify its initial versioning baseline and lack of a prior release. Authors MUST NOT assign a final version before resolution. - **Traceable publication.** Generated identity and provenance MAY surround the authored note as a distinct envelope; they MUST NOT replace or rewrite it. The release MUST retain the note's source identity and snapshot provenance so its relationship to the published code is inspectable. Every destination carrying release notes, including downstream propagation, MUST receive the complete record. - **Correct release scope.** A bundled release's integration PR MUST cover every bundled consumer delta. An optional ad hoc release MUST provide equivalent evidence without implying a nonexistent PR. A prerelease MUST preserve the note appropriate to its immutable published source, not a later final-PR description that describes different code. @@ -73,18 +82,19 @@ Because versions are semantic, immutable, and published once, a consumer can ado ## Success criteria - Merging an eligible PR with an explicit or configured bump produces a GitHub Release, a git tag, and (where one exists) a published artifact, with no manual step. +- A pull request targeting an invoked release route is evaluated even when `.github/release.config.yml` is absent; a pull request targeting a route without an invocation carries no release decision block, label, or check. - For a publishing PR, an explicit owned bump label overrides the configured default; without that label, a valid `DefaultBump` supplies the level and is recorded as its source. - A PR with no explicit level, configured default, or valid no-release decision fails the required decision check and cannot merge. Invalid defaults and conflicting owned labels also block merge rather than selecting a fallback. - Removing the only decision source or changing its inputs re-evaluates the PR check; a prior result does not validate different inputs. - An open pull request carrying `release:pre-release` and an explicit or configured bump publishes a prerelease without promoting it to latest. - The artifact that consumers download is byte-identical to the artifact that passed validation. -- A documentation-only merge carrying `release:skip` produces no new version but still runs its CI checks. +- On an invoked release route, a documentation-only merge carrying `release:skip` produces no new version but still runs its CI checks. - Two release runs for the same ref never overlap; the second waits for the first to finish rather than racing it. - Only the single production branch ever publishes a stable release. - A version that reaches one publishing target reaches all of them, or the release is reported as failed. - Every release is linkable and records its immutable artifact reference. -- The published authored title and body match the release-bound snapshot in full, including adoption, consumer/template evidence, and maintainer details. -- A consumer can identify the actual target, version base, change baseline, and any applicable compatible template without relying on a moving branch, alias, or today's documentation. +- The published authored title and body match the release-bound snapshot in full, including every classified result and its section-scoped technical details and related references. +- Where a result affects consumers or an integration template, a consumer can identify the actual target, version base, change baseline, and compatible template without relying on a moving branch, alias, or today's documentation. - A bundled or ad hoc note covers its complete change range, and a prerelease note never gains instructions for code absent from that prerelease. - A published-note correction is traceable to released-source evidence while all artifact and source identities remain unchanged. @@ -94,5 +104,5 @@ Because versions are semantic, immutable, and published once, a consumer can ado - [Publishing Targets](design-publishing-targets.md) — the contract each destination documents. - [Documentation Model](../../Ways-of-Working/Documentation-Model.md) — why this spec holds only the why and the what. - [Automation Labels](../../Ways-of-Working/Automation-Labels.md) — why release labels are owned by the `release:` namespace. -- [PR Format](../../Ways-of-Working/PR-Format.md) — the change-type labels that drive the bump. +- [PR Format](../../Ways-of-Working/PR-Format.md) — the authored release record and conditional release-decision block. - [Dependency Updates](../dependency-updates/spec.md) — update PRs are artifact-affecting and release through this capability. diff --git a/src/docs/Coding-Standards/Dependencies.md b/src/docs/Coding-Standards/Dependencies.md index 8d106de..bc83265 100644 --- a/src/docs/Coding-Standards/Dependencies.md +++ b/src/docs/Coding-Standards/Dependencies.md @@ -44,7 +44,7 @@ The resolution is not to pick a point and freeze — it is to **control integrit 1. **Pin tightly by default** — an identity pin plus a deliberate version, or a lockfile — so every build is reproducible and nothing changes unvetted. A controlled owned-major tag is the narrow exception for automation whose release path the organization or initiative operates. 2. **Automate updates** so currency never depends on a human watching upstream: the [Dependency Updates](../Capabilities/dependency-updates/index.md) bot opens one reviewed pull request per bump. -3. **Gate every update through CI and review** — every update passes the repository's normal merge policy; security advisories are raised out of band and prioritized. After related changes are collected, decide the repository release bump under [Release Management](../Capabilities/release-management/design.md). +3. **Gate every update through CI and review** — every update passes the repository's normal merge policy; security advisories are raised out of band and prioritized. After related changes are collected, resolve the repository release decision under [Release Management](../Capabilities/release-management/design.md) when the target route invokes it. Tight pinning is safe *because* the updates are automated: the bot closes the currency gap and CI plus review close the vetting gap. A controlled owned-major tag applies the same principle at the producer: compatible releases pass the controlled release gate once, then the major pointer rolls them out centrally. It trades consumer-level reproducibility for coordinated rollout and is never valid for an external dependency. diff --git a/src/docs/Coding-Standards/GitHub-Actions.md b/src/docs/Coding-Standards/GitHub-Actions.md index dc8c22e..347e8cb 100644 --- a/src/docs/Coding-Standards/GitHub-Actions.md +++ b/src/docs/Coding-Standards/GitHub-Actions.md @@ -67,7 +67,8 @@ a fleet of pin-update pull requests. version comment. - **Apply the updater's default three-day cooldown** before adopting a freshly published version. Omit an explicit `cooldown` mapping unless the repository deliberately adopts a non-default duration. - **Make the release decision separately** after dependency changes are - collected, under [Release Management](../Capabilities/release-management/design.md). + collected when the target route invokes [Release + Management](../Capabilities/release-management/design.md). - **Publish owned floating major tags only through controlled release automation.** The release gate validates compatibility, publishes the immutable version tag first, and then advances the major tag to that stable release. diff --git a/src/docs/Coding-Standards/Natural-Language.md b/src/docs/Coding-Standards/Natural-Language.md index 1e25a7e..af53fc3 100644 --- a/src/docs/Coding-Standards/Natural-Language.md +++ b/src/docs/Coding-Standards/Natural-Language.md @@ -33,7 +33,7 @@ The split is per artifact, not per repository. A repository that serves a Norweg | `scripts/Test-Link.mjs` | `scripts/Test-Lenker.mjs` | | `Update-Source.ps1 -Offline` | `Update-Source.ps1 -Frakoblet` | | `Source not found: ` | `Kilden finnes ikke: ` | -| `🪲 [Fix]: Broken links no longer reach main` | `🪲 [Fix]: Brutte lenker stoppes` | +| `Broken links no longer reach main` | `Brutte lenker stoppes` | Repository artifacts are read by contributors, reviewers, and agents who do not share one first language, and by tooling built for English. Mixed-language automation splinters the vocabulary — `-Frakoblet` and `-Offline` are the same switch — and makes shared standards, linters, and scripts unreusable across repositories. @@ -76,7 +76,7 @@ Prefer specific, observable language over vague intent. | Prefer | Avoid | | --- | --- | | The workflow fails when the release decision is missing. | There may be some issues with labels. | -| Add `release:skip` to documentation-only PRs. | Make sure docs PRs are handled correctly. | +| On a release-managed route, add `release:skip` when documentation does not affect the artifact. | Make sure docs PRs are handled correctly. | | The agent reads `AGENTS.md` before editing files. | The agent should probably look at the instructions. | Use **MUST**, **SHOULD**, and **MAY** only when a sentence is intentionally normative. If a rule is optional, say what trade-off decides it. @@ -154,7 +154,7 @@ A good error message includes: Prefer: ```text -Release decision is missing. Add a release:patch, release:minor, or release:major label, configure DefaultBump in the release settings, or select release:skip. Prerelease mode still requires a resolved bump. This required CI check must pass before merge. +Release decision is missing for this release-managed route. Add a release:patch, release:minor, or release:major label, configure DefaultBump in .github/release.config.yml, or select release:skip. Prerelease mode still requires a resolved bump. This required CI check must pass before merge. ``` Avoid: @@ -169,10 +169,11 @@ PR titles and descriptions are written for the user of the change first, then th | Prefer | Avoid | | --- | --- | -| `📖 [Docs]: Agentic development framework documented` | `Update framework docs` | +| `Agentic development guidance defines the framework` | `Update framework docs` | | `Agents segment project context before loading standards.` | `Refactor AGENTS.md instructions.` | -Technical implementation details belong in a clearly named technical section at the bottom of the PR body. +Technical implementation details belong in the `Technical details` block for +the reader-facing result they support. ## Prompts diff --git a/src/docs/Ways-of-Working/Automation-Labels.md b/src/docs/Ways-of-Working/Automation-Labels.md index 83b792a..6840093 100644 --- a/src/docs/Ways-of-Working/Automation-Labels.md +++ b/src/docs/Ways-of-Working/Automation-Labels.md @@ -56,6 +56,12 @@ namespaced, including the release set: | `release:pre-release` | Publish a prerelease from the open pull request. | | `release:skip` | Validate the change without publishing a release. | +This set applies only when the pull request's target route invokes Release +Management. A route without that invocation does not apply or report any +`release:*` label, including `release:skip`. The optional +`.github/release.config.yml` file refines an invocation; its absence alone does +not determine whether the route invokes the capability. + These labels are read by [release management](../Capabilities/release-management/spec.md) and by nothing else. One owned bump label records an explicit level and overrides the optional diff --git a/src/docs/Ways-of-Working/Branching-and-Merging.md b/src/docs/Ways-of-Working/Branching-and-Merging.md index cc2bdf6..140c455 100644 --- a/src/docs/Ways-of-Working/Branching-and-Merging.md +++ b/src/docs/Ways-of-Working/Branching-and-Merging.md @@ -35,7 +35,7 @@ Every layer follows the ordinary [Contribution Workflow](Contribution-Workflow.m 1. **Plan the dependency.** Give each layer its own Task or Bug issue. Add a native blocked-by edge from every dependent leaf to its prerequisite as described in [Issue Relationships](Issues/Process/Relationships.md#execution-order); prose, sub-issue order, and stack position do not create the gate. 2. **Open every layer as a draft.** After the initial commit, push the branch and open its pull request immediately. Use the standard user-facing title and description from [PR Format](PR-Format.md); do not add stack position or an internal branch name to the title. -3. **Link the stack in Technical Details.** Add fully qualified pull request links for the immediate dependency and dependent, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task or Bug. +3. **Link the stack in Related references.** Add fully qualified pull request links for the immediate dependency and dependent to the applicable section's `Related references` block, using `Depends on Owner/Repo#N` and `Followed by Owner/Repo#N`. Each pull request closes only its own Task or Bug. 4. **Keep each delta isolated.** The pull request diff against its current base contains only that layer's change. Run its tests, checks, and automated review even when an earlier layer already exercised the combined code. 5. **Make one layer ready at a time.** Only the lowest unmerged layer is marked ready and given auto-merge. Every later layer stays draft, even when its current checks are green. 6. **Advance after merge.** When the lowest layer lands, refresh the next branch against the landed target, retarget its pull request to that target, and verify that the diff still contains only its intended change. Run CI and the automated review loop again before marking it ready. @@ -59,7 +59,7 @@ A repository on the promotion model MAY keep a **standing draft pull request** f - **One long-lived pull request, not one per promotion.** Merging it promotes; a new draft opens immediately, so the candidate view is never absent. - **Draft is the resting state.** It is marked ready when the integrated state is deemed promotable, which is what turns review and any promotion gate on. - **Its description is the promotion note.** Assembled from the changes it carries, it is the record of what a promotion contained, written for whoever operates the destination. -- **Its resolved release decision determines the production version.** Promotion is a release like any other, so the level comes from this pull request's explicit bump label or the configured repository default, not from the versions of the changes it bundles ([release management](../Capabilities/release-management/spec.md)). +- **Its release metadata follows the target route.** When the route invokes [Release Management](../Capabilities/release-management/spec.md), the pull request's `Release decisions` block records the production decision and the level comes from its explicit bump label or the configured repository default, not from the versions of the changes it bundles. A route without that invocation omits the block and all `release:*` labels. The value is continuous visibility: at any moment, the difference between what is integrated and what is live is one link. It suits repositories where promotion is a deliberate, gated event and costs more than it returns where every merge already ships. diff --git a/src/docs/Ways-of-Working/Contribution-Workflow.md b/src/docs/Ways-of-Working/Contribution-Workflow.md index 9809968..1cd8f4e 100644 --- a/src/docs/Ways-of-Working/Contribution-Workflow.md +++ b/src/docs/Ways-of-Working/Contribution-Workflow.md @@ -34,10 +34,15 @@ flowchart TD that delivery issue and the pull request, not in the spec, design, or parent aggregate. 2. **Open the pull request as a draft.** A draft attaches CI and keeps the change - out of people's review queues while you iterate. + out of people's review queues while you iterate. Assign the pull request to + its author and apply any repository-owned workflow labels. 3. **Run the Copilot review loop** (below) until Copilot reports a clean round — no changes requested and no new inline comments. -4. **Mark the pull request ready for review** once it meets the +4. **Finalize and mark the pull request ready for review.** Re-read the complete + diff and finalize the title and description per [PR Format](PR-Format.md). + If the target route invokes Release Management, reconcile the conditional + decision block and `release:*` labels with its effective configuration. If it + does not, omit both. Then confirm the [Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review). 5. **Enable auto-merge** so the change lands automatically when human review approves and the required checks stay green. Human review takes over from there. @@ -121,7 +126,8 @@ the approval identity that satisfies the gate. - [Workflow](Workflow.md) — the spec-led loop this operates within. - [Issue Lifecycle](Issues/Process/Lifecycle.md) — why only ready Task and Bug leaves enter this flow. -- [PR Format](PR-Format.md) — the pull request title, description, and labels. +- [PR Format](PR-Format.md) — the pull request title, description, and + route-conditional release metadata. - [Definition of Ready and Done](Definition-of-Ready-and-Done.md#definition-of-ready-for-review) — the readiness gate this hands off at. - [Branching and Merging](Branching-and-Merging.md) — the branch model a pull request builds on. - [Review Etiquette](Review-Etiquette.md) — how human review proceeds once the pull request is ready. diff --git a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md index c68b48b..a74d9d1 100644 --- a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md +++ b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md @@ -33,7 +33,7 @@ A pull request is ready for review when: - The automated review loop has converged — a clean [Copilot round](Contribution-Workflow.md#the-copilot-review-loop) with no unresolved review threads. - The [standards and framework alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass) has run against the finished change, its result covers every changed surface in the pull request, and every exception links a follow-up issue. - The [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) has run against scoped open issues, and every fully convergent issue is linked in the pull request with a closing keyword. -- The title, release-note description, and effective release decision and its source are finalized per [PR Format](PR-Format.md). Where Release Management applies, its [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) passes; an explicit label is not mandatory when a valid configured default supplies the level. +- The title and release-note-ready description are finalized per [PR Format](PR-Format.md). When the target route invokes Release Management, the `Release decisions` block, effective configuration, and applied `release:*` labels agree, and the [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) passes; an explicit bump label is not mandatory when a valid configured default supplies the level. When the route does not invoke Release Management, the block and labels are absent. Absent checks are not a pass. When a pull request reports no checks at all, the usual cause is that the workflow's triggers do not cover it — a base branch outside the `pull_request` trigger's `branches` filter is the common one — and that is a gap to fix or file, not a gate to wave through. Manually dispatching the workflow against the branch does not substitute for it either: jobs gated on the event type are skipped silently, so a green `workflow_dispatch` run can hide verification that never ran. If the checks genuinely cannot be made to run before merge, say so in the pull request and link the issue tracking it, so the reviewer knows the gate was not met instead of assuming it was. diff --git a/src/docs/Ways-of-Working/Fleet-Orchestration.md b/src/docs/Ways-of-Working/Fleet-Orchestration.md index ed34da6..bff9a8f 100644 --- a/src/docs/Ways-of-Working/Fleet-Orchestration.md +++ b/src/docs/Ways-of-Working/Fleet-Orchestration.md @@ -36,7 +36,9 @@ tool, can read and drive a campaign with the GitHub CLI alone. A campaign is one change rolled out across a set of repositories. Each repository's slice is one Task or Bug delivery leaf and its pull request. A campaign has a short, stable **slug** (for example `process-psmodule-v6`) that -names both artifacts everywhere. +prefixes every delivery issue. A campaign pull request carries that identity +through its native closing reference to the prefixed issue, leaving the pull +request title free for its reader-facing result. An **existing open pull request can be adopted** when its scope matches the campaign slice. Ensure it closes exactly one correctly typed Task or Bug, @@ -71,12 +73,13 @@ copied into another state-bearing field, because duplicated state drifts. signals people care about most are native, and are set by the same act that does the work — [marking ready](Contribution-Workflow.md) and merging. -### Campaign identity lives in the title +### Campaign identity lives on the delivery issue Campaign membership is carried in a stable square-bracket prefix on every -delivery issue and pull request title, for example `[process-psmodule-v6]`. The -prefix is the cross-repository join key; labels stay reserved for mutable -workflow state. +delivery issue title, for example `[process-psmodule-v6]`. Each campaign pull +request closes exactly one of those issues, so the native closing reference +joins the pull request to the campaign without copying internal metadata into +its title. Labels stay reserved for mutable workflow state. ### Process labels fill the gap @@ -91,11 +94,13 @@ same way. | `stage:in-progress` | Actively being changed; the assignee owns it. | | `stage:blocked` | Needs a human decision or a manual, off-platform action before it can proceed. | -Rules: the campaign prefix is mandatory on every delivery issue and pull request; at most one -`stage:*` label applies at a time; and `stage:*` may be dropped once a pull -request carries the signal itself (a ready pull request needs no `stage` label, -but `stage:blocked` stays explicit because "a human must act" has no built-in -equivalent). The slug inside the prefix is lowercase and hyphenated. +Rules: the campaign prefix is mandatory on every delivery issue; each campaign +pull request closes one prefixed issue and uses the reader-facing title from [PR +Format](PR-Format.md) without the prefix; at most one `stage:*` label applies at +a time; and `stage:*` may be dropped once a pull request carries the signal +itself (a ready pull request needs no `stage` label, but `stage:blocked` stays +explicit because "a human must act" has no built-in equivalent). The slug inside +the issue prefix is lowercase and hyphenated. ## Effective status @@ -135,21 +140,21 @@ flowchart TD ``` 1. **Queue the work.** Create one Task or Bug delivery issue per repository, with - the campaign prefix in the title and `stage:queued`. Route it through the - [Issue Hierarchy](Issues/Types/Hierarchy.md) and follow its canonical type - page. The whole fleet starts as *Queued*. + the campaign prefix in the title and `stage:queued`. Route it through the + [Issue Hierarchy](Issues/Types/Hierarchy.md) and follow its canonical type + page. The whole fleet starts as *Queued*. 2. **Branch and open a draft.** Create a worktree and branch ([Git Worktrees](Git-Worktrees.md)), then open a **draft** pull request that - closes exactly that delivery issue, per [PR Format](PR-Format.md). Use the same - campaign prefix in the pull request title and move the stage to - `stage:in-progress`, clearing the issue's `stage:queued` so the repository - delivery never carries two stages at once. If the repository already has an open - pull request that covers part of the change, adopt it instead of opening a - new one: add the remaining change to its branch, return it to **draft** while - work is in progress, and give it the same campaign prefix and - `stage:in-progress` label (clearing `stage:*` from its closing issue). Add the - one closing Task or Bug reference before continuing if the adopted pull - request did not already have it. + closes exactly that prefixed delivery issue, per [PR Format](PR-Format.md). + The closing reference carries campaign membership, so the pull request title + states only its reader-facing result. Move the stage to `stage:in-progress`, + clearing the issue's `stage:queued` so the repository delivery never carries + two stages at once. If the repository already has an open pull request that + covers part of the change, adopt it instead of opening a new one: add the + remaining change to its branch, return it to **draft** while work is in + progress, and give it `stage:in-progress` (clearing `stage:*` from its closing + issue). Add the one closing reference to the prefixed Task or Bug before + continuing if the adopted pull request did not already have it. 3. **Apply the change and run the loop.** Make the change and take the pull request through the [Contribution Workflow](Contribution-Workflow.md) — the Copilot review loop — exactly as any single-repository change. The @@ -215,10 +220,11 @@ identical diff. A campaign is watched through a **dashboard** — a deterministic projection of GitHub state, not a store of its own. A script enumerates the campaign's -repository deliveries by title prefix (`[]` across the owners), reads each pull request's -built-in properties, computes the effective status, and renders a page. It can -regenerate on an interval so the view refreshes as GitHub changes; deleting it -loses nothing, because GitHub is the source of truth. +delivery issues by title prefix (`[]` across the owners), follows each +native closing reference to its pull request, reads the built-in properties, +computes the effective status, and renders a page. It can regenerate on an +interval so the view refreshes as GitHub changes; deleting it loses nothing, +because GitHub is the source of truth. Typical columns: effective status, repository, delivery issue and pull request, draft/ready, CI, review decision and open-thread count, assignee, the latest progress note, @@ -244,11 +250,12 @@ a deterministic label-and-comment write, so it is scripted; the judgement of Because all state is on GitHub and the workflow labels are generic: - **A person** can run a whole campaign from the GitHub UI — filter by - the campaign prefix in the title, read each pull request's draft and merge state, move - `stage:*` labels, and merge. + the campaign prefix in delivery issue titles, follow each issue's closing pull + request, read its draft and merge state, move `stage:*` labels, and merge. - **An automated system** — a scheduled workflow, a different agent framework, or - a teammate's tooling — can enumerate the work with one query and pick up any - delivery. The state is portable and self-describing. + a teammate's tooling — can enumerate the issues with one query, follow their + native pull request references, and pick up any delivery. The state is + portable and self-describing. If an automated run stops midway, nothing is lost: the board is complete, every in-flight pull request shows its true state, and anyone can finish the job. This @@ -261,9 +268,12 @@ hand. Labels and comments use the issues API, which serves issues and pull requests alike. ```powershell -# enumerate a campaign's pull requests across an owner -gh search prs 'in:title "[]"' --owner ` - --json number,repository,title,url,isDraft,state +# enumerate a campaign's delivery issues across an owner +gh search issues 'in:title "[]"' --owner ` + --json number,repository,title,url,state + +# follow a delivery issue to its closing pull request +gh issue view --repo / --json closedByPullRequestsReferences # read one pull request's authoritative state gh pr view --repo / --json ` @@ -291,13 +301,15 @@ the Pester version requirement to the test files, and migrate the tests. `#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.0.0'; MaximumVersion = '6.*' }` requirement to each `*.Tests.ps1`, migrate the tests, and take the pull request through the [Contribution Workflow](Contribution-Workflow.md). -- **Track it:** every issue and pull request starts with `[process-psmodule-v6]`; - the dashboard shows the fleet advancing from *Queued* to *Merged*. +- **Track it:** every delivery issue starts with `[process-psmodule-v6]`; each + pull request uses a reader-facing title and closes its prefixed issue. The + dashboard follows those links as the fleet advances from *Queued* to *Merged*. ## What this is not - **Not a database.** Any `JSON` or `HTML` is a disposable projection of GitHub. - **Not agent-specific.** The model stays fully operable by people and non-agent tools; nothing in it depends on a particular assistant. -- **Not a shared label store.** Labels are per-repository; the campaign title - prefix is the shared contract, created in each participating repository. +- **Not a shared label store.** Labels are per-repository; the delivery-issue + prefix plus the native closing reference is the shared contract in each + participating repository. diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md index 72f1174..d95e6ef 100644 --- a/src/docs/Ways-of-Working/PR-Format.md +++ b/src/docs/Ways-of-Working/PR-Format.md @@ -1,321 +1,532 @@ --- title: PR Format -description: Pull request title, description, change types, and labels. +description: Audience-first pull request titles and descriptions with evidence-based, conditional release decisions. --- # PR Format -Pull requests in the MSX ecosystem double as **release notes**. Write for end users, including downstream integrators: what changes, who is affected, and how to adopt it. Keep consumer instructions distinct from reviewer and maintainer evidence. +A pull request title and description are release-note-ready artifacts. They +explain one complete change to the people who use what the repository delivers, +while carrying the evidence reviewers and maintainers need. -## The source of truth +This page owns the title and description format. The +[Contribution Workflow](Contribution-Workflow.md) owns draft, assignment, +review, and handoff mechanics; [Branching and Merging](Branching-and-Merging.md) +owns branches, commits, and integration. -The release-bound PR title and complete description are the authored release note. The contract lives in structured Markdown in that body, not a parallel JSON/YAML file or a version-specific migration guide. [Release Management](../Capabilities/release-management/design.md#release-notes) owns publication, resolved release coordinates, provenance, and traceable corrections. +## Analyze before writing -Describe the **incremental change introduced by this release**, not a migration manual from every previous version. Consumers compose the applicable records across their upgrade range; a note for the newest release does not replace the intervening evidence. +Write from evidence, not from the branch name, commit messages, or the existing +pull request text. Those surfaces are useful leads, but the complete change is +the source. -## Title +### Identify the readers -```text - []: -``` +Start with the repository [README audience +declaration](Readme-Driven-Context.md#target-audience), then inspect linked user +documentation, capability specifications, and effective configuration. -- The **Icon** matches the change type. -- The **Type** in brackets is one of: `Major`, `Feature` (Minor), `Patch`, `Fix`, `Docs`, `Maintenance`. -- The **outcome** describes what changed from the end user's perspective. Do not lead with private function or class names or refactoring verbs; public commands, inputs, APIs, paths, and settings are consumer-facing concepts. +Treat every supported interface as reader-facing when someone depends on it. +Commands, APIs, configuration, reusable workflows, Actions, templates, and +published guidance can all be the product. Do not classify an integration as +internal merely because its readers write scripts or maintain another product. -### Good titles +For documentation-only work, the delivered result is guidance. State what a +reader can now understand or do; do not present documentation as product +behavior that the change did not implement. -- `🌟 [Major]: Legacy export command removed` -- `🚀 [Feature]: Custom templates now supported` -- `🩹 [Patch]: Default timeout value corrected` -- `🪲 [Fix]: Parameter validation no longer fails on null input` -- `📖 [Docs]: Installation guide updated with prerequisites` -- `⚙️ [Maintenance]: Internal build tooling stays current` +### Read the whole change -### Bad titles +Inspect the complete base-to-head diff before writing. For a promotion or +bundled release, inspect the complete promoted range rather than only the latest +commit or pull request. -- `Add support for custom templates` — describes the action, not the outcome. -- `Refactor parameter validation logic` — implementation language. -- `Update stuff` — meaningless. +Check claims against the changed public interfaces, documentation, +configuration, tests, and generated output. Commit messages and an earlier pull +request description may be incomplete or stale and never replace this check. -## Change types +### Keep claims accurate -| Type | Icon | Label | Description | -| ----------- | ---- | ---------------- | ----------------------------------------------------- | -| Major | 🌟 | `release:major` | Breaking changes that affect compatibility | -| Feature | 🚀 | `release:minor` | New features or enhancements | -| Patch | 🩹 | `release:patch` | Small fixes or improvements | -| Fix | 🪲 | `release:patch` | Bugfixes (patch-level release impact) | -| Docs | 📖 | `release:skip` | Documentation changes only | -| Maintenance | ⚙️ | `release:skip` | Internal upkeep with no change to shipped behavior or integration contracts | +State only outcomes the evidence supports: -`release:pre-release` is a release mode, not a change type. It uses one explicit -bump label or the repository's configured `DefaultBump` when an open pull request -must publish a prerelease. The mode alone supplies no level. Never combine it -with `release:skip`; [Release Management](../Capabilities/release-management/design.md#version-computation) -owns resolution and validation. +- Describe a dependency update's behavior or security benefit only when upstream + notes, tests, or product evidence establish that result. +- Describe documentation work as changed guidance unless the same change also + changes the documented product. +- Distinguish a public contract change from the internal implementation that + delivers it. +- Name required user action precisely. Do not imply that no action is needed + without checking the supported interfaces. -### Detecting the change type +### Resolve release decisions -Decide the type from the change **for the declared target audience**, including its integrators, not from the maintainer's implementation effort or the names of changed files. Read the [audience declaration in the README](Readme-Driven-Context.md#target-audience) and any explicitly adopted initiative definition first. Resolve and record missing or ambiguous audience context before finalizing the type; do not guess it from repository ownership. +Before adding release metadata or changing a `release:*` label, determine +whether the repository invokes [Release +Management](../Capabilities/release-management/spec.md) for the pull request's +target route. Inspect the caller workflows and their effective inputs. The +optional `.github/release.config.yml` file refines that invocation; its absence +alone does not prove that release management is absent. -Assess every affected supported use: commands, parameters, APIs, output shapes, configuration, permissions, installation, and runtime/tool requirements. User and integrator may be the same person, as the [PSModule audience](../Initiatives/PSModule.md#target-audience) illustrates. An interactive command still working does not make a change compatible if the same user's supported script integration breaks. +If the route does not invoke Release Management, omit the entire `Release +decisions` block and do not apply or report any `release:*` label, including +`release:skip`. -The change type is decided in this order: +If the route does invoke Release Management, resolve these decisions from the +complete change and the effective +[configuration](../Capabilities/release-management/design.md#configuration-surface): -1. **Explicit user input** — if the contributor / Shipper specified a type, verify it against the audience impact and applicable version policy. Resolve a conflict before finalizing the release decision; a label does not make a breaking change compatible. -2. **Pre-1.0.0 rule** — projects with no version tags or latest tag below `v1.0.0` follow [SemVer §4](https://semver.org/#spec-item-4). Major is **never** auto-detected for pre-1.0.0 projects. Breaking changes there are classified as Minor (`0.x.0`). -3. **Find the affected consumer contracts** in the branch diff. Paths help locate evidence; they do not determine impact: +1. **Release or skip.** Release when the change affects the versioned artifact + or a supported consumer contract. Otherwise select `release:skip`. +2. **Version bump.** For a release, choose Patch, Minor, or Major from the + compatibility impact. An explicit bump label overrides a valid + `DefaultBump`; a matching configured default may supply the level without an + explicit bump label. +3. **Mode.** Record Stable or Prerelease from the target route and any valid + `release:pre-release` override. Prerelease mode still requires a resolved + bump. - | Artifact type | Recognition hints | Consumer contract to inspect | - | --- | --- | --- | - | Library / Module | Source and package manifest | Public commands/APIs, parameters, output shapes, defaults, installation, and supported runtimes. | - | GitHub Action | `action.yml` and its implementation | Inputs, outputs, permissions, execution environment, and behavior. | - | Reusable Workflow | Callable workflows under `.github/workflows/` | Caller inputs, secrets, permissions, configuration, tool requirements, and behavior. | - | Infrastructure module | Module source, variables, and outputs | Variable/output contracts, defaults, provider requirements, and managed-resource behavior. | +Use only the labels owned by the +[`release:` namespace](Automation-Labels.md#every-set-is-namespaced). Missing, +invalid, or conflicting decisions are errors to resolve before review, not +reasons to assume a patch release. -4. **Classification rules** (apply in order, against those contracts): - 1. **Docs** — documentation-only changes, not a functional change merely stored in a documentation file. - 2. **Maintenance** — internal-only changes with no effect on shipped behavior or supported integration contracts. - 3. **Major** — a supported user or integration contract breaks (pre-1.0.0 auto-detection maps this to Minor). - 4. **Feature (Minor)** — backward-compatible capabilities are added. - 5. **Patch or Fix** — backward-compatible fixes or small improvements. +### Select the news -Use the highest impact across the affected supported contracts, then apply the version policy. A small fix can be breaking; unrelated internal changes or documentation do not lower that impact. +Keep the summary and named sections focused on results that matter to the +identified readers. Put implementation facts, validation, and process evidence +in supporting details. Omit internal facts that neither explain a reader-facing +result nor help review it. -A configured default supplies a release level, not evidence of compatibility. Check it against the audience impact and apply an explicit override when the change requires a different level. +Internal-only work can still have a clear result, such as a shared automation +configuration. When it has no reader-facing classified section, summarize the +result and put necessary supporting blocks directly after the summary marker. -Illustrative cases, not release history: +### Group related changes -| Change | Audience-based classification | -| --- | --- | -| Remove a supported `Process-PSModule` caller input | Breaking for module maintainers integrating the workflow, not Maintenance because the edit is under `.github/`. | -| Change a module's supported output shape or raise its minimum PowerShell version | Breaking for PowerShell users and their integrations, even if only a manifest or one line changes. | -| Add an optional module parameter without changing existing calls | Feature (Minor): a compatible capability for the same PowerShell audience. | +Group changes by audience-facing result or affected interface, not by commit, +file, issue, or implementation step. One section may describe several files +that jointly deliver one result. Separate unrelated reader outcomes into their +own sections and classify each result once. -## Description structure +## Write the title -Ordered, top to bottom. +Use one short statement of the most important user-facing result: -### 1. Leading paragraph — Summary +```text +LLM Gateway streaming requests report usage +``` -A concise paragraph describing **what changes for the user**. Present tense, active voice. Never open with implementation language ("Refactored", "Updated class", "Added null checks"). +For internal-only work, name the operational result: -### 2. User-facing changes — sections with headers +```text +Release automation uses a shared configuration +``` + +The title must not contain: + +- an icon or type prefix; +- a Conventional Commit prefix such as `feat:` or `docs:`; +- an issue reference; +- a list of unrelated changes; +- AI or agent attribution; +- an implementation detail when a reader-facing result is available. -Organize by **what the user experiences**, not by what was changed internally. +## Write the description -- `## Breaking Changes` — what stopped working or changed incompatibly, regardless of the selected change type. Include pre-1.0 breaking behavior even when the version policy classifies it as Minor. -- `## New: ` — new things the user can do. -- `## Changed: ` — existing behavior that now works differently. -- `## Fixed: ` — problems now resolved. +The description stands on its own for a reader who has not inspected the diff. +Use the following structure. -Under each header: +### Summarize the result -- What the user can now do, or what changed for them. -- Who is affected, including changed public parameters and defaults. -- A link to the release-wide adoption path rather than a second sequence of instructions. -- Examples or code snippets showing new usage. +Start with one or two short paragraphs and no `Summary` heading. Lead with +required action and breaking impact when either exists. A short unordered list +is acceptable only when the change has several distinct result groups that +cannot be stated clearly in prose. -Do **not** include private implementation details or refactoring decisions here. Exact public interface names belong here when users need them to understand or adopt the change. +Use the vocabulary of the supported interface. Describe what changes, who is +affected, and what they need to do. Keep implementation narration out of the +summary. -### 3. Adopting this release +### End the shareable summary -Every PR includes `## Adopting this release` before the technical details. Give one ordered, release-wide path for the affected consumers, with applicability, prerequisites, and any required intermediate steps. Adapt the actions to the artifact: a library call, workflow input, service setting, or infrastructure module may need different consumer changes. +End the summary with the exact HTML marker shown in the +[complete template](#copy-the-complete-template). -When updating the reference is sufficient, state: **No configuration, code, or invocation changes are required beyond selecting this release.** For a non-releasing change, state its adoption outcome explicitly too. An empty section or an absent migration paragraph is not evidence that no action is needed. +The marker appears exactly once, on its own line, outside a code fence, and +before the first detailed section. Text before it must remain useful when shared +without the rest of the description. -### 4. Release impact +### Explain each reader-facing result -Every PR includes `## Release impact`. Report the release resolver's decision; do not introduce a second version-selection policy. +Use these classifiers in this order and omit empty groups: -When `DefaultBump` supplies an MSX release level, record the setting and value as the source. Unless a valid `release:skip` is selected, missing both an explicit level and a configured default fails the [required decision check](../Capabilities/release-management/design.md#required-pre-merge-decision-check) and blocks merge; never infer a patch release from missing input. +1. `## Breaking: ` +2. `## Removed: ` +3. `## New: ` +4. `## Changed: ` +5. `## Fixed: ` -| Field | Required content | +| Classifier | Use when | | --- | --- | -| Effective decision | The selected owned label and its semantic effect, or the configured policy that supplies the decision where supported. Identify the decision's source; do not assume a label name across producers. | -| Semantic effect | Major, minor, patch, or no release, plus stable/prerelease mode where applicable. Describe breaking behavior separately from its version classification. | -| Release/base coordinates | Before publication, state that final coordinates are resolved by the release process. The published record supplies the actual target version, tag, immutable source, version-computation base, and release/source baseline for the consumer delta, distinguishing the two bases when they differ. | +| `Breaking` | A supported consumer must act or an existing supported use becomes incompatible. | +| `Removed` | A supported capability, interface, or documented path is no longer available. | +| `New` | Readers gain a capability, interface, or body of guidance. | +| `Changed` | Existing behavior, configuration, or guidance changes compatibly. | +| `Fixed` | An incorrect behavior or guidance now works as intended. | + +Each section heading states one result, not a component name. Open the section +with one or two prose paragraphs that explain the outcome, affected readers, +and required action. A documentation change uses the classifier that describes +what its guidance now provides. + +### Show interfaces after the prose -Before publication, name the intended semantic effect and state that final coordinates are **resolved by the release process**. Do not assign a final version in advance or retain a numeric prediction after the base changes. The publisher records the actual coordinates in a distinct publication envelope without rewriting the authored body. For a first release, identify the initial versioning baseline and state that there is no prior release; for `release:skip`, state that no version is produced. +After the opening prose, add an interface example or compact table only when it +makes the reader's action clearer. Do not lead a section with a code block or +table. Do not use before-and-after examples or diagrams in a pull request +description; keep those in durable documentation and link to them. -### 5. Required ending blocks +Link visible documentation using an absolute default-branch URL or the canonical +published URL so the link survives when the pull request becomes a release +record. Never include secret values. -At the very end of every PR description, use this exact structure: +### Close each section with supporting details + +A named section may end with either or both of these optional blocks, in this +order: ```markdown ----
Technical details -### Consumer change record +Implementation and validation evidence for this result. + +
+ +
+Related references - +- Resolves MSXOrg/repository#123 +- Depends on MSXOrg/other-repository#456 -### Template baseline +
+``` - +The blocks are section-scoped. Do not add global catch-all `Technical details` +or `Related references` blocks after several classified sections. If the pull +request is internal-only and has no classified section, place its supporting +blocks directly after the summary marker. -### Maintainer evidence +Put the standards and framework alignment evidence required by +[Implement](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass) +in the `Technical details` block for the result it supports. For a +release-managed result, include the applicable consumer, template, and baseline +evidence required by [Release +Management](../Capabilities/release-management/spec.md#release-evidence) in that +same scoped block. - +Use fully qualified `owner/repository#number` references for every same-instance +GitHub issue or pull request, including references to the current repository. +Use closing keywords only for issues the complete change actually resolves. +Prefix non-closing relationships with terms such as `References`, `Depends on`, +or `Followed by`. Use absolute Markdown links for Jira, cross-instance GitHub, +and references that will render outside GitHub. - +Do not include AI or agent attribution anywhere in the description. + +### Record release decisions only when invoked +When the target route invokes Release Management, add one `Release decisions` +block after the classified sections and apply the exact labels the block +reports: + +```markdown
-Relevant issues (or links) +Release decisions -- Resolves Org/Repo#123 -- Resolves Org/OtherRepo#124 +- **Release:** Yes - the delivered artifact and supported caller contract change. +- **Version bump:** Minor - callers gain a compatible optional input. +- **Mode:** Stable - the target route publishes stable releases. +- **Labels:** `release:minor` -### Related work +
+``` -- Depends on Org/OtherRepo#124 -- Followed by Org/OtherRepo#125 -- References Org/OtherRepo#126 +For a no-release decision, include only the decision and its label: + +```markdown +
+Release decisions + +- **Release:** No - the change does not affect the artifact or its supported consumer contracts. +- **Labels:** `release:skip`
``` -The **Technical details** block uses the three `###` headings shown above to separate consumer evidence from maintainer evidence. The deeper headings below organize this standard, not the PR body. +The evidence after each decision must identify the applicable route, +configuration, and audience impact. List the exact resulting labels, or `None` +when effective configuration supplies the release decision and no override +label applies. Do not predict the final version; Release Management resolves it +from the actual base. -#### Consumer change record +When the target route does not invoke Release Management, omit this block and +all `release:*` labels. Do not add `release:skip` merely because the repository +has no `.github/release.config.yml`. -Use one row per affected surface. A stable identifier within the record lets the adoption steps and later release records refer to the same change. +### Assemble the body -| Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification | -| --- | --- | --- | --- | --- | --- | -| `` | `` | `` | `` | `` | `` | +Use this order: -Record exact changed configuration keys, workflow contracts, permissions, secret **names, never values**, public APIs, runtime/tool requirements, defaults, removals, and behavior. A list of changed filenames alone is insufficient. Link to numbered detail in the adoption path when commands or coordinated edits need more room; do not maintain competing instructions. +1. Summary prose. +2. The shareable-summary marker. +3. Classified sections in the required order, each with its own optional + `Technical details` and `Related references` blocks. +4. Supporting blocks directly after the marker only when internal-only work has + no classified section. +5. The conditional `Release decisions` block, only when the target route + invokes Release Management. -Record no-action outcomes explicitly, including changes that affect behavior but require no consumer edit. If no consumer-facing surface changes, say so instead of leaving an empty table. Applicability distinguishes consumers that need an action from those already using the released contract. +Do not add a `Summary` heading, empty classified sections, global supporting +blocks, or parallel release-note metadata. -#### Template baseline +### Copy the complete template -Where a framework or product has an applicable integration template, record: +Start from this complete body. Replace every placeholder and delete every +classifier section, supporting block, example, or release field that does not +apply. Repeat a complete classifier section when several distinct results share +the same classifier, and keep every remaining classifier group in the order +shown. -| Field | Required content | -| --- | --- | -| Producer identity | Producer version and immutable source, or the immutable candidate source before publication. | -| Template identity | Template repository and full immutable commit SHA, not a branch, floating tag, or today's latest template. | -| Compatibility evidence | Evidence that this template commit works with the identified producer source, including required integration surfaces and the relevant validation result. | -| Template work | Linked template PRs and their delivery state, or a justified no-change result. An earlier compatible commit may be reused when the evidence supports it. | +For internal-only work with no classified result, delete all five classifier +groups and place one applicable `Technical details` block and `Related +references` block directly after the marker. Delete the complete `Release +decisions` block when the target route does not invoke Release Management. On an +invoked route with a no-release decision, replace the release block with the +shorter no-release form shown in +[Record release decisions only when invoked](#record-release-decisions-only-when-invoked). + +````markdown +{{ One or two short summary paragraphs that state what changes, who is affected, +and any required action. }} -Every applicable release identifies its verified compatible baseline; a claim of compatibility without evidence is insufficient. If no template applies, state that fact and why. Do not invent a template or describe pending template work as delivered. + -#### Maintainer evidence +## Breaking: {{ Reader-facing result }} -Keep internal implementation notes separate from the consumer record: +{{ One or two prose paragraphs that explain the outcome, affected readers, and +required action. }} -- Which internal functions, classes, or files were changed. -- Implementation approach and design decisions. -- Internal compatibility considerations not already owned by the consumer record. -- **Implementation plan progress** — cross-reference the closing Task or Bug's plan. Which plan steps does this PR complete? Which were moved to follow-up delivery issues? -- **Standards and framework alignment** — the result of the [alignment pass](Workflow-Stages/Implement.md#5-standards-and-framework-alignment-pass), as one row per changed surface. The stage procedure owns when and how the pass is run; this block only carries its evidence. -- **Issue convergence sweep** — the scope used for the [session-end sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) and which additional open issues (if any) the finished diff fully satisfied. +{{ Optional interface example or compact table after the prose. Delete when it +does not help the reader act. }} + +
+Technical details + +{{ Implementation and validation evidence for this result. }} | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | -| `src/**` (PowerShell) | Naming, Functions | Module source layout | Aligned | -| `.github/workflows/**` | GitHub Actions | Reusable workflow contract | Exception — Org/Repo#123 | +| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} | -A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link to the follow-up issue that carries it. A surface with no framework or domain documentation of its own is recorded as `None (no framework-specific docs)`. +{{ For an applicable release-managed consumer or template change, record the +release and source baseline, exact consumer action and verification, and the +compatible template repository and immutable commit. Delete when it does not +apply. }} -The **Relevant issues (or links)** block is required and uses fully qualified references (`Org/Repo#N`) so links work across repositories. +
-Use one bullet per linked reference. Begin with the closing issues, each prefixed with `Resolves`; this applies to the scoped Task or Bug delivered by the pull request and to additional issues the [issue convergence sweep](Workflow-Stages/Implement.md#6-issue-convergence-sweep) confirms are fully satisfied by the same finished diff. When the PR relates to other issues or pull requests, add a `### Related work` header below the `Resolves` list, then list each qualified reference with its relationship, such as `Depends on`, `Followed by`, or `References`. Closing keywords do not close pull requests. A parent PBI or Epic may appear as context without a closing keyword; never close an aggregate through a delivery pull request. Partially convergent or supporting issues are linked as non-closing context. +
+Related references -A PR that delivers a scoped Task or Bug must include at least one `Resolves` link. A PR that does not resolve an issue must include a `### Related work` header and an unordered list of qualified relationship references. If additional `Resolves` links are used, include sweep evidence in Technical details that shows those issues are fully satisfied. The [Issue Hierarchy](Issues/Types/Hierarchy.md) and [Issue Lifecycle](Issues/Process/Lifecycle.md) own type and closure semantics. +- Resolves MSXOrg/repository#123 +- References MSXOrg/repository#456 +- Depends on MSXOrg/other-repository#789 -## Formatting +
-- Paragraphs are written as a **single unbroken line**. GitHub renders mid-paragraph newlines as spaces. -- The PR description is **the release note**. Write it for users, not reviewers. -- The PR title and description align with the closing Task or Bug's user-facing framing and recorded technical decisions. -- Refer to every issue or pull request as `Org/Repo#N`, including references in the current repository; do not use bare `#N` references. +## Removed: {{ Reader-facing result }} -## Example +{{ One or two prose paragraphs that explain the outcome, affected readers, and +required action. }} -This illustrative configuration change uses the same record shape for any artifact type; it does not depend on a particular package manager, language, or deployment mechanism. +{{ Optional interface example or compact table after the prose. Delete when it +does not help the reader act. }} -````markdown -Job timeouts use the explicit `timeoutSeconds` setting. Existing timeout values and the 30-second default are unchanged. +
+Technical details -## Breaking Changes +{{ Implementation and validation evidence for this result. }} -The `timeout` configuration key is removed. Configurations that still supply it are rejected. Rename it using the [adoption path](#adopting-this-release); configurations that omit the key need no configuration edit. +| Changed surface | Standards checked | Framework docs checked | Result | +| --- | --- | --- | --- | +| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} | -## Adopting this release +{{ For an applicable release-managed consumer or template change, record the +release and source baseline, exact consumer action and verification, and the +compatible template repository and immutable commit. Delete when it does not +apply. }} -1. If the job configuration sets `timeout`, rename that key to `timeoutSeconds`, preserving its positive integer value in seconds. For example, `timeout: 20` becomes `timeoutSeconds: 20`. Do not supply both keys. If the key is absent, retain the 30-second default without adding a setting. -2. Select the published release through the integration's version reference or deployment mechanism. Apply the configuration edit with that version change, not to the previous version. -3. Run the existing configuration validation against the selected version: `timeoutSeconds: 20` is accepted and the removed `timeout: 20` is rejected. Run the existing timeout check to confirm cancellation at the configured limit, or 30 seconds when omitted. +
-## Release impact +
+Related references -| Field | Value | -| --- | --- | -| Effective decision | `release:major`, selected for removal of a supported configuration key. | -| Semantic effect | Major, stable; existing explicit configurations require the edit above. | -| Release/base coordinates | The release process resolves the actual version base, change baseline, target version, tag, and immutable source at publication. No final numeric version is assigned in this PR. | +- Resolves MSXOrg/repository#123 +- References MSXOrg/repository#456 +- Depends on MSXOrg/other-repository#789 + +
+ +## New: {{ Reader-facing result }} + +{{ One or two prose paragraphs that explain the outcome, affected readers, and +required action. }} + +{{ Optional interface example or compact table after the prose. Delete when it +does not help the reader act. }} ----
Technical details -### Consumer change record +{{ Implementation and validation evidence for this result. }} + +| Changed surface | Standards checked | Framework docs checked | Result | +| --- | --- | --- | --- | +| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} | + +{{ For an applicable release-managed consumer or template change, record the +release and source baseline, exact consumer action and verification, and the +compatible template repository and immutable commit. Delete when it does not +apply. }} + +
+ +
+Related references + +- Resolves MSXOrg/repository#123 +- References MSXOrg/repository#456 +- Depends on MSXOrg/other-repository#789 + +
-| Identifier / surface | Before | After | Applicability / prerequisites | Consumer action | Verification | -| --- | --- | --- | --- | --- | --- | -| TIMEOUT-KEY / job configuration | Optional `timeout`, a positive integer in seconds; default 30. | Optional `timeoutSeconds`, with the same units and default; `timeout` is rejected. | Every integration; only configurations using the removed key need an edit. | Rename the key without changing its value; see adoption steps 1-2. No configuration change when omitted. | Adoption step 3 accepts the new key, rejects the old key, and confirms the timeout behavior. | +## Changed: {{ Reader-facing result }} -### Template baseline +{{ One or two prose paragraphs that explain the outcome, affected readers, and +required action. }} -Not applicable: this product does not distribute an integration template. +{{ Optional interface example or compact table after the prose. Delete when it +does not help the reader act. }} -### Maintainer evidence +
+Technical details -- The configuration parser accepts `timeoutSeconds` and reports the removed key as invalid. -- Implementation plan progress: all steps in Org/Repo#218 are complete, including explicit-value and default-value coverage. -- Issue convergence sweep: configuration and timeout issues were inspected; no additional issue is fully satisfied. +{{ Implementation and validation evidence for this result. }} | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | -| Configuration parsing and timeout behavior | Naming, Error Handling, Testing | Product configuration contract | Aligned | +| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} | + +{{ For an applicable release-managed consumer or template change, record the +release and source baseline, exact consumer action and verification, and the +compatible template repository and immutable commit. Delete when it does not +apply. }}
-Relevant issues (or links) +Related references + +- Resolves MSXOrg/repository#123 +- References MSXOrg/repository#456 +- Depends on MSXOrg/other-repository#789 -- Resolves Org/Repo#218 +
-### Related work +## Fixed: {{ Reader-facing result }} + +{{ One or two prose paragraphs that explain the outcome, affected readers, and +required action. }} + +{{ Optional interface example or compact table after the prose. Delete when it +does not help the reader act. }} + +
+Technical details -- References Org/Repo#220 +{{ Implementation and validation evidence for this result. }} + +| Changed surface | Standards checked | Framework docs checked | Result | +| --- | --- | --- | --- | +| `{{ Path or interface }}` | {{ Applicable standards }} | {{ Applicable framework docs, or `None (no framework-specific docs)` }} | {{ `Aligned`, `Fixed in this PR`, or `Exception - MSXOrg/repository#123` }} | + +{{ For an applicable release-managed consumer or template change, record the +release and source baseline, exact consumer action and verification, and the +compatible template repository and immutable commit. Delete when it does not +apply. }}
-```` -For a no-action patch, keep both required user-facing blocks. State the no-action adoption outcome and record either the affected behavior with `No consumer edit required` or `No consumer-facing surface changes` under Consumer change record. Do not copy the breaking example's configuration actions into an unaffected release. +
+Related references -## Drafts and readiness +- Resolves MSXOrg/repository#123 +- References MSXOrg/repository#456 +- Depends on MSXOrg/other-repository#789 -- The Shipper always creates the PR as **draft** so CI attaches immediately. -- A pull request is marked ready only when it meets every item in the [Definition of Ready for Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review) — nothing in that gate is left open. That page is the single checklist; this section does not restate it. -- Marking ready is a gate, not a person: anyone who can verify that gate — a contributor, or an agent acting on their behalf — may mark it ready. The gate, not the actor, is what makes it ready. -- Once ready, enable auto-merge (squash) so the change lands when review approves and the required checks stay green. See [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge). +
-## Branches and commits +
+Release decisions -- Branch naming: `/-`, e.g. `fix/123-pagination-truncation`. -- Commit messages: plain, direct, descriptive. **No conventional-commit prefixes** (`fix:`, `feat:`, `docs:`). See [Commit Conventions](Commit-Conventions.md). -- Self-review the staged diff before each commit. Unintended files (debug output, editor temp, credentials) get caught before they reach the remote. +- **Release:** {{ Yes or No }} - {{ Evidence from the artifact, route, and + supported consumer contract. }} +- **Version bump:** {{ Patch, Minor, or Major }} - {{ Compatibility evidence. + Delete this field when Release is No. }} +- **Mode:** {{ Stable or Prerelease }} - {{ Target-route or override evidence. + Delete this field when Release is No. }} +- **Labels:** {{ Exact `release:*` labels, or `None` when effective configuration + supplies the decision without an override label. }} -## Labels and assignment +
+```` -- Apply an owned release label for an explicit decision or override. A matching configured `DefaultBump` may supply the bump without a label; record that source. Use `release:skip` for an explicit no-release decision. -- Apply phase labels if the repo uses them (Planning, Implementation, etc.). -- Assign the current user. -- Request reviewers per `CODEOWNERS`; if none, fall back to repo defaults or skip. +## Check readiness + +Before marking the pull request ready, verify: + +- the title states one result and contains none of the prohibited prefixes, + references, lists, or attribution; +- the summary is accurate on its own and the marker appears exactly once in the + required position; +- every claim matches the complete diff or promotion range; +- classified sections are non-empty, ordered, and grouped by reader-facing + result; +- prose precedes optional examples and tables; +- supporting blocks are scoped to their section and ordered correctly; +- same-instance references are fully qualified and closing keywords are + accurate; +- release metadata and `release:*` labels are absent when the route does not + invoke Release Management; +- when Release Management applies, the decision block, labels, effective + configuration, and complete-change evidence agree; +- the description contains no AI or agent attribution. + +The pull request still follows the complete [Definition of Ready for +Review](Definition-of-Ready-and-Done.md#definition-of-ready-for-review). + +## Where this connects + +- [README-Driven Context](Readme-Driven-Context.md) — where the product audience + and supported interfaces are declared. +- [Contribution Workflow](Contribution-Workflow.md) — how a draft pull request + moves through automated and human review. +- [Definition of Ready and Done](Definition-of-Ready-and-Done.md) — the gate + before review and completion. +- [Branching and Merging](Branching-and-Merging.md) — branch, integration, and + merge rules. +- [Automation Labels](Automation-Labels.md) — ownership and meaning of + `release:*` labels. +- [Release Management](../Capabilities/release-management/design.md) — release + invocation, configuration, decision resolution, and publication. diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md index d495da8..bd15d67 100644 --- a/src/docs/Ways-of-Working/Readme-Driven-Context.md +++ b/src/docs/Ways-of-Working/Readme-Driven-Context.md @@ -38,7 +38,7 @@ Every repository README MUST identify its target audience, the jobs the product **User and integrator are roles, not necessarily different people.** An integration interface is user-facing when the audience depends on it; it does not become internal because its users write scripts, compose APIs, or maintain another product. The audience is not inferred from who authors or reviews a pull request. -Detailed users and jobs belong in the [capability specification](Spec-Driven-Development.md#what-a-specification-is), linked from the README rather than copied. This declared audience anchors [change classification](PR-Format.md#detecting-the-change-type) and the consumer evidence in release notes. +Detailed users and jobs belong in the [capability specification](Spec-Driven-Development.md#what-a-specification-is), linked from the README rather than copied. This declared audience anchors [reader identification](PR-Format.md#identify-the-readers) and the evidence in pull request descriptions. ## When to update the README diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index 1bbc6b9..013f710 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -166,20 +166,23 @@ When a tool only discovers config at the repository root, keep it there and docu ## Pull request defaults -Repository pull requests must use the PR Manager style for title and description when a release note may be generated from the PR. - -Default title pattern: - -```text - []: -``` - -Use [PR Format](PR-Format.md) for audience-based change classification and the complete description structure, including its required consumer evidence and ending blocks. A PR closes one scoped Task or Bug, with any additional closing links limited to issues the session-end convergence sweep shows are fully delivered by the same diff. +Repository pull requests follow [PR Format](PR-Format.md): one short +reader-facing result in the title, an audience-first description of the complete +change, and supporting evidence scoped to the result it supports. Repository or +initiative guidance MUST NOT add an icon, type prefix, issue reference, or +internal campaign identifier to the title. + +A pull request closes one scoped Task or Bug, with any additional closing links +limited to issues the session-end convergence sweep shows are fully delivered by +the same diff. When the target route invokes Release Management, the description +and labels carry its evidence-based release decision. A route without that +invocation carries neither the `Release decisions` block nor `release:*` labels. The organization-level `.github` repository supplies the default template. The repository-local contribution guide directs humans and agents to the -organization template and its required format. A repository carries a local -template only for a documented exception. +organization template and the canonical format. The inherited template is a +scaffold; PR Format remains authoritative. A repository carries a local template +only for a documented exception. ## Managed files @@ -218,7 +221,7 @@ For example, PSModule can define its module-specific managed files in `PSModule/ - [Agentic Development](../Capabilities/agentic-development/index.md) — which agent files a repository carries and why the entry point is a pointer. - [Repository Type Property](Repository-Type-Property.md) — the `Type` custom property that classifies a repository and drives which type-specific files and controls apply. - [README-Driven Context](Readme-Driven-Context.md) — why the README is the front door. -- [PR Format](PR-Format.md) — the PR Manager-style title and description format. +- [PR Format](PR-Format.md) — the audience-first title and description format. - [Natural Language](../Coding-Standards/Natural-Language.md) — which language each artifact is written in, and how English prose is written. - [GitHub Actions](../Coding-Standards/GitHub-Actions.md) — workflow and automation standards. - [Dependency Updates](../Capabilities/dependency-updates/spec.md) — supply-chain update requirements. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md index 021b485..cb7ac6f 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Implement.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Implement.md @@ -5,7 +5,7 @@ description: Procedure for the Workflow stage that delivers one ready Task or Bu # Implement -Implement is the delivery stage of the canonical [Workflow](../Workflow.md). It takes one ready, unblocked Task or Bug and produces working software in a review-ready pull request. The stage owns branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the release note. Implement builds delivery leaves; it does not implement an Epic or PBI aggregate, plan from scratch, or supply the independent review. +Implement is the delivery stage of the canonical [Workflow](../Workflow.md). It takes one ready, unblocked Task or Bug and produces working software in a review-ready pull request. The stage owns branching, coding, committing, opening the pull request, tracking progress, running the automated review loop, responding to feedback, and finalizing the pull request description and any applicable release metadata. Implement builds delivery leaves; it does not implement an Epic or PBI aggregate, plan from scratch, or supply the independent review. ## Enter this stage when @@ -64,7 +64,7 @@ Record the outcome as one row per changed surface: | `src/functions/**` (PowerShell) | Naming, Functions, Error Handling | Module source layout | Aligned | | `.github/workflows/**` | GitHub Actions | Reusable workflow contract | Exception — Owner/Repo#123 | -A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link that justifies it. Where a changed surface has no framework or domain documentation of its own, write `None (no framework-specific docs)` rather than inventing a pseudo-link. Carry the table into the pull request's Technical details block per [PR Format](../PR-Format.md), so [Review](Review.md) can verify the pass instead of guessing whether it happened. +A result is `Aligned`, `Fixed in this PR`, or `Exception` with a link that justifies it. Where a changed surface has no framework or domain documentation of its own, write `None (no framework-specific docs)` rather than inventing a pseudo-link. Put each row in the `Technical details` block for the pull request section whose result it supports. For internal-only work without a classified section, put the table in the supporting block after the summary marker. This keeps the evidence scoped per [PR Format](../PR-Format.md) so [Review](Review.md) can verify the pass instead of guessing whether it happened. **Stop rule.** Fix what is in scope for the closing Task or Bug and small enough to keep the pull request reviewable. When a finding is out of scope, systemic across the repository, or would change the shape of the pull request, file a follow-up issue through [Define](Define.md), link it in the table as an exception, and leave the change as it is. The pass improves alignment; it does not turn into a second delivery. @@ -75,15 +75,15 @@ Run this once per implementation session, at the same timing as the standards/fr 1. Search for already-open issues whose asks are already satisfied by the finished diff, not only the issue originally linked when the branch was opened. 2. Scope the sweep deliberately so it scales: prioritize the delivery leaf's parent and siblings in the [Issue Hierarchy](../Issues/Types/Hierarchy.md), then narrow by affected component, labels, keywords, or code paths. Do not read every open issue serially in large repositories. 3. Treat convergence as outcome-based: - - **Fully satisfied** — the diff already delivers the issue's ask. Add it to the pull request's Relevant issues block with `Resolves` so merge closes it. - - **Partially satisfied** — the diff helps but does not fully deliver the ask. Link it as non-closing context and keep or create a follow-up delivery leaf for the remaining gap. + - **Fully satisfied** — the diff already delivers the issue's ask. Add it to the applicable section's `Related references` block with `Resolves` so merge closes it. + - **Partially satisfied** — the diff helps but does not fully deliver the ask. Add it to the applicable `Related references` block as non-closing context and keep or create a follow-up delivery leaf for the remaining gap. 4. Keep this pass focused on convergence and linkage. It does **not** rewrite, reformat, or otherwise "fix up" issue bodies to match issue templates; issue quality edits are separate work routed through [Define](Define.md). ### 7. Finalize and hand off When the change meets the [Definition of Ready for Review](../Definition-of-Ready-and-Done.md): -1. Finalize the title, release-note description, and effective release decision and its source per [PR Format](../PR-Format.md). +1. Finalize the title and release-note-ready description per [PR Format](../PR-Format.md). When the target route invokes Release Management, also reconcile the `Release decisions` block and applied `release:*` labels with the effective configuration; otherwise omit them. 2. Mark the pull request ready and enable auto-merge per [Branching and Merging](../Branching-and-Merging.md). ## Operating rules diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Review.md b/src/docs/Ways-of-Working/Workflow-Stages/Review.md index 0fd096d..1e28ee8 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Review.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Review.md @@ -33,6 +33,10 @@ Check each dimension per [Review Etiquette](../Review-Etiquette.md): - **Taste** — readability, naming, structure, tests that exercise behaviour. - **Security** — input validation, no secrets in logs, external action and reusable-workflow references pinned to full commit SHAs, owned major-tag references meeting the controlled-release exception, and least privilege. Escalate a deep pass to [Security Review](Security-Review.md). - **Documentation** — updated where user-facing behaviour changed. +- **Pull request artifact** — the title states one result, the description follows + [PR Format](../PR-Format.md), supporting evidence is section-scoped, and + release metadata appears only when the target route invokes Release + Management. - **Standards and framework alignment** — the pull request records the author's [alignment pass](Implement.md#5-standards-and-framework-alignment-pass), the result covers every changed surface, and each exception links a real follow-up issue. Spot-check at least one row against the canonical standard or framework page rather than trusting the summary; a missing or hollow pass is a blocking finding. - **Issue convergence sweep** — the pull request records the author's [sweep](Implement.md#6-issue-convergence-sweep), including scoped search coverage and any convergent issues linked with closing keywords. Spot-check at least one linked closing issue against the delivered diff; a claimed convergence with no visible delivery evidence is a blocking finding. - **Tests** — new behaviour has tests; bugs get regression tests. @@ -58,6 +62,7 @@ An approval co-signs the change, so approve once the blocking concerns are resol - [Review Etiquette](../Review-Etiquette.md) — tone, severity, and how to disagree well. - [Implement](Implement.md#5-standards-and-framework-alignment-pass) and [Implement](Implement.md#6-issue-convergence-sweep) — the author-side session-end passes this stage verifies. -- [PR Format](../PR-Format.md) — delivery-leaf closure and contextual aggregate links. +- [PR Format](../PR-Format.md) — reader-facing titles and descriptions, + supporting references, and conditional release metadata. - [Branching and Merging](../Branching-and-Merging.md) — who approves and how a change lands. - [Security Review](Security-Review.md) — the specialized security path. diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md index 58f1b0a..bad4672 100644 --- a/src/docs/Ways-of-Working/Workflow.md +++ b/src/docs/Ways-of-Working/Workflow.md @@ -136,7 +136,10 @@ See [Review Etiquette](Review-Etiquette.md). Human review approves the ready pull request and the required checks stay green, so auto-merge lands the change — squash-merged into the protected branch, its branch deleted — and closes its Task or Bug. Where the project releases from the trunk, the merge cuts the release. -The pull request description becomes the release note. Write it for end users, not reviewers. +The pull request description is release-note-ready. When Release Management +publishes it, the description becomes part of the release record; otherwise it +remains the durable change record. Write it for the identified readers, not +only for reviewers. Parent PBI and Epic issues close separately when their native children and aggregate acceptance criteria are complete. See [PR Format](PR-Format.md), [Issue Lifecycle](Issues/Process/Lifecycle.md), and [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge). diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md index 4ae7e6e..67d4386 100644 --- a/src/docs/Ways-of-Working/index.md +++ b/src/docs/Ways-of-Working/index.md @@ -35,7 +35,7 @@ This section documents the principles, processes, and norms that every contribut | [Goal-Setting Framework](Goal-Setting.md) | Mission, OKRs, and Initiatives — the strategy above repository Epics. | | [Definition of Ready and Done](Definition-of-Ready-and-Done.md) | The three gates that bracket every piece of work. | | [Issues](Issues/index.md) | How issues are formatted and organized across the MSX ecosystem. | -| [PR Format](PR-Format.md) | Pull request title, description, change types, and labels. | +| [PR Format](PR-Format.md) | Audience-first pull request titles and descriptions with evidence-based, conditional release decisions. | | [Commit Conventions](Commit-Conventions.md) | How commit messages are written. | | [Branching and Merging](Branching-and-Merging.md) | Delivery-leaf topic branches, pull-request-only integration, and merge models. | | [Review Etiquette](Review-Etiquette.md) | Tone, scope, severity, and how to disagree well. |