Question/suggestion for v2.0.0-rc.0 release candidate

[behnazh-w]

I was looking at the changelog for v2.0.0-rc.0 release candidate and couldn't figure out the breaking change that is resulting in a major version bump. I think using the Breaking Change notations in conventional commits can improve the changelogs. But because the commit history can't change now, it would help to add the breaking change to the release description.

Also, to make the changelog more readable, it would be good to run commitizen (also available as a GitHub Actions workflow) to filter out chore and other insignificant commits that don't need to be communicated to users of slsa-verifier.

[ianlewis]

Hi, Thanks for the suggestions.

The reason for the bump is that the slsa-verifier CLI has changed in a backwards incompatible way. It now uses different flags (e.g. --source-tag vs. the old --tag) and has different commands (e.g. slsa-verifier verify-artifact ..., slsa-verifier verify-image ...).

I'll ask @asraa to add a human readable overview of the changes to the release.

[jenstroeger]

The reason for the bump is that the slsa-verifier CLI has changed in a backwards incompatible way. It now uses different flags (e.g. --source-tag vs. the old --tag) and has different commands (e.g. slsa-verifier verify-artifact ..., slsa-verifier verify-image ...).

@ianlewis in that case there should be a commit whose message contains that “breaking change” indicator — either in the message title or footer of the commit message, see here for proper examples.

Also note that multiple commits in the release candidate do not comply with the conventional commit spec. As @behnazh-w suggests, please consider using automation tools like commitizen to manage your commits and releases.

Otherwise, release version numbers and changelogs of this project are unreliable and more of a sentimental version than machine-usable for checking supply-chain integrity.

I'll ask @asraa to add a human readable overview of the changes to the release.

The purpose of commitzen (and similar tools) and conventional commits is to automate exactly such tasks. However, that requires contributors and maintainers to write meaningful and compliant commit messages…

[ianlewis]

Again, Thanks for the suggestions. We do that for some of our PRs but we haven't always been consistent about the format and labeling them accurately. We're definitely looking to automate things in the future but it will take a bit.

In the mean time I've updated the release description a bit to include all the changes since v1.3.2 and mark the change I referred to as breaking in the release notes.

[asraa]

Thank you both: yes, I'm well aware of convenional commit naming. I'll add a presubmit job that can enforce that, so hopefully we won't need to rely on detecting that ourselves.

I also added the migration from previous commands to the current command in the breaking change description.

I've never used commitizen, but I'll take a look and integrate it. I do dislike the chore/fix updates inside release notes, and it'd be nice to not include those. Thank you for detecting these. I'll make sure the release for 2.0.0 includes a better release note description. Thank you for detecting it on the pre-release so I can make some changes.

[asraa]

Do either of you have recommendations for enforcing convenional commits? I've had a project only do it for PR title using: https://github.com/amannn/action-semantic-pull-request and seen some that check for the commit message in the PR body (expecting the squash and merge to copy and paste the body)

EDIT: So far, see https://github.com/slsa-framework/slsa-verifier/pull/372. I'll help enforce marking BREAKING CHANGES in PR body

[behnazh-w]

@asraa Please have a look at this workflow that runs Commitizen to check both the title of the PR and all commit messages of the PR's branch.

You can also use Commitizen like here to bump and generate the changelog automatically based on the commit messages.

I do dislike the chore/fix updates inside release notes

By default chore commits will not bump a version and will not appear in the changelog but fix commits will increment the PATCH version. I think it's a good idea to keep the default configurations and make sure fix commits appear in the changelog.