PROCESS CHANGE: use GitHub native release notes generator

dsimansk commented 5 months ago

Expected benefits

Currently we use Kubernetes release-notes tool to generate release notes markdown files. The flow of updating release note:

Run GH action
Take generated markdown
Update particular release with markdown

There's an issue with current default PR template. Whenever there are multiple code blocks, it's parsed as code block until the last closing element. Hence that's producing very poorly formatted outputs.

Examples and discussion per Slack threads: https://cloud-native.slack.com/archives/C04LKEZUXEE/p1706185040469779 https://cloud-native.slack.com/archives/C04LY4Y3EHF/p1706177567962819

With GH action we can keep very similar format, being sorted with existing labels already. We might drop dependency bumps from the notes. I'm not sure if there is a lot value in it, since mostly they are hidden as being too long.

It's possible to publish release with generated notes included. Either with gh cli or API call.

Use automatically generated release notes
$ gh release create v1.2.3 --generate-notes

https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#create-a-release

In this flow we could drop manual trigger of release notes and iterate on the included one:

Release is published with generated markdown
Update particular release markdown as needed in release view

Expected costs

Changing to GH generated release notes should be quicker and less demanding on release leads. The cost of introducing the change are approax. a few days/week to introduce the template, implement changes on release.sh script and test it.

Example config: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuration-options

# .github/release.yml

changelog:
  exclude:
    labels:
      - ignore-for-release
    authors:
      - octocat
  categories:
    - title: Breaking Changes 🛠
      labels:
        - Semver-Major
        - breaking-change
    - title: Exciting New Features 🎉
      labels:
        - Semver-Minor
        - enhancement
    - title: Other Changes
      labels:
        - "*"

Timeframe

Next release - April '24 very likely.

I'm willing to drive the process.

dprotaso commented 5 months ago

+1 from me

psschwei commented 5 months ago

+1

converge commented 4 months ago

I'd like to propose a second option for streamlining the release process. Having utilized Goreleaser extensively in the past years, and it's proved to be a great open source tool to manage and automate releases.

With Goreleaser, we gain the following benefits:

Dry-Run Releases: We can test our release process without actually publishing, ensuring everything runs smoothly.
Automatic Changelog/Release Notes: By leveraging conventional commits, Goreleaser can automatically generate changelogs and release notes directly in GitHub.
versioning: Goreleaser intelligently calculates the next release version based on the content of commits. For instance, if the current version is 1.5.0 and the next version includes 1 fix and 1 new feature, the next version will be 1.6.0. Similarly, if the next release contains only fixes, the version will be 1.5.1.
announcements: Goreleaser can automatically announce new releases, saving us time and effort in dissemination.

dsimansk commented 4 months ago

@converge thanks for the recommendation! AFAIK some parts of the project has previously used goreleaser as well. There's extensive release.sh script in our case that we are probably not going to refactor just yet. That script is covering most of the heavy lifting parts with tagging and publishing to Github, image registry etc.

This change of proposal aims to simplify the part of publishing the release notes. The motivation is quiet simply our default PR template doesn't play well with release note tool we utilize currently, and current native Github feature seems good enough.

knative / community