search

paketo-buildpacks / community

Community content for the Paketo Buildpacks project
Apache License 2.0
3 stars 8 forks source link

Improve release notes completeness #87

Open davidmirror-ops opened 2 years ago

davidmirror-ops commented 2 years ago

What happened?

Release notes for different Buildpacks are hardly human-readable, meaning that it's hard to guess:

  1. What's new? (new Features/bug fixes)
  2. Why it matters?
  3. How to use it?
  4. Contributor recognition

Sometimes it's a matter of making it consistently throughout releases and including contributor recognition.

fg-j commented 2 years ago

Perhaps it'd be easiest to standardize this by updating the template for our current release notes with a spot for human-readable summary that can be added once releases are cut.

dmikusa commented 2 years ago

I would say that buildpacks are a bit of a special case with release notes with a couple of specific challenges:

  1. Many of our releases don't really have a lot to talk about, the release is cut because there are dependencies we install that need to be bumped. Like, let's say there's a new Java version. We cut a release so everyone can use it and get fixes.

  2. The amount of buildpacks we release also makes it a challenge for any sort of human written release notes. On the Java buildpacks side, we're cutting 5-10 buildpack releases a week, plus the composite buildpacks. Occasionally, we'll cut releases for everything which is 20+ buildpacks.

I have at times added a manual note below the auto-generated notes to highlight specific very important things, like if there's a fix for a particular CVE or bug. I don't do that very often though.

I would be interested in suggestions on what we can do with the auto-generated release notes to improve the format, improve the readability, supplement it with information that's missing, and better highlight the information that is present. Just because they are auto-generated, doesn't mean we can't have nice things :) I feel like they really need to be auto-generated through, or it's going to increase our maintenance burden.

For human-written friendlier summaries, our plan is more blog posts. We've only recently started writing them, but our goal is to have a blog post for larger chunks of work that we complete, or perhaps to wrap up a 2-3 month period of smaller features we've been working on. @pivotal-david-osullivan wrote one when we added a bunch of Java debugging support. We encouraged the one for Liberty. We should probably do one for Tomee. This is definitely something we want to keep doing, and it helps to address the four points identified above (why? why? how? who?).

davidmirror-ops commented 2 years ago

+1 on not increasing maintenance burden as it affects the community in several ways.

Anything we could consider should be as automated as possible.

Probably a mix of what @fg-j suggested (a brief summary added to the template) and asynchronous blog posts wrapping up recent releases highlights

loewenstein commented 2 years ago

Just stumbled upon this. We have created a small tool - possibly inspired by release-drafter - that takes PR labels into account for grouping (feature, fix, dependency update,...), but also allows to provide a custom release notes entry replacing the PR title via a custom code block, i.e. ```release-note

Not sure if such logic would help for reaching the goal of this issue?

davidmirror-ops commented 2 years ago

08-23-2022-WG Notes: [JL] The mechanism proposed uses the PR title to feed Release Notes, will check how/what can be shared [RM] It has to be something automated to avoid additional load on an already heavy release process, interesting to see what @loewenstein can share