Categorize GitHub Repository Release Notes by Content for a Nice Look

2022-10-07

Introduction

When creating release notes in a GitHub repository, you can click the “Generate release notes” button in the top right corner to automatically input the changes made since the last release.

This is already quite useful, but with just a little additional configuration, you can categorize these changes by content, which I will introduce here.

Procedure

1. Create a configuration file

Create a .github/release.yml file with the settings for how to categorize the release notes.

The official documentation for configuration options is available here:

Automatically generated release notes - GitHub Docs

You can automatically generate release notes for your GitHub releases

docs.github.com

For reference, here’s the configuration I created:

changelog:
  exclude:
    labels:
      - ignore-for-release

  categories:
    - title: 🎉 Feature
      labels:
        - Feature
    - title: 🐛 Bug
      labels:
        - Bug
    - title: 🔥 Remove
      labels:
        - Remove
    - title: ⚡ Performance
      labels:
        - Performance
    - title: ♻ Refactoring
      labels:
        - Refactoring
    - title: ✅ Testing
      labels:
        - Testing
    - title: 💚 CI/CD
      labels:
        - CI/CD
    - title: ⬆ Dependencies
      labels:
        - Dependencies
    - title: 🔒 Security
      labels:
        - Security
    - title: 🛠 Development
      labels:
        - Development
    - title: 📝 Documentation
      labels:
        - Documentation
    - title: Other Changes
      labels:
        - "*"

When creating release notes, if there are merged Pull Requests with labels corresponding to the labels setting in the difference since the last release, the release notes content will be categorized under the corresponding title category name.

I might have created too many categories for my first attempt at categorization, and I’m not sure if I’ve covered everything, but for now, I’ll try to operate with the above settings and make changes as needed to make it more user-friendly.

By the way, I referred to @azu’s github-label-setup repository when creating the labels.

GitHub - azu/github-label-setup: 📦 Setup GitHub label without configuration.

📦 Setup GitHub label without configuration. Contribute to azu/github-label-setup development by creating an account on GitHub.

github.com

2. Add labels to Pull Requests according to the settings

The configuration is now complete, so all you need to do is add labels to Pull Requests according to their content.

3. Click the “Generate release notes” button when creating release notes

After merging a few Pull Requests and creating release notes, clicking the “Generate release notes” button as mentioned above will display release notes categorized by content like this!

Thoughts

While it’s nice to have more readable release notes, adding labels to Pull Requests is a bit of a hassle!

I usually add labels to issues, so adding them to Pull Requests as well is cumbersome. In my mind, Pull Requests are related to issues, so adding labels to both issues and Pull Requests feels redundant.

I usually link the corresponding issue to the “Development” section of the Pull Request, and when the Pull Request is merged, the issue is automatically closed. I was hoping to find a way to automatically add the same labels from the linked issue to the Pull Request when linking it to the “Development” section, but I couldn’t find such a trigger (if anyone knows, please let me know).