Skip to content

Make release impact and user adoption explicit in PR release notes #202

Description

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:

  1. What version transition does this release make, and which label selected that SemVer increment?
  2. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions