GitHub-Native Changelog Generator: A Comprehensive Guide

Hey guys! Today, we're diving deep into how to create a GitHub-native changelog generator using merge discussions. This approach, championed by AndrewWilks in the repo-template-public repo on the ci/gh-changelog branch, leverages Release Drafter and GitHub’s Generate Release Notes API to automate the changelog creation process. Buckle up, because we're about to make your release notes game strong!

Scope

The primary goal here is to use Release Drafter in conjunction with GitHub's Generate Release Notes API. This combo will produce release notes derived from merged pull requests and their associated labels. The magic doesn't stop there! The generated notes will then be synced into your CHANGELOG.md file via an automated pull request. The best part? No external AI keys are needed – everything stays within the GitHub ecosystem. This ensures security, simplicity, and a streamlined workflow. Forget about juggling multiple tools and API keys; this solution keeps it 100% GitHub, making it easier for everyone to manage and contribute to the changelog. Plus, you get to maintain a single source of truth for your release notes.

Acceptance Criteria

To ensure our changelog generator works like a charm, we have a few key criteria to meet:

• .github/release-drafter.yml categories map to Keep‑a‑Changelog sections: This ensures that your changelog is well-organized and adheres to the widely-adopted Keep-a-Changelog format. By mapping the categories defined in your Release Drafter configuration to the sections in Keep-a-Changelog, you maintain consistency and clarity in your release notes. This structured approach makes it easier for users to quickly understand the changes introduced in each release.
• Workflow release-drafter.yml updates the draft release on pushes to main: This workflow automates the process of updating the draft release whenever there are new commits to the main branch. This ensures that the release notes are always up-to-date with the latest changes. By automatically updating the draft release, you save time and effort, and you can be confident that your release notes accurately reflect the current state of the codebase.
• Workflow changelog-sync.yml pulls the generated notes and opens a PR updating CHANGELOG.md: This workflow is responsible for taking the generated release notes and creating a pull request to update the CHANGELOG.md file. This automates the process of keeping the changelog in sync with the release notes. By automating this process, you eliminate the risk of manual errors and ensure that your changelog is always accurate and up-to-date.

Detailed Breakdown

Let's break down each component to see how they work together to achieve our goal of automated changelog generation.

1. .github/release-drafter.yml

This file is the heart of our changelog generator. It configures Release Drafter to automatically categorize pull requests based on their labels. The categories defined in this file should map directly to the sections in your CHANGELOG.md file, such as Added, Fixed, Changed, and Deprecated. This mapping ensures that your changelog is well-organized and easy to read. For example, a pull request labeled feature might be automatically categorized under the Added section, while a pull request labeled bug might be categorized under the Fixed section. By carefully configuring this file, you can ensure that your changelog accurately reflects the changes introduced in each release.

Configuring .github/release-drafter.yml involves defining different categories that align with the Keep-a-Changelog format. For each category, you specify which labels should trigger inclusion in that section. This is where thoughtful planning pays off, as clear and consistent labeling practices will ensure accurate categorization. Think about the common types of changes in your repository: features, bug fixes, performance improvements, security updates, and deprecations. Create categories in your .github/release-drafter.yml file to match these change types, and then define the corresponding labels. For instance, if you use the label enhancement for new features, you would configure the Added category to include pull requests with that label. The goal is to create a system where every merged pull request is automatically categorized into the appropriate section of your changelog, making the release note generation process as seamless as possible.

2. .github/workflows/release-drafter.yml

This workflow is triggered on every push to the main branch. It uses the Release Drafter action to update the draft release with the latest changes. This ensures that your release notes are always up-to-date. The workflow typically includes steps to check out the code, run the Release Drafter action, and then commit the changes to the draft release. By automating this process, you save time and effort, and you can be confident that your release notes accurately reflect the current state of the codebase. This workflow is the engine that keeps your release notes fresh and relevant, allowing you to focus on other important tasks.

The release-drafter.yml workflow file is configured to run automatically whenever changes are pushed to the main branch. This automation ensures that your release notes are always up-to-date, reflecting the latest merged pull requests and associated labels. Within the workflow, the primary action is the Release Drafter action itself. This action analyzes the merged pull requests since the last release, categorizes them based on the labels, and updates the draft release notes accordingly. The configuration in .github/release-drafter.yml guides the action, determining which labels correspond to which sections in the release notes. By scheduling this workflow to run on every push to main, you guarantee that the draft release is continuously refined, reducing the manual effort required when it's time to publish a new release. This workflow is a cornerstone of the automated changelog generation process, ensuring that your release notes are accurate, comprehensive, and always ready for review.

3. .github/workflows/changelog-sync.yml

This workflow is the final piece of the puzzle. It pulls the generated release notes from the draft release and opens a pull request to update the CHANGELOG.md file. This automates the process of keeping your changelog in sync with your releases. The workflow typically includes steps to fetch the release notes, update the CHANGELOG.md file, and then create a pull request. By automating this process, you eliminate the risk of manual errors and ensure that your changelog is always accurate and up-to-date. This workflow is the glue that binds the release notes to your codebase, providing a single source of truth for all changes.

The changelog-sync.yml workflow is responsible for taking the generated release notes from the draft release and synchronizing them with the CHANGELOG.md file in your repository. This workflow is triggered after the release notes have been updated by the release-drafter.yml workflow. It begins by fetching the latest release notes from the draft release. Then, it updates the CHANGELOG.md file by prepending the new release notes to the top of the file, ensuring that the most recent changes are always prominently displayed. Finally, the workflow creates a pull request with the updated CHANGELOG.md file, allowing you to review the changes before merging them into the main branch. This workflow completes the automated changelog generation process, ensuring that your release notes and changelog are always in sync.

4. CHANGELOG.md

This is the file that contains your project's changelog. It should follow the Keep-a-Changelog format, with sections for Added, Fixed, Changed, and Deprecated. The changelog-sync.yml workflow automatically updates this file with the latest release notes. By maintaining a well-organized and up-to-date changelog, you provide valuable information to your users and contributors. A good changelog makes it easy for people to understand the changes introduced in each release, track progress, and identify potential issues. This file is a critical part of your project's documentation and should be treated with care.

The CHANGELOG.md file serves as the single source of truth for all the changes made in your project. It follows the Keep-a-Changelog format, which is a widely adopted standard for creating readable and maintainable changelogs. This format divides changes into several categories, such as Added, Fixed, Changed, and Deprecated, making it easy for users to quickly understand the nature of each change. The changelog-sync.yml workflow automatically updates this file with the generated release notes, ensuring that the most recent changes are always prominently displayed. By adhering to the Keep-a-Changelog format and automating the update process, you can create a changelog that is both informative and easy to maintain. This, in turn, fosters trust with your users and makes it easier for them to stay up-to-date with the latest developments in your project.

Links

For further exploration, here are the key files discussed:

• .github/release-drafter.yml
• .github/workflows/release-drafter.yml
• .github/workflows/changelog-sync.yml
• CHANGELOG.md

By implementing this setup, you'll have a fully automated, GitHub-native changelog generator that keeps your CHANGELOG.md file up-to-date with minimal effort. Happy coding!

For more information on Keep a Changelog format, check out the official website: Keep a Changelog