Replace use of `paultyng/changelog-gen` in our release process

[SarahFrench]

Background

Current changelog generator tool and process

Currently we generate entries for the CHANGELOG using paultyng/changelog-gen. This tool relies on the provider repo containing a .changelog folder that contains release notes for PRs as text files. When the tool is used it takes in several inputs, most importantly the branch and commit SHAs of the last and next release. This is necessary for generating release notes that describe only the changes that are about to be released.

$ changelog-gen \
    -repo $REPO_NAME \
    -branch main \
    -owner hashicorp \
    -changelog ${MM_REPO}/.ci/changelog.tmpl \
    -releasenote ${MM_REPO}/.ci/release-note.tmpl \
    -no-note-label "changelog: no-release-note" \
    $COMMIT_SHA_OF_LAST_RELEASE \
    $COMMIT_SHA_OF_LAST_COMMIT_IN_CURRENT_RELEASE

(Sourced from the wiki)

The tool prints the release notes to the users terminal, where they copy & paste the output into a PR for updating the CHANGELOG file on a release branch.

Proposal

We should investigate migrating away from this tool. The tool is created by an ex-HashiCorp employee and the tool hasn't been updated since 2020 and we aren't able to maintain the tool and/or add any necessary updates.

Option 1: hashicorp/go-changelog

One potential alternative is to migrate to using the HashiCorp-owned hashicorp/go-changelog tool. From the commit history this repo appears to be a copy of paultyng/changelog-gen created by Paddy Carver at roughly the time when paultyng/changelog-gen stopped being updated.

After migrating to this tool we could investigate adapting it to a GitHub action, to remove the toil associated with generating changelogs in your terminal (see the wiki).

PROS:

• HashiCorp-owned tool that can be maintained
• Strongly resembles the current tool we use

CONS:

• Differences in behaviour need to be investigated. For example, .changelog txt files are named slightly differently.

Option 2: Changie CLI tool

This is a tool that's been recommended as another replacement. There are apparently more automation features, and it's nice to use a tool with documentation and a community around it.

Here is a GitHub action that already exists for this tool : https://github.com/miniscruff/changie-action

PROS:

• More automation features (need to confirm)
• OSS tool that has a community around it, including guides and documentation

CONS:

• Need to assess how much lift would be required to change, versus benefit
• If it doesn't address our needs we are less able to advocate/implement changes.

Option N: ???

There may be other options out there

What kind of contribution is this issue about?

Release tooling

Related PR(s), if any:

N/A

Details

When I first downloaded the tool to my M1 Mac I experienced some problems when installing the latest version. I can't remember details (e.g. if the problem was M1, or more current Go versions) but I needed to add this note to the wiki as a result:

Note: go install github.com/paultyng/changelog-gen@91f787dc0cf1eedf016a444740cd28a4f1370e4 for Go 1.17+ Using this commit is necessary to get a version that supports the -no-note-label flag.

This made the use of that tool feel brittle.

[rileykarson]

I'm surprised we didn't switch to the HashiCorp-maintained version Paddy had developed- it was based on their experiences here! I thought we already had, honestly.

[c2thorn]

Looked into hashicorp/go-changelog, and what it would take to switch over.

This is immediately blocked by https://github.com/hashicorp/terraform-provider-google/issues/18095

go-changelog reads the changelog entry files instead of parsing the PR's themselves like paultyng/changelog-gen. We would need to get the changelog entry files generated again in order to be able to switch over in the release process. There is currently no other use for these files that I know of, and we've gone almost a month without noticing they were gone.

Switching over for the (manual) release process would require:

• Fixing https://github.com/hashicorp/terraform-provider-google/issues/18095
• Updating the changelog and release note templates in MM to be compatible with hashicorp/go-changelog. They use different variables & template functions.
• Editing the release script in https://github.com/hashicorp/terraform-provider-google/wiki/Release-Process#on-wednesday

There is a given template for the changelog, but I'd imagine we would want to keep our release note formatting similar to what it has always been unless there is a reason to otherwise.

Using the changelog files instead of the PR's themselves would also change the process for editing changelogs after PR's are merged and pushed. Right now, maintainers can quickly edit the generated downstream PR release notes if they notice that the changelog is incorrect. Switching over to the changelog files would require an additional PR to edit the corresponding entry file. While not a huge deal, it does seem slightly less convenient.

[c2thorn]

Side note: we have a copy of go-changelog in MM: https://github.com/GoogleCloudPlatform/magic-modules/tree/main/tools/go-changelog We use it for checking the release notes of PR's in a GHA