|
| 1 | +--- |
| 2 | +title: Writing release-note pull requests |
| 3 | +description: Turn a pull request into clear release notes that explain outcomes, adoption steps, and version impact. |
| 4 | +--- |
| 5 | + |
| 6 | +# Writing release-note pull requests |
| 7 | + |
| 8 | +For the default Process-PSModule configuration, a pull request title becomes the GitHub Release notes heading and its |
| 9 | +description becomes the release notes body. The release name is the resolved version unless |
| 10 | +`Publish.Module.UsePRTitleAsReleaseName` changes that setting. Treat the title, description, and selected version label |
| 11 | +as the final decision about what users receive. |
| 12 | + |
| 13 | +This guide extends the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/) with the release transition and |
| 14 | +adoption information required by Process-PSModule consumers. It applies to any releasable artifact: a PowerShell |
| 15 | +module, reusable workflow, GitHub Action, library, service, or infrastructure module. |
| 16 | + |
| 17 | +## Before starting |
| 18 | + |
| 19 | +- Identify the artifact and the people or systems that use it. |
| 20 | +- Inspect the configured version-label mapping and select the label that matches the delivered compatibility impact. |
| 21 | + Do not assume a label name: repositories can configure their own mappings. |
| 22 | +- Find the latest published stable version and calculate the expected SemVer transition. If another release can merge |
| 23 | + first, describe the semantic increment and re-check the numeric transition before the pull request is ready. |
| 24 | +- Identify every user-visible change and the steps an existing user needs to take to use it safely. |
| 25 | + |
| 26 | +## Steps |
| 27 | + |
| 28 | +1. Write the title in the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#title). Describe the |
| 29 | + user-facing outcome, not the implementation activity. |
| 30 | +2. Open with one concise paragraph that says what users receive and why it matters. Use present tense and active voice. |
| 31 | +3. Group the changes by experience using `## New:`, `## Changed:`, `## Fixed:`, and, for an incompatible release, |
| 32 | + `## Breaking Changes`. Each group explains the outcome before any implementation detail. |
| 33 | +4. Add `## Adopting this release` after the user-facing change groups. Give the steps in the order an existing user |
| 34 | + takes them from the currently supported version, workflow reference, configuration, or invocation. State explicitly |
| 35 | + when no configuration, code, or usage change is needed. This is normal release adoption, not a migration. |
| 36 | +5. Add `## Release impact`. State the configured label, the resulting SemVer effect, and the transition from the |
| 37 | + current published version to the planned release version. Explain whether the numeric value is provisional because |
| 38 | + it is resolved from the current published version at release time. |
| 39 | +6. Finish with the required `Technical details` and `Relevant issues (or links)` blocks from the |
| 40 | + [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#description-structure). Technical details explain |
| 41 | + how the outcome was delivered; they do not replace the user-facing narrative or adoption steps. |
| 42 | + |
| 43 | +## Release-note structure |
| 44 | + |
| 45 | +Use only the user-facing change headings that apply, but always include an adoption answer and release impact for a |
| 46 | +published change. |
| 47 | + |
| 48 | +````markdown |
| 49 | +<One paragraph explaining what users receive and why it matters.> |
| 50 | + |
| 51 | +## New: <capability> |
| 52 | + |
| 53 | +<What users can now do and the result they get.> |
| 54 | + |
| 55 | +## Changed: <existing behavior> |
| 56 | + |
| 57 | +<What users experience differently.> |
| 58 | + |
| 59 | +## Fixed: <problem> |
| 60 | + |
| 61 | +<What now works and how users benefit.> |
| 62 | + |
| 63 | +## Breaking Changes |
| 64 | + |
| 65 | +<What no longer works, who is affected, and the compatible replacement.> |
| 66 | + |
| 67 | +## Adopting this release |
| 68 | + |
| 69 | +1. <First action from the currently supported version or reference.> |
| 70 | +2. <Next action, configuration change, or verification step.> |
| 71 | + |
| 72 | +<Or: No configuration, code, or invocation change is required. Update to this version normally.> |
| 73 | + |
| 74 | +## Release impact |
| 75 | + |
| 76 | +- **Configured label:** `<label that selects this release>` |
| 77 | +- **SemVer change:** `<Major | Minor | Patch>` |
| 78 | +- **Version transition:** `<current published version> -> <planned release version>` |
| 79 | +- **Release name:** `<planned release version>` |
| 80 | + |
| 81 | +--- |
| 82 | +<details> |
| 83 | +<summary>Technical details</summary> |
| 84 | + |
| 85 | +<Implementation approach, compatibility evidence, validation, and standards alignment.> |
| 86 | + |
| 87 | +</details> |
| 88 | + |
| 89 | +<details> |
| 90 | +<summary>Relevant issues (or links)</summary> |
| 91 | + |
| 92 | +- Resolves Owner/Repository#123 |
| 93 | + |
| 94 | +### Related work |
| 95 | + |
| 96 | +- References Owner/Repository#456 |
| 97 | + |
| 98 | +</details> |
| 99 | +```` |
| 100 | + |
| 101 | +For `release:skip` or an equivalent configured label, replace the release-impact list with an explicit statement that |
| 102 | +no artifact is published and no version transition occurs. For a prerelease, state the selected bump and that the |
| 103 | +release is a validation channel rather than the latest stable version. |
| 104 | + |
| 105 | +## Writing the adoption path |
| 106 | + |
| 107 | +The adoption path is release-wide. It connects related changes into the sequence a user follows instead of leaving |
| 108 | +instructions scattered through feature sections. |
| 109 | + |
| 110 | +| Artifact users consume | Adoption path answers | |
| 111 | +| --- | --- | |
| 112 | +| PowerShell module | Which version to install, whether scripts or command usage change, and how to verify the updated behavior. | |
| 113 | +| Reusable workflow | Which `uses:` reference to change, which trigger, permission, input, secret, or label changes are required, and the order to apply them. | |
| 114 | +| GitHub Action | Which action reference and inputs change, whether permissions or secrets are affected, and how callers verify it. | |
| 115 | +| Library or service | Which dependency, API contract, setting, or deployment step changes and what compatibility behavior remains. | |
| 116 | +| Infrastructure module | Which module version and input or output contracts change, the safe rollout order, and any state or deployment action. | |
| 117 | + |
| 118 | +Do not label this section `Migration` unless the release performs a genuine data or platform migration. A routine |
| 119 | +version update, reference change, configuration adjustment, or command replacement belongs under |
| 120 | +`Adopting this release`. |
| 121 | + |
| 122 | +## Release impact |
| 123 | + |
| 124 | +The configured version label determines the next version by applying its SemVer bump to the current published |
| 125 | +version. The exact label can differ between repositories; describe its effect rather than relying on a conventional |
| 126 | +name. The title and body explain the user value, while the version becomes the default GitHub Release name. |
| 127 | + |
| 128 | +Before marking a pull request ready, refresh the current version and planned version if another release landed while |
| 129 | +the branch was open. Do not publish a stale numeric transition. A prerelease label selects a release channel alongside |
| 130 | +the version bump; it is not the bump itself. |
| 131 | + |
| 132 | +## Verify |
| 133 | + |
| 134 | +- The title and opening paragraph are understandable without internal file, function, or class names. |
| 135 | +- Every user-visible change says what the user gets, and the technical details remain in the final details block. |
| 136 | +- `Adopting this release` gives complete, ordered instructions for affected users or explicitly says no action is |
| 137 | + needed. |
| 138 | +- The configured label, SemVer effect, current version, and planned version agree with the release configuration. |
| 139 | +- No placeholders or authoring comments remain in the release notes body. |
| 140 | +- The final details blocks match the [MSX PR format](https://msx.no/docs/Ways-of-Working/PR-Format/#description-structure). |
| 141 | + |
| 142 | +## If it fails |
| 143 | + |
| 144 | +| Symptom | Cause | Resolution | |
| 145 | +| --- | --- | --- | |
| 146 | +| The next version cannot be stated accurately. | Another release may change the published baseline, or the configured label is unknown. | State the semantic impact, inspect the configured label mapping, and refresh the numeric transition before review. | |
| 147 | +| A user cannot tell whether they need to change anything. | The change explanation describes implementation instead of adoption. | Add an ordered adoption path or explicitly state that normal updating is sufficient. | |
| 148 | +| The release notes read like reviewer notes. | Technical implementation details appear in the user-facing sections. | Move implementation, validation, and design detail to `Technical details`; retain the user outcome and action in the main body. | |
0 commit comments