Release notes tooling: honor `## Text for release notes`? Or ditch it from the PR template?

[fingolfin]

trafficstars

Some PRs have neither the release notes: not needed nor the release notes: use title label but do have a ## Text for release notes section in their description. For these, we could try to extract the text in that section and insert it into the release notes... somehow?

This shouldn't be too hard, the main question I have is: how exactly would the generated entry look like? So far all generated entries are one entry in a list. Now I have a potentially arbitrary snippet of Markdown. Should I just insert it raw into the file? Should I attempt to indent it minimally? I think whatever is done should be as simple as possible and explicitly documented.

Alternatively, we might say this is not actually useful in practice, and just remove the Text for release notes section from the PR template. For the GAP 4.12.0 release notes, I had only about six PRs (out of ~192) which did not just use their title as PR description. Three of them were for "highlights" which I wrote separately into the release notes; for these in theory "inserting the Text for release notes section" could be useful... except that (a) two of them belonged together, which this feature can't deal with, and (b) since "Highlights" is the first section anyway, editing it manually was no problem.

For the other three PRs, they all contained multiple changes that belonged into different sections each. I don't see how blindly inserting a text block into the release notes would help here, either... However, it could be made useful, see issue #5006 for an idea related to that.

[ThomasBreuer]

My understanding of the creation of release notes is as follows. The script dev/releases/generate_release_notes.py can extract information from the relevant pull requests. It is based on the titles and labels of the pull requests, and (currently) does not evaluate the "body" information of the pull request.

The "Text for release notes" section can be used in two situations:

• People who are not allowed to assign labels can enter text that will be translated into the appropriate label(s) by someone who is allowed to do this. (Afterwards the "Text for release notes" can be removed.)
• If the information from labels and title is not sufficient to describe the pull request for the release notes, an explicit text can be entered here.

I think that the section in the template cannot be removed as long as the first of these points is valid. The second point is problematic as long as the information is not processed automatically (by dev/releases/generate_release_notes.py). Issue #5006 proposes a syntax that would require to extract body information. If we want to do this then it might also be useful to separate the above two aspects of the "Text for release notes" section into different sections of the template.