Release Announcement Drafting Workflow
Draft a release announcement that distinguishes user impact from internal detail and links to the changelog.
Objective
Communicate a release clearly to users and stakeholders with accurate, non-hyped content.
Environment
- A changelog
- An announcement channel
- Reviewers for accuracy
Steps
1. Separate user impact from internals
Extract only changes users can observe and group them by theme.
Expected state: The draft leads with what users will notice.
2. State breaking changes plainly
Describe any required user action with a migration path and deadline.
Expected state: Breaking changes are unmissable with actions and dates.
3. Review for accuracy
Have a reviewer confirm each claim against the changelog and shipped code.
Expected state: No announcement claim overstates what shipped.
4. Publish and link
Publish the announcement with links to the changelog and docs.
Expected state: Readers can reach the details from the announcement.
Decision points
Announce internally first or externally?
- Internal then external
- External only
Brief internal support first so they can handle questions.
Detail level?
- User-facing summary
- Full technical detail
Lead with a user-facing summary and link to full detail.
Expected outcome
Users and stakeholders receive an accurate announcement that highlights what affects them and how to act.
Verification
Confirm each claim matches the changelog, breaking changes list actions and dates, and links resolve.
Cleanup
Archive the announcement with the release and update the docs it references.
Overview
Communicate a release clearly to users and stakeholders with accurate, non-hyped content.
This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.
Environment and prerequisites
- A changelog
- An announcement channel
- Reviewers for accuracy
Procedure
1. Separate user impact from internals
Extract only changes users can observe and group them by theme.
Expected state: The draft leads with what users will notice.
2. State breaking changes plainly
Describe any required user action with a migration path and deadline.
Expected state: Breaking changes are unmissable with actions and dates.
3. Review for accuracy
Have a reviewer confirm each claim against the changelog and shipped code.
Expected state: No announcement claim overstates what shipped.
4. Publish and link
Publish the announcement with links to the changelog and docs.
Expected state: Readers can reach the details from the announcement.
# keep the announcement claim traceable to the changelog entry
grep -n 'deprecat' CHANGELOG.mdVerification
Confirm each claim matches the changelog, breaking changes list actions and dates, and links resolve.
Decision points
Announce internally first or externally?
- Internal then external
- External only
Recommendation: Brief internal support first so they can handle questions.
Detail level?
- User-facing summary
- Full technical detail
Recommendation: Lead with a user-facing summary and link to full detail.
Common failures
- Hyping internal changes confuses users.
- Burying breaking changes causes support spikes.
- Unverified claims damage trust.