[DOCS]: Release notes are very noisy and inconsistent

[pndurette]

Describe the need

This is more of required changes to the release process but it affects documentation and usability:

The release notes (changelog) are very noisy, which makes it difficult to single out important functional changes (for example, at a glance from a Dependabot PR on a repo). The important features and bugfixes are lost in a sea of .md files updates, GitHub Actions workflow changes and Dependabot updates the often doesn't impact the end-user.

Might I suggest adopting something like Conventional Commits or anything similar to categorize the changes in release notes instead of a general "What's Changed"? (e.g. with Conventional Commits, updating the GitHub Actions workflows would be a chore which wouldn't even appear in release notes, same for Dependabot updates, which I see is already committing in CC).

SDK Version

N/A

API Version

N/A

Relevant log output

N/A

Code of Conduct

• I agree to follow this project's Code of Conduct

[astorrs]

+1

[nickfloyd]

Hey @pndurette thank you for the call out on this! ❤️. We do something like what you're suggesting in the Octokit repos and we're trying to propagate that type of workflow across all of the repos we own (around +70) and hopefully can get there soon. As a two-person team, @kfcampbell and I realize the value of these changes for sanity and efficiency alone; most importantly, these practices help our communities.

Thanks for the highlight here and your patience as we sand down the rough edges. I've added a task to our team board to try and tackle this in a future iteration.

[mildmojo]

Maybe an action could automate building the Changelog.md file from the release notes?

When I want to learn if there are any breaking changes between versions, I find it very difficult to read the notes now that they're split across 5 separate pages (after just one year since Changelog.md went away!). They can't be searched/grepped/skimmed all together, and they have a bunch of noise about release artifacts. I hope this isn't a standard pattern!

[kfcampbell]

Release notes are auto-generated using this GitHub feature. What we could do here is configure the generation to filter out some types of changes based on labels or accounts.

That being said, I think there's a value in showing things like markdown and Dependabot updates: our documentation (which IMO merits inclusion in releases) is written in markdown, and Dependabot updates can contain big changes (for instance, changes to the GitHub SDK client can substantially change behavior despite application code not being changed). In addition, if you're only worried about breaking changes, the provider attempts to follow semantic versioning, so you can look for a major version change. Those tend to be released infrequently, as Terraform documentation recommends no more than a single breaking change per year to be released.

[laughedelic]

I added a configuration for the auto-generated release notes (no filtering) in #2184

[mildmojo]

I wrote a small shell script using gh and jq to convert a repo's release history to a kind of Changelog.md format to enable searching and easier browsing:

#!/bin/bash

# gh-changelog.sh

set -euo pipefail

if (( $# < 1 )); then
  echo "Usage: $(basename $0) owner/repo"
  exit 1
fi

gh api "/repos/$1/releases" | jq -r '.[] | ( "# " + .tag_name,.created_at,"",.body,"\n\n" )' | less