We’ve been working on our release process to get everyone more Syft, Grype, and Grant enhancements faster, and I wanted to have a discussion about how our release notes want to represent dependencies.
We’re trying to keep our released artifacts more recent, for example not letting scan-action depend on the old version of Grype for very long.
As a consequence of this more frequent release of downstream dependencies, we end up generating release notes that are pretty empty aside from dependency bumps, which looks kind of weird.
This post is meant to address two questions:
How should we represent dependency bump changes in our release notes?
How should we mechanically accomplish that representation (what Dependabot settings, label configs, Chronicle settings, etc.)
For the first question, there are a couple of considerations:
We want to leave things that don’t affect the released software at all entirely out of the release notes. (For example, if the Syft PR validator uses a new version of actions/checkout, this has zero impact on the actual bytes you get when you install syft and should be omitted.)
We want to highlight things that change the way something works (for example, Grype uses Syft internally; bumping Syft in Grype is a real change to Grype, even if dependabot did it.)
We want to avoid junking up the release notes with little minor dependency changes, like if we bumped a patch version of a minor library, this probably doesn’t deserve its own bullet point.
Therefore, my proposal is 3 changes:
PRs that don’t affect the released software at all get changelog-ignore
PRs that are a “core dependency” get modeled as enhancement, e.g. bumping Syft in Grype is labeled as an enhancement
Dependabot PRs that are not a “core dependency” but do affect the released artifact (e.g. bumping a dependency that Syft uses) go in a new “Dependencies” section of the release notes, which is collapsed in a <details> section by default. (This requires an enhancement to chronicle.)
We could distinguish between 2 and 3 by setting dependabot to ignore core dependencies and having separate automation that bumps them.
Does this make sense to everyone? Any feedback or alterations here?
We have plenty of patch releases only containing bugfixes; these should probably not be considered enhancements. And, depending on the changes there’s a possibility that the changes don’t affect the downstream projects at all, so summarily labeling these as enhancements doesn’t seem right to me. But generally a non-patch release probably does bring new functionality.
If a version change of a core dependency includes a non-patch version increase from the previous one, it could probably be tagged as an enhancement or bugfixes otherwise? Does this change much; maybe we just include all dependency updates together with some different behavior depending if it’s a “core” vs. not?
Could/should these updates be a lot more verbose and include the entirety of the changelogs in the downstream releases? I, for one, might like to go to a Grype release page and see something like:
** Dependency Updates**
Syft 1.33.7
New features:
* Uses zero memory!
* Reads new things!
I don’t think we would want to see this for everything, but for the “core” dependencies – things in the github.com/anchore org, the incoming changes are probably mostly pertinent across the tools. If we do this verbose downstream inclusion, it should probably include all changelogs/release notes since the last version update.
I’m in agreement that any update to a library that affects a code path within a tool
should be included in the release notes.
I’m not sure we need to stop using dependabot for this stuff, we just need a way to identify the specific dependency updates as “core” or not, I think.
I think we could probably use a combination of labels: and ignore and allow in dependabot yaml to achieve this (docs). But if we’re building additional automation for bumping core dependencies it might make sense to do it there too.
Maybe we should change chronicle to include dependabot PRs in Dependencies section at the bottom of the release notes anyway? (Except for label ecosystems that don’t get in the release, like github_actions, as changelog-ignore.)
