Automate Release Notes a.ka. Changelog with release please
Tags: github
Published: 2022-08-30 23:20:25

Curious about what is being released into a project? 

[**Keep a Changelog**](https://keepachangelog.com/en/1.0.0/), it keeps your audience up to date with the latest changes at a glance!

And even better, automate the CHANGELOG.md each time a PR is merged into the base branch:
- by using [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), it creates a standard [type](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type) for having a commit message format: `type(optional scope): message`
- and adding [release please](https://github.com/googleapis/release-please) to your repository as a [github action](https://github.com/googleapis/release-please#github-action-recommended)

## How to automate the Changelog

1 - Create `.github/workflows/release-please.yml` at the root of the repository
```
$ mkdir .github && cd .github && mkdir workflows && cd workflows && touch release-please.yml
```

2 - Modify the changes on `release-please.yml` and choose the [release-type](https://github.com/google-github-actions/release-please-action#release-types-supported)
```
# release-please.yml
on:
  push:
    branches:
      - main
name: release-please
jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v3
        with:
          release-type: simple
```

3 - Add the commit message and merge the branch. Make sure to follow conventional commits.

4 - Some changelog sections will not be displayed. To override the [default](https://git.io/JqCZL), update the release-please.yml with `changelog-types` with the field `hidden:false`
```
# release-please.yml
...
        with:
          release-type: simple
          changelog-types: >
            [
              { "type": "build", "section": "Build System", "hidden": false },
              { "type": "ci", "section": "Continuous Integration", "hidden": false },
              { "type": "chore", "section": "Miscellaneous Chores", "hidden": false },
              { "type": "docs", "section": "Documentation", "hidden": false },
              { "type": "feat", "section": "Features", "hidden": false },
              { "type": "fix", "section": "Bug Fixes", "hidden": false },
              { "type": "perf", "section": "Performance Improvements", "hidden": false },
              { "type": "revert", "section": "Reverts", "hidden": false },
              { "type": "refactor", "section": "Code Refactoring", "hidden": false },
              { "type": "style", "section": "Styles", "hidden": false },
              { "type": "test", "section": "Tests", "hidden": false }
            ]
```

5 - Configure [default to PR title for squash and merge commits](https://github.blog/changelog/2022-05-11-default-to-pr-titles-for-squash-merge-commit-messages/) when merging a pull request

6 - See the automated changelog PR - [github link](https://github.com/sofiama/tutorial-release-please/pull/7)

![automated changelog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fdqh1sjwz3ahdr1rb4le.png)

Using the `Squash and merge` PR in github will group the commits into one commit, displaying just one line with the `PR#`. While not using the `Squash and merge` PR, each commit will be listed on its own, as displayed under the section "Continuous Integration"

![Squash and merge](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1um5ua1mkkhz3gca6coe.png)

The individual commit history of the PR can still be viewed by clicking the PR# in the CHANGELOG.MD

![PR commit history](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/st390m183blxzu7tokbw.png)

Release notes can also be [overridden](https://github.com/googleapis/release-please#how-can-i-fix-release-notes) in the body of the PR with the changelog reflecting the changes

![override release notes](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ssuc3o5b9l2ir7683kjr.png)

![changelog reflecting changes](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kgliqcty70bxn9zf160h.png)

## Simplify merged PRs
Configure merged PRs to keep a cleaner history in the base branch

1 - Add a branch protection rule to [require branches to be up to date before merging
](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule)

![rebase branch](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sg3ljhwuwr9kngw98qih.png)

2 - Use [squash and merge commits on PRs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests) to keep a cleaner commit history in the base branch

![squash and merge branch](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/92x7vnmaqfuj1vh7ik43.png)

3 - [Delete branches automatically](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches) after a merge

![delete branch](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k4t54hlefef89u5rbgan.png)

---
<sub>The Github repo for this tutorial can be found [here] (https://github.com/sofiama/tutorial-release-please)</sub>