中文
devexamples
← Workflows

阅读中文版本

Release Notes Quality Review Workflow

Review generated notes for accuracy and audience, lead with impact and breaking changes, add migration steps, and remove internal noise.

beginner~60 minreleasecommunicationquality

Objective

Turn generated release notes into clear, audience-appropriate communication before publishing.

Environment

  • A generated draft of release notes
  • A reviewer familiar with the release

Steps

1. Check every entry against what actually

Check every entry against what actually shipped.

Expected state: Notes are accurate.

2. Lead with breaking changes and required

Lead with breaking changes and required actions.

Expected state: Readers see what affects them first.

3. Add migration steps and links

Add migration steps and links for breaking changes.

Expected state: Consumers can act immediately.

4. Remove internal noise and clarify jargon

Remove internal noise and clarify jargon.

Expected state: The audience can read it without context.

Decision points

Editorial pass or publish generated text as-is?

  • Editorial pass
  • As-is

Always edit; generated text often includes internal jargon and misses impact ordering.

Separate notes per audience?

  • Yes for external and internal
  • One set

Separate external notes from internal changelog; internal details should not reach customers.

Expected outcome

Accurate release notes that lead with impact, include migrations, and are readable by the target audience.

Verification

Confirm each breaking change has a migration step and that no entry describes work not actually in the release.

Cleanup

Publish the notes and record the release date and version.

Overview

Turn generated release notes into clear, audience-appropriate communication before publishing. Confirm each breaking change has a migration step and that no entry describes work not actually in the release.

Steps

  1. Check every entry against what actually shipped. Expected state: Notes are accurate.
  2. Lead with breaking changes and required actions. Expected state: Readers see what affects them first.
  3. Add migration steps and links for breaking changes. Expected state: Consumers can act immediately.
  4. Remove internal noise and clarify jargon. Expected state: The audience can read it without context.
# review the generated draft
sed -n '1,80p' RELEASE_NOTES.md
# verify each entry against the merged PRs before publishing

Verification

  • Accurate release notes that lead with impact, include migrations, and are readable by the target audience.

Decision points

  • Editorial pass or publish generated text as-is? Options: Editorial pass; As-is. Recommended: Always edit; generated text often includes internal jargon and misses impact ordering.
  • Separate notes per audience? Options: Yes for external and internal; One set. Recommended: Separate external notes from internal changelog; internal details should not reach customers.