Changelog?

[armsnyder]

With the new release process, the CHANGELOG.md is no longer updated automatically by tf-release-bot. Do we need to do anything to react to this change? For example I think using (GH-123) to reference PRs doesn't work anymore.

TF reference docs: https://www.terraform.io/docs/extend/best-practices/versioning.html#changelog-specification

Example commit from tf-release-bot in the past: d48f13a9bfb54a161b2bd25fa7de92340f65f3ea

[armsnyder]

Hey @nagyv @timofurrer I don't think we've had much progress on this, at least that I've seen. Is this something we agree could be improved still? There've been a few issues -- #743, #521, #663.

Something as simple as formalizing a Changelog format and expecting the person merging a PR to update the Changelog immediately after merging could work.

One question I have is how the Changelog relates to the GitHub release notes, and whether we need to maintain both.

[nagyv]

One question I have is how the Changelog relates to the GitHub release notes, and whether we need to maintain both.

The release notes are automatically populated and they need to be updated. In the past two releases, it meant a copy&paste and some formatting.

[timofurrer]

In general, I think for now it's okay if we curate the CHANGELOG.md file by hand before a release or from time to time as I did in #864. Once this becomes to much of a burden we can always think about automation - I think our time is currently spent wiser in other areas :D.

I propose to close this for now :)

[armsnyder]

I appreciate your willingness to curate the changelog by hand 🙇, but I would still like to keep this issue open, since we have had problems maintaining it in the past. And TBH I'm worried we'll get worse at it now, since pushing to main is now restricted for maintainers.

At the very least we should commit to a process and write it down.

Since I took some notes on strategies I've seen employed by other TF providers, I'll include those here...

Option: PR author includes a changelog entry in the PR

Click to expand...

Using go-changelog or some variant, have the PR author include the changelog entry, in either the PR description or in a new file created and named after the PR to avoid conflicts. Automation updates the main CHANGELOG.md file after the PR is merged.

Pros:

• Main branch is always releasable
• Changelog entry is written when knowledge of the change is most fresh

Cons:

• Burden on PR author

References:

• https://github.com/hashicorp/terraform-provider-aws/blob/main/.github/workflows/changelog.yml
• https://github.com/hashicorp/terraform-provider-aws/blob/main/.github/workflows/generate_changelog.yml
• https://github.com/cloudflare/terraform-provider-cloudflare/blob/master/.github/workflows/changelog-check.yml
• https://github.com/cloudflare/terraform-provider-cloudflare/blob/master/.github/workflows/generate-changelog.yml

Option: Automation creates the changelog update PR before a release

Click to expand...

Using git-chglog or similar, have a step in the release workflow that creates a PR, generating a changelog and allowing a maintainer to edit and merge before the release goes out.

I'm not super clear on how this works exactly and would need to research more.

Pros:

• ???

Cons:

• ???

References:

• https://github.com/newrelic/terraform-provider-newrelic/blob/main/.github/workflows/changelog.yml

Option: Handcraft the full release changelog before a release

Click to expand...

This is almost always done by pushing to main branch directly.

Pros:

• We can decide to do this now without much effort upfront.

Cons:

• Manual repetitive work for a maintainer.
• Requires more than one maintainer to coordinate quickly during release time to avoid missing changelog entries for late PRs. Or else push access to main, which we recently disallowed for maintainers.

References:

• https://github.com/PagerDuty/terraform-provider-pagerduty/blob/master/CHANGELOG.md
• https://github.com/grafana/terraform-provider-grafana/blob/master/CHANGELOG.md
• https://github.com/integrations/terraform-provider-github/blob/main/CHANGELOG.md
• https://github.com/DataDog/terraform-provider-datadog/blob/master/CHANGELOG.md
• https://github.com/hashicorp/terraform-provider-helm/blob/main/CHANGELOG.md
• https://github.com/hashicorp/terraform-provider-google/blob/master/CHANGELOG.md

Option: Handcraft a changelog update after every PR merge

Click to expand...

This is always done by pushing to main directly.

Pros:

• Clear responsibility; the maintainer who merges writes the entry.

Cons:

• Requires maintainers to have push access on main branch, which we disabled recently.

References:

• https://github.com/hashicorp/terraform-provider-azurerm/blob/main/CHANGELOG.md

[timofurrer]

What also would be nice is some automation to put the corresponding CHANGELOG.md section into the GitHub release ...

[armsnyder]

Something that could work for that: https://github.com/hashicorp/terraform-provider-google/blob/424ea88caf0f5cd1ac1d43b7924d6491d3d18b93/.github/workflows/release.yml#L40

[timofurrer]

@armsnyder I think I'm in favor of option 1 Option: PR author includes a changelog entry in the PR. However, this mustn't necessarily be the PR author, but could be the maintainer merging the PR and before that pushing the changelog to the branch (given it's been allowed)

Another nice thing would actually be to add a git trailer to the merge commit if not already in one of the commits on the source branch. Then something like go-changelog would generate the changelog from that instead of files in the source tree ... what would you think about that? (I remember that GitLab itself does something similar edit: https://docs.gitlab.com/ee/development/changelog.html#overview ...)

[RicePatrick]

For what it's worth, I'm in agreement on option 1 as well. I think it's easier to review for as opposed to a trailer in the merge commit, as it's something that can be actively reviewed during the PR as opposed to needing to happen during merger (which would inherently not be reviewed as it happens post-review.)

[github-actions[bot]]

Marking this issue as stale due to 120 days of inactivity. If this issue receives no comments in the next 30 days it will be closed. Maintainers can also remove the stale label.

Please comment with more information if you would like this issue to remain open.