Incompatibility between different branching strategies and release note generation

[SarahFrench]

Hi!

I recently debugged an issue with how release notes are generated in the Google provider's release process (link here). The problem was that during a release the release notes contained multiple entries from the CHANGELOG and required manual editing to delete out all but the most recent entry.

It turned out that problem was due to the use of release branches, and how that wasn't compatible with the recommended sed command for generating release notes in this repo's README (link here).

After investigating that issue I wanted to see if I could contribute to hashicorp/ghaction-terraform-provider-release

Problem

The current sed command needs all v*.*.* tags to be accessible from the commit being used to generate a release:

# making release v1.3.0 off tip of main branch

	 tag: v1.2.0	     tag: v1.3.0
	 /		    /
x---x---x---x---x---x---x---x main

So if a repo tags and makes releases using the branching strategy below it doesn't work, and too-much/all of the CHANGELOG.md file is included in the generated release note. How much of the CHANGELOG is included depends on how many release tags have made their way onto the main branch.

# making release v1.3.0 off tip of release-b branch

		   tag: v1.2.0			   tag: v1.3.0
		  /				  /
	 x---x---x release-a	 	 x---x---x release-b
	/				/
x---x---x---x---x---x---x---x---x---x---x---x---x---x---x main

Solution (used in the Google provider repo)

In the context of the problem with the Google provider, I found that we could use the same sed command but replace use of git describe with git tag when finding information about the previous release tag.

Basically this command:

sed -n -e "1{/# /d;}" -e "2{/^$/d;}" -e "/# $(git describe --abbrev=0 --exclude="$(git describe --abbrev=0 --match='v*.*.*' --tags)" --match='v*.*.*' --tags | tr -d v)/q;p" CHANGELOG.md > release-notes.txt

can be edited to this command:

export PREV_TAG=$(git tag --list 'v*' --sort=-version:refname | head -n 2 | tail -n 1)
export PREV_VERSION=${PREV_TAG//v}
sed -n -e "1{/# /d;}" -e "2{/^$/d;}" -e "/# $PREV_VERSION/q;p" CHANGELOG.md > release-notes.txt

This should still work for repos using a 'release from main' strategy, but also correct how release notes are made in repos that use a 'release from release branches' strategy.

What should we change in hashicorp/ghaction-terraform-provider-release ?

I've made a PR that makes the 2 versions of the sed command into reusable workflows, but I thought I'd open this issue as a place to discuss this problem and what the best solution could be.

[bflad]

Hi @SarahFrench 👋 Thank you for raising this!

When this reusable release workflow was created, the intention was that it would cover the 80% (probably more like 95% given the current adoption) use case of releasing providers from the default branch. When projects have more specific release processes or requirements, it can be a little difficult to maintain and test reusable workflows if the logic complexity is increased, so the recommendation becomes to borrow the necessary release pieces into your own custom release workflow.

That being said, non-default branch releases are likely a very good candidate for supporting, since I believe that would be the next most common release workflow in larger projects. To that end, I have marked this issue for discussion at our team's next triage meeting to see if this is something we want to support and if so, further discuss the preferred design.

Thanks again. 😄

[SarahFrench]

That makes a lot of sense re: difficulty maintaining lots of workflows, and I agree it's tough testing them out! I'll close out my PR to avoid clutter and influencing any discussions 😁