Merge release notes

[rarkins]

What would you like Renovate to be able to do?

When more than one version is being updated, support the option to combine semantic release notes.

Did you already have any implementation ideas?

Can only work for known, semantic changelog formats. Probably a new option, opt-in. Some inspiration from https://github.com/Belco90/octoclairvoyant

[Belco90]

Hi there! I just ran into this issue by chance, octoclairvoyant creator here 😅

Since my app was partly inspired by renovate, I'm willing to contribute if you need some help here, by giving more explanation about what I did in my app or anything else you find useful.

There is an alternative to implement this which would be generate corresponding url with filled querystring so octoclairvoyant can render this semantic release notes combined per group. An example url: https://octoclairvoyant.vercel.app/?repo=renovatebot%2Frenovate&from=23.95.0&to=24.22.3

I understand you would prefer to get the releases notes combined within renovate messages itself, but just offering this alternative in case it's useful.

Let me know what you think!

[rarkins]

Hi @Belco90!

I think it would be best for users (which are both self-hosted and in the app) to have the functionality in Renovate so that it's not dependent on another service.

However as such a feature would be opt-in, we could maybe add a link to your app as a default feature, if we can work out the right way to insert it.

What has been your approach for combining non-semantic changelogs? e.g. ones written by hand or with inconsistent headings, etc? I'd have a small concern about linking to any URL which produces no output or gibberish, so curious to hear your approach.

I'd be really excited to see this land sometime soon if you can help out.

[Belco90]

I basically wrote a summary within the repo's README. You can see first I normalize the changelogs groups, then I group them by the same changelog type, and finally apply some priority to sort them properly.

The normalization is a really important step, which includes some sanitization to ignore string case and other chars. You can find that implementation here.

However this only works for semantic changelogs. What about non-semantic ones? Well, at the moment my app it's just normalizing and grouping them without any priority so they are not displayed in any particular order. I have few ideas to improve this: the main one is if not semantic changelogs are found, then group and sort them by the release version. So all the X.0.0 versions are majors, then X.Y.0 are minors and everything else are patches. From here, I can apply the same grouping and sorting.

[Belco90]

I found an example where I should apply the improvement I mentioned in my previous comment: https://octoclairvoyant.vercel.app/?repo=jest-community%2Fjest-junit&from=v10.0.0&to=latest

Since I don't have a particular title for each group of changes, I can just group them based on semantic versioning. That doesn't mean it's gonna be 100% correct since one change inside a major can be a minor or a patch, but it's the best guessing I can do I think 🔮

[HonkingGoose]

However as such a feature would be opt-in, we could maybe add a link to your app as a default feature, if we can work out the right way to insert it.

If we start linking from our bot to Octoclairvoyant, we might cause them to exceed their allowance, either on the "Vercel open source plan" bandwidth/traffic allowance side of things. Or maybe even on the GitHub API side, though they already limit the amount of request users can fire at the GitHub API from Octoclairvoyant without further authentication.

What has been your approach for combining non-semantic changelogs? e.g. ones written by hand or with inconsistent headings, etc? I'd have a small concern about linking to any URL which produces no output or gibberish, so curious to hear your approach.

@Belco90 gave me some examples of really bad input to his Octoclairvoyant app... It will always be hard to clean up bad stuff programatically when the input can be "basically any text humans can come up with". It's the old "garbage in, garbage out" problem, but with changelogs... 😄

Why not limit our scope to "known-good changelogs that follow sane conventions"?

I'm thinking of having an array called knownGoodSemVerChangelogSources, which only contains manually added known-good sources, like say renovate, semantic-release, and so on. The idea is to not show the link button if the package is not in the array. That way we don't have to worry (as much) about showing gibberish.

[Belco90]

If we start linking from our bot to Octoclairvoyant, we might cause them to exceed their allowance, either on the "Vercel open source plan" bandwidth/traffic allowance side of things. Or maybe even on the GitHub API side, though they already limit the amount of request users can fire at the GitHub API from Octoclairvoyant without further authentication.

I believe Vercel limits shouldn't be a problem! Most of the restrictions apply to the number of deploys you can do (we are far far away from that limit) and the usage of Serverless functions (Octoclairvoyant only uses one for authenticating the user through GitHub OAuth). In terms of traffic allowance, we have 1TB of bandwidth, which I think it should be more than enough too.

@Belco90 gave me some examples of really bad input to his Octoclaivoyant app... It will always be hard to clean up bad stuff programatically when the input can be "basically any text humans can come up with". It's the old "garbage in, garbage out" problem, but with changelogs... 😄

Why not limit our scope to "known-good changelogs that follow sane conventions"?

I'm thinking of having an array called knownGoodSemVerChangelogSources, which only contains manually added known-good sources, like say renovate, semantic-release, and so on. The idea is to not show the link button if the package is not in the array. That way we don't have to worry (as much) about showing gibberish.

I'd say this is an actual problem. I don't want users to land on any Octoclairvoyant link that is broken or doesn't offer any info because the updated package doesn't have a proper semantic release format. Limiting the scope of knowns sane conventions seems a good approach for a first iteration.

[HonkingGoose]

How do we feel about putting a link to Octoclairvoyant in the PR body for some known SemVer packages, and make the new feature opt-in via a config option?
I think most of the value is in providing an easy way to get a full overview of what changes between releases.

Seeing as we already know the old version and the version we're upgrading to, we can fill in the Octoclairvoyant comparator query string ourselves.

Proposed behavior

GIVEN A user is currently using release-please bot 10.0.0
WHEN Renovate bot creates a PR: Update release-please to 11.13.2
THEN Renovate checks if user is opted in to the "show octoclairvoyant link" feature
AND Renovate checks if package update is in the knownGoodSemVerChangelogSources array

IF user is opted-in AND package is in the knownGoodSemVerChangelogSources array
THEN Renovate bot adds a new section to the PR body:

Get an overview of changes between version `10.0.0` and `11.13.2` by going to Octoclairvoyant: https://octoclairvoyant.vercel.app/?repo=googleapis%2Frelease-please&from=v10.0.0&to=v11.13.2

ELSE show default PR body text.