(Semi-)automating Changelog generation for releases

[hoffie]

Based on an idea by @pljones, I want to try generating the boilerplate for the upcoming release's changelog automatically. This should be rather straight-forward via some scripting. In order to keep the wording consistent, I propose adding the relevant text as a comment in the PR. This can be done by the PR author (@ann0see: Maybe that would be a good addition to the planned PR template?), by contributors or by @jamulussoftware/maindevelopers . PRs with no such special comment will be listed by the title in the boilerplate, but can still be edited, of course.

This is an optimization attempt and not a change in processes. We should just be careful -- as we used to -- about assigning each PR to the proper milestone (at least when merging).

Format: CHANGELOG: <Text> on a single line
Example: #1731 (comment)

Doing that at merge time has the benefit that the information around the PR is still fresh. It also provides early transparency (and possibility for further improvement).
Doing it as part of a comment (and not as part of the PR/commit itself) avoids conflicts in the ChangeLog file.

[ann0see]

Hmm, yes that seems like a good process. Do you propose to include it in the CI?

[hoffie]

Do you propose to include it in the CI?

Not sure yet. I'd suggest trying it out manually first. If it works, we can judge whether it makes sense to further automate it by providing a manual CI job or even an automatical one. Step-by-step... :)

[dcorson-ticino-com]

Please add to a template, I will forget every time otherwise :)

[ann0see]

Just requested your review here: #1827

[hoffie]

FYI, #2257 is the relevant PR.

[gilgongo]

Nice! Does/can the <text> be used to order the log according to the type of the PR? We've usually tried to group them in the list by client and server-related, docs, internal etc. Come to think of it, could we also use it to generate a (separate) list of PRs that need documentation changes? We've missed a few of those in past.

[hoffie]

If users are allowed to addl abels to their own tickets (I think they are?), we could add two checkboxes there:

• No need for documentation
• Website update needed, I have added the needs-website-update label
• Other documentation

?

[gilgongo]

Ah yes - always forget about labels. Dunno why I didn't think of that before! I think simple "Needs documenting" would be fine as we can then just round them all up as needed (usually it's only the ones also tagged for a release that matter)

[hoffie]

Yet another idea: Would it make sense to reverse the logic, i.e. have users add a "No docs needed" label? That way you could search for all issues without this label. It would also mean that we err on the safe side, i.e. reduce the risk for forgetting something.

What do you think?
Are you planning to add a PR for the issue template?

[gilgongo]

Hehe - I guess that might encourage people to think if it really doesn't need docs (and sometimes it's not initially clear on some PRs) every time they look at it. So shall we try that? Will mean the vast majority of PRs will have it though. I'd not been planning to update the template - I'd just added a "needs documentation" label to the list.

[hoffie]

Will mean the vast majority of PRs will have it though.

At least that would make it explicit. :)

I'd not been planning to update the template - I'd just added a "needs documentation" label to the list.

Hrm, I think some kind of trigger will be needed -- either submitters should have it in their checklist or approvers/mergers in theirs.