ci: Group changelog entries for breaking changes

[helderco]

Overview

If there's a change that requires migrations from users, an easy thing we can do right now is to make them clear in the changelog. In Python, I'm used to read the release notes for packages before updating them.

The convention, according to https://www.conventionalcommits.org is to add a ! before the ::

• chore!: Move packages to core
• feat!: Rename field X

RFCs

1. I thought about using break: instead, but decided to go with the convention above in case we decide to adhere more to it later. WDYT?

2. Not sure about the title for the "other" group: Changes. We need to consider there will be logs without breaking changes, so it needs to make sense on its own.

3. We could also group by features and bug fixes, but I think we need to have the discipline to add these prefixes to all commits for that (basically adhering to the conventions above).

Signed-off-by: Helder Correia

[gerhard]

If there's a change that requires migrations from users ... according to https://www.conventionalcommits.org is to add a ! before the ::

• chore!: Move packages to core
• feat!: Rename field X

Big yes to this!

1. I thought about using break: instead, but decided to go with the convention above in case we decide to adhere more to it later. WDYT?

These conventions are sensible, I also think we should stick to them.

2. Not sure about the title for the "other" group: Changes. We need to consider there will be logs without breaking changes, so it needs to make sense on its own.

I would not add the third category. Users care about fixes & features, the rest is noise. Instead, I would add a link to the full changelog which should cover everything, e.g. https://github.com/goreleaser/goreleaser/releases/tag/v1.6.0

Here's another good example: https://github.com/cli/cli/releases/tag/v2.7.0

3. We could also group by features and bug fixes, but I think we need to have the discipline to add these prefixes to all commits for that (basically adhering to the conventions above).

Yes, we should absolutely do this.

We should also add list of contributors & full changelog (see the examples above). I have been using the full changelog for years, and find it extremely helpful when looking for unintended side-effects - found a bad one in PostgreSQL in 2019.

[helderco]

2. Not sure about the title for the "other" group: Changes. We need to consider there will be logs without breaking changes, so it needs to make sense on its own.

I would not add the third category. Users care about fixes & features, the rest is noise.

Not what I meant. There's two with this PR: 1) breaking changes; 2) other changes (title "Changes"). I'm referring to the catch-all.

[...] I would add a link to the full changelog which should cover everything

Good point, I will add that.

[TomChv]

We could also group by features and bug fixes, but I think we need to have the discipline to add these prefixes to all commits for that (basically adhering to the conventions above).

So ensure that we always follow the convention, we can use a GitHub action.
After a quick research, I found that one : https://github.com/webiny/action-conventional-commits and we can use https://github.com/commitizen/cz-cli or an extension for the format.

Indeed, I think we could also automatically add label according to file changed or commit/PR prefix

[aluzzardi]

Nice!

Left a clarification comment

[aluzzardi]

If I understand this correctly, this will put anything!: inside Breaking Changes.

Is the convention to call them break!: ...?

[helderco]

The convention is the exclamation point, no matter the prefix.

[helderco]

Could be fix!: or feat!:.

[4x0v7]

I believe this is Conventional Commits, correct?

[4x0v7]

BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change

A link to the CC site could be helpful 🙂

[helderco]

There's a footnote to it in the contributing guidelines, and I also mentioned it in the description of this PR.

[4x0v7]

Thanks, don't know how I missed that. Actually, I think I came from the changelog link to the commit so my context was the commit, rather than the pull request that contained it. That's good to know.