中文
devexamples
← Workflows

阅读中文版本

Changelog Automation Workflow

Capture change notes with each contribution, generate a human-readable changelog at release, and keep breaking changes prominent for consumers.

beginner~60 minreleasedocumentationci

Objective

Produce an accurate, readable changelog from contributor input without hand-writing it at release.

Environment

  • A change-note convention or tool
  • Conventional commits or a changeset flow

Steps

1. Require contributors to add a change

Require contributors to add a change note with the change.

Expected state: Intent is captured at the source.

2. Generate the changelog from the notes

Generate the changelog from the notes at release time.

Expected state: The changelog reflects real changes.

3. Highlight breaking changes and migration steps

Highlight breaking changes and migration steps prominently.

Expected state: Consumers see impactful changes first.

4. Link entries to issues or pull

Link entries to issues or pull requests.

Expected state: Readers can get context.

Decision points

Automated or curated changelog?

  • Automated with editing
  • Fully automated

Automate the draft then edit for clarity; fully automated lists are often unreadable.

Include internal refactors?

  • No, user-facing only
  • Everything

User-facing changes plus notable fixes; listing internal refactors buries what matters.

Expected outcome

A changelog generated from contributor notes that accurately reflects the release and leads with breaking changes.

Verification

Confirm the generated changelog lists every user-facing change in the release and that breaking changes include migration guidance.

Cleanup

Publish the changelog and tag the release.

Overview

Produce an accurate, readable changelog from contributor input without hand-writing it at release. Confirm the generated changelog lists every user-facing change in the release and that breaking changes include migration guidance.

Steps

  1. Require contributors to add a change note with the change. Expected state: Intent is captured at the source.
  2. Generate the changelog from the notes at release time. Expected state: The changelog reflects real changes.
  3. Highlight breaking changes and migration steps prominently. Expected state: Consumers see impactful changes first.
  4. Link entries to issues or pull requests. Expected state: Readers can get context.
npx conventional-changelog -p angular -i CHANGELOG.md -s
# review and edit before publishing

Verification

  • A changelog generated from contributor notes that accurately reflects the release and leads with breaking changes.

Decision points

  • Automated or curated changelog? Options: Automated with editing; Fully automated. Recommended: Automate the draft then edit for clarity; fully automated lists are often unreadable.
  • Include internal refactors? Options: No, user-facing only; Everything. Recommended: User-facing changes plus notable fixes; listing internal refactors buries what matters.