Problem
The PR Format correctly defines a pull request as the release note and requires user-facing sections plus separate technical details. It tells writers to include migration steps under each user-facing section, but it does not require one ordered, release-wide answer to two questions a current user needs answered:
- What version transition does this release make, and which label selected that SemVer increment?
- What must I change, in sequence, to adopt this release from the version or workflow reference I use today?
Calling the second answer a migration overstates routine upgrades. A release note should instead say how to adopt the released change, including an explicit no-action outcome when applicable.
Evidence
A review of all 242 pull requests in PSModule/Process-PSModule found 235 non-empty descriptions. Only 24 use both current required details blocks and 60 use the current user-facing New/Changed/Fixed section pattern. Recent PRs such as PSModule/Process-PSModule#524, PSModule/Process-PSModule#529, and PSModule/Process-PSModule#531 demonstrate strong user and technical narratives, but their adoption/version information is distributed or absent. PSModule/Process-PSModule#535 has an effective sequential consumer-change section named Migration; it is the behavior to standardize without that term.
Proposed change
Extend the Description structure with two required user-facing blocks before the existing technical details:
## Adopting this release
1. <ordered, user-visible action from the currently supported version/reference>
2. <next action>
<Or explicitly state that no configuration, code, or invocation change is required.>
## Release impact
- **Selected label:** `<repository-configured label>`
- **SemVer change:** `<major | minor | patch | no release>`
- **Version transition:** `<current published version> -> <planned released version>`, or an explanation that the final value is resolved from the current published version at release time.
The standard should require authors to:
- keep this adoption path release-wide and ordered rather than scattering instructions under individual feature sections;
- address affected users by artifact type (library/module, reusable workflow, action, service, infrastructure module, and so on);
- state no action explicitly when users can update without changing configuration or usage;
- explain the label's semantic effect without assuming an organization-wide label name where repositories configure their own; and
- update or avoid a numeric transition when another release changes the base version before merge.
Keep the current user-facing feature sections and final Technical details / Relevant issues blocks unchanged. The result stays generic for any release while making a PR a complete, customer-facing release decision record.
Problem
The PR Format correctly defines a pull request as the release note and requires user-facing sections plus separate technical details. It tells writers to include migration steps under each user-facing section, but it does not require one ordered, release-wide answer to two questions a current user needs answered:
Calling the second answer a migration overstates routine upgrades. A release note should instead say how to adopt the released change, including an explicit no-action outcome when applicable.
Evidence
A review of all 242 pull requests in PSModule/Process-PSModule found 235 non-empty descriptions. Only 24 use both current required details blocks and 60 use the current user-facing
New/Changed/Fixedsection pattern. Recent PRs such as PSModule/Process-PSModule#524, PSModule/Process-PSModule#529, and PSModule/Process-PSModule#531 demonstrate strong user and technical narratives, but their adoption/version information is distributed or absent. PSModule/Process-PSModule#535 has an effective sequential consumer-change section namedMigration; it is the behavior to standardize without that term.Proposed change
Extend the Description structure with two required user-facing blocks before the existing technical details:
The standard should require authors to:
Keep the current user-facing feature sections and final Technical details / Relevant issues blocks unchanged. The result stays generic for any release while making a PR a complete, customer-facing release decision record.