Skip to content

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

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.

Activity

  1. added
    C.I.Continuous Integration (Workflows and actions)
    ReleasesRelated with new releases
    on Dec 4, 2025
  2. Malmahrouqi3 commented on Dec 5, 2025

    @Malmahrouqi3
    Member

    @Gui-FernandesBR please assign!

  3. Malmahrouqi3 commented on Dec 9, 2025

    @Malmahrouqi3
    Member

    POC: changelog.yml, CHANGELOG.md. To implement, change the branch from changelog-update to develop.

    I merged some PRs from other fork branches and it worked as intended.

    Comments:

    Default -> Enhancement, otherwise Label (case-sentive) should correspond to either Fixed, Added, or Changed. Also, "Docs" & "Git housekeeping" labels are included under Changed. "Docs" by itself is included under Added.

    Overall the concept works relying solely on labels so no need to be abiding by PR title naming conventions or such.

    Not all labels mentioned (e.g. Maintenance, Feature) above exist for some reason. I just need a correct list of current/updated labels and their respective sections. Also, does secrets.GITHUB_TOKEN have write access to allow the workflow to edit CHANGELOG.md on develop branch? Further, REL (release) PRs ought to be excluded from the process therefore added manually.

  4. Gui-FernandesBR commented on Dec 9, 2025

    @Gui-FernandesBR
    MemberAuthor

    @Malmahrouqi3 here you can find our official list: https://docs.rocketpy.org/en/latest/development/style_guide.html#pull-requests

    these are our labels: https://github.com/RocketPy-Team/RocketPy/issues/labels

    does secrets.GITHUB_TOKEN have write access to allow the workflow to edit CHANGELOG.md on develop branch?

    Yes! Or at least it should...

    @Malmahrouqi3 thx for your help, please submit a PR so we can review it

  5. linked a pull request that will close this issueENH: Auto Populate Changelog #919on Dec 11, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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