Add changelog / release notes for new releases

[BGrasnick]

Which document would you like to address?

The text for releases.

What is the issue?

As of now, releases have no text at all explaining the changes between versions. This is crucial to find out important and/or breaking changes between kepler versions (e.g. switchting from bcc to libbpf or some other important underlying changes)

How do you suggest this is fixed?

It works in kepler-operator and the only difference I see is that it has

  create-release-branch:
    ...
    permissions:
      contents: write

Maybe this would already fix it? The GitHub docs for actions seem to confirm this:

Work with the contents of the repository. For example, contents: read permits an action to list the commits, and contents:write allows the action to create a release. For more information, see "Permissions required for GitHub Apps."

[sthaha]

@BGrasnick , unfortunately, that isn't how it works. We make the release and then edit the release in Github itself where you can choose to auto generate release notes.

It is worth exploring - https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes and using conventional commits - https://www.conventionalcommits.org/en/v1.0.0/

[SamYuan1990]

https://github.com/softprops/action-gh-release#-external-release-notes @sthaha and @jiere maybe we can try this?

[sthaha]

I feel the difficult part is ...

      - name: Generate Changelog
        run: echo "# Good things have arrived" > ${{ github.workspace }}-CHANGELOG.txt

which if we followed (insisted on) conventional commit may help

[SamYuan1990]

I feel the difficult part is ...

      - name: Generate Changelog
        run: echo "# Good things have arrived" > ${{ github.workspace }}-CHANGELOG.txt

which if we followed (insisted on) conventional commit may help

I hope we can start with change log file, as there maybe some nit fix as https://github.com/sustainable-computing-io/kepler/pull/1064 for example in our git commit log.

[sthaha]

@SamYuan1990 yes, I agree that would be a great start.

[jiere]

I vote conventional commit :) Content is 1st, tool is 2nd. We may discuss and cherry pick a subset of specifications here to guide all contributors for their commits.

My first simple idea is that all the issues tickets(feature or bug) should be able to 1:1 mapping to specific PR commits through the comments, each PR should and must have only 1 commit.

Another difficulty is how to judge the conventionality of the commits' comment? Not sure if there is any BKM for such check in PR submit phase.

[SamYuan1990]

I vote conventional commit :) Content is 1st, tool is 2nd. We may discuss and cherry pick a subset of specifications here to guide all contributors for their commits.

My first simple idea is that all the issues tickets(feature or bug) should be able to 1:1 mapping to specific PR commits through the comments, each PR should and must have only 1 commit.

Another difficulty is how to judge the conventionality of the commits' comment? Not sure if there is any BKM for such check in PR submit phase.

emmmm so what will happen to https://github.com/sustainable-computing-io/kepler/commit/8c6c8b9dd6272902edd46f28b5d1ad92337de5c6 bot commit like this?

[sthaha]

@SamYuan1990 Good point if we are following conventional commits it should make it easier to filter out these commits from the changelog generated.

[jiere]

so what will happen to 8c6c8b9 bot commit like this?

IMO, such dependabot related commits could be ignored for CHANGELOG

[SamYuan1990]

so what will happen to 8c6c8b9 bot commit like this?

IMO, such dependabot related commits could be ignored for CHANGELOG

dependence bump up should be an item in CHANGELOG. I suppose we can start from manually change log before we got a way to auto generate it. IMO, the change log, as release note is for kepler user. It's should be briefly and they can understand what's in the release with basic information as container image address and key feature's update in quick.

[jiere]

Maybe we could do exploration on other mature open source projects to learn some experience. i.e. those CNCF Graduated projects. If someone in our community has similar experience to share, we will be pretty much appreciated of course.

[SamYuan1990]

Maybe we could do exploration on other mature open source projects to learn some experience. i.e. those CNCF Graduated projects. If someone in our community has similar experience to share, we will be pretty much appreciated of course.

I would like we have a 1st pr with changelog in briefly 1st and then we can enhance our approach to generate the change log later. wdyt? @jiere

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.