Skip to content

MNT: Automate CHANGELOG.md updates via GitHub Actions #905

@Gui-FernandesBR

Description

@Gui-FernandesBR

Is your feature request related to a problem? Please describe.
Currently, the CHANGELOG.md file is manually updated by contributors in every Pull Request. This process has several downsides:

  1. Human Error: Contributors often use the wrong format, forget to add links, or place entries in the wrong section.
  2. Merge Conflicts: Since almost every PR touches the [Unreleased] section of the changelog, it is a frequent source of merge conflicts that require manual resolution.
  3. Inconsistency: The descriptions often vary in style (e.g., starting with "ENH", "BUG", or just plain text).

Describe the solution you'd like
I would like to implement a GitHub Action (or a bot) that automatically updates the CHANGELOG.md file when a PR is merged.

The automation should:

  1. Read PR Metadata: Extract the PR title, number, and URL.
  2. Categorize: Use GitHub Labels (e.g., Enhancement, Bug, Refactor, Documentation) to decide which section of the Changelog the entry belongs to.
  3. Format: Automatically prepend the standard prefixes (ENH, BUG, DOC) and append the PR link [#123](url).
  4. Write: Append the new entry to the [Unreleased] section of CHANGELOG.md.

Proposed Logic for Categorization
The automation should map GitHub Labels to "Keep a Changelog" sections:

  • Label: Enhancement or Feature $\rightarrow$ Section: ### Added
  • Label: Bug $\rightarrow$ Section: ### Fixed
  • Label: Refactor or Maintenance $\rightarrow$ Section: ### Changed
  • Label: Documentation $\rightarrow$ Section: ### Added or ### Changed (depending on configuration)

Potential Tools
We should investigate tools such as:

  • Release Drafter: Creates a draft release with the changes, which can then be pasted into the Changelog.
  • Git Cliff: A highly customizable changelog generator.
  • Towncrier: (Used by pandas/scipy) Uses fragment text files to generate the changelog at release time to avoid merge conflicts completely.

Additional context
The current format of CHANGELOG.md adheres to Keep a Changelog. The automation must respect this format.

Example of a desired entry generation:

  • PR Title: "Add new drag model"
  • PR Number: 895
  • Label: Enhancement
  • Result: - ENH: Add new drag model [#895](https://github.com/RocketPy-Team/RocketPy/pull/895) under ### Added.

Metadata

Metadata

Assignees

Labels

C.I.Continuous Integration (Workflows and actions)Git housekeepingClean and organize our githubReleasesRelated with new releases

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions