Switch to keepachangelog format

[glensc]

Current release notes are just pure noise for end user:

• https://github.com/containers/skopeo/releases/tag/v1.1.0

Examples:

Add upstream and testing container images
Add upstream and testing container images
there is a brew formula for skopeo
vendor github.com/containers/common v0.14.0
vendor github.com/containers/image/[email protected]

(yes, there are duplicate lines there)

Therefore a project was created under a flag "Don’t let your friends dump git logs into changelogs":

• https://keepachangelog.com/en/1.0.0/

The purpose of the changelog is to list notable changes for the release. Changes that are meaningful for end-user.

I'd rather see no release notes than just git log that is done now. If I want to see git shortlog, I can do that from the console.

[mtrmac]

Thanks for you report.

As much as I feel your pain, and I’m also unhappy about the current state of this, I think we basically need to automate this (both the collection of data and enforcement that good enough change logs are written), or it’s not going to happen by default; and with N releases with bad change logs, the motivation to write a very good change log for release N+1 is not great if it’s going to be buried behind a bad change log the next time again.

Not that I immediately know how to automate this. A PR template might help as a reminder, but it’s too convenient to just delete it, and it doesn’t help collect the data. A CI check that requires an addition to the change log would complicate use of Dependabot.

I’m sure this is a solved problem somewhere, and close to home Podman does well. There might be something easy we can do to improve.

[glensc]

Some ideas

If the merge request volume is not too high, one can require that changelog entry is added from PR itself.

You may need merge=union in .gitattributes to resolve conflicts better:

• https://github.com/eventum/eventum/blob/v3.8.17/.gitattributes#L27

do note that this still does not work in GitHub, but works okay with git command-line rebase: isaacs/github#487

A satisfactory solution would be also some automation that is able to collect changelog from pull request titles and categorizing with labels. I'm sure such tool exists, just haven't found one myself yet.

GitHub has a flow that you create .yaml file for each changelog entry, that information is used to make generate changelog prior release: https://docs.gitlab.com/ee/development/changelog.html

[rhatdan]

@glensc Is this still an issue?

[glensc]

@rhatdan doesn't seem anything changed if looking latest release:

• https://github.com/containers/skopeo/releases/tag/v1.2.0

[rhatdan]

Ok so this is a Human doing the release issue (Often me). As @mtrmac says, I don't see an easy way to fix this through software that will not just be ignored by busy humans.

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[lsm5]

@mtrmac @vrothberg @rhatdan have things changed on this front since the last time this issue was visited?

[vrothberg]

I suggest to do two things when (manually) creating the changelog:

1. Make it a formatted list, not just lines.
2. Try to filter out commits that are not useful to users.

I think we can close the issue and try to be better in the future.

[lsm5]

Thanks @vrothberg . Closing..

[mwgamble]

I just found this issue after reading the release notes for v1.8.0:

https://github.com/containers/skopeo/releases/tag/v1.8.0

I think this issue is still very much a problem. The very first note in that list of patch notes is "v1.7.0". Not only does that not meaningfully describe the changes made in the relevant PR (a problem in of itself), it's useless noise for the wrong version!

The patch notes for v1.9.0 are just as bad:

https://github.com/containers/skopeo/releases/tag/v1.9.0

This text:

Bump github.com/docker/docker

Appears three times for the same release!

@rhatdan If you're looking for ways to improve these automatically generated patch notes with more automation, here are a couple of recommendations:

1. Remove duplicate lines
2. Remove PRs generated by Dependabot
3. Remove PRs that only touch development-related files

Here's a few examples of PRs that only touch development-related files, that end users definitely do not care about:

• Use an updated CI image with OCI-capable registry #1679 (end users don't care how the test suite is run)
• [CI:DOCS] Makefile: include cautionary note for rpm target #1682 (end users don't care about comments in makefiles)
• [WIP] Makefile: set CONTAINERSCONFDIR based on the OS #1507 (end users really don't care what's in your makefiles)
• [CI:BUILD] Cirrus: Migrate multiarch build off github actions #1661 (end users don't care who your CI provider is or where container images are built)