tools: Add ChangeLog helper script

[hoffie]

Short description of changes

This PR adds release tooling to validate the ChangeLog for completeness.

• find-missing-entries: Will find missing PRs/Issues by scanning the Github milestone and the git log.
• add-missing-entries: Will edit the ChangeLog and add those found entries.
• group-entries: Will group newly added (or even existing) entries by their category while using a pre-defined category order (within the script).

Context: Fixes an issue?

Does this change need documentation? What needs to be documented and how?

• The CHANGELOG: syntax should be suggested in the PR template. This is done as part of this PR.
• Translation logic still has whitespace issues
• Existence of this tool should be documented in the release checklist: contribute/en/Release-Process: Document changelog helper jamulussoftware/jamulus#2257 jamuluswebsite#708

Status of this Pull Request

Works, but open to improvements.

What is missing until this pull request can be merged?

Reviews.

Checklist

• I've verified that this Pull Request follows the general code principles
• I tested my code and it does what I want
• My code follows the style guide (no bash style guide)
• I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
• I've filled all the content above

---

Why is #1993 listed here? It was tagged for 3.8.1, not 3.8.2, but was actually closed, not merged, and replaced with #1994. Just thought it might be something to check in your tools.

Originally posted by @softins in #2249 (comment)

It's listed because it's part of the history in master (see a8853b6). Might be a stray reference.
The tool uses Github PRs and their milestone to find relevant PRs. However, we might have forgotten to assign a milestone. That's why the script also scans git log and uses the references there as well.

Finally, let this PR be handled properly in the tool...:
CHANGELOG: SKIP

[softins]

When trying this out, I was in a working directory that had my own fork as the base repo for gh (in .git/config):

[remote "origin"]
    url = [email protected]:softins/jamulus.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    gh-resolved = base

That meant it couldn't view any of the upstream PRs:

tony@pi:~/jamulus $ gh pr list

There are no open pull requests in softins/jamulus

If I switched to my other working directory that only had jamulussoftware/jamulus as a remote, gh pr worked fine:

tony@pi:~/jamulus-upstream $ gh pr list

Showing 20 of 20 open pull requests in jamulussoftware/jamulus
......

One suggestion would be to replace gh with $GH everywhere, and then at the top do:

GH="gh -R jamulussoftware/jamulus"

It would then look at the upstream PRs whatever remote the user had set as the gh base.

Alternatively, prominently document the need to set gh-resolved to the upstream repo if running multiple remotes, and/or abort the script with an explanation if gh pr view N returns non-zero.

Once I understood the problem, it was easy to change the gh base in my normal working directory, to point to the upstream repo by default.

[softins]

If there is no title suggestion, do you want to create a placeholder as a reminder that it needs filling in? Or to leave the PR so that find-missing-entries still flags it up?

[hoffie]

Hrm, I think it already should (unless I misunderstand)?

The current logic should be like this:

• If there is a CHANGELOG: line in the PR, it is interpreted.
• If the line equals SKIP, the whole entry is skipped. There will be no placeholder either. This is intended for PRs like this one which do not necessarily have to be part of the ChangeLog.
• If the line is not SKIP, it is used verbatim.
• If there's not CHANGELOG: line, the PR title is used.

This probably implies that we could do us a favor by editing PR titles and/or adding CHANGELOG: comments on merge.

[softins]

One suggestion would be to replace gh with $GH everywhere, and then at the top do:

GH="gh -R jamulussoftware/jamulus"

A better way to do this would just be to set and export GH_REPO:

export GH_REPO=jamulussoftware/jamulus

Then there is no need for $GH

[hoffie]

I was in a working directory that had my own fork as the base repo for gh

Ah, didn't think of that, but that's certainly important to handle properly.

export GH_REPO=jamulussoftware/jamulus

Sounds good, I've added that.

[softins]

Looks good to me.

[pljones]

Is this aiming for 3.9.0? Should it have a milestone set?

[ann0see]

Can sed edit "in-place" so we don‘t need to copy loads of data into a variable?

[hoffie]

sed does support in-place editing, but I don't think those features are sufficient to do what's needed here. Feel free to suggest an alternative, that's what I came up with in absence of any better approaches.

[ann0see]

Maybe include a FIXME comment explaining that this could be improved

[ann0see]

After thinking and looking at the past change logs, it seems as if we got shorter in our description style of changes. Is this good or bad?

jamulus/ChangeLog

Line 62 in 8bbff18

- Client/Server: Improved the version output on the command line to give more detail and Qt version (#2187).

for example is not that verbose

jamulus/ChangeLog

Lines 260 to 263 in 8bbff18

	- GUI: Moved the Ping and Delay stats from the Settings window to the main window (#1762):
	This was partly to work around a Mac issue with updates to the settings window (#1643)
	and is actually an improvement anyway, as the settings window does not need to remain open.
	(contributed by @dcorson-ticino-com and @softins)

For example gives a lot more detail.

We could still give users a little advice how to use the new feature (and not just give a commit-message style entry).

[pljones]

The change log entries shouldn't be limited to a single line, for sure. In my view, they shouldn't, however, attempt to explain the problem and what was done to solve it -- only to say what has improved and link to the full description (i.e. issue, if available, and pull request). So anything saying "Improve " is a bit redundant :).

Improved the version output on the command line to give more detail and Qt version

could be

Version description now provides more detail and Qt version

As it covers all cases (GUI, non-GUI, client, server) adding a limiting clause is redundant. However, "more detail" doesn't really say anything, either... What changed? :)

I don't think "contributed by" needs saying -- the format is condensed: the text in brackets at the end is a list (separated by commas, no "and") of contributors. If that needs explaining, say it once.

---

So what I want:

• Section, if it's a singular limiting feature. If multiple areas are affected, don't use the "tag:" format, use the content if it's necessary to limit the scope of the description - it may be obvious.
• Description: Hopefully, the CHANGELOG tags will help get better entries but "What should be there" needs thinking about
• Source: the issue (if raised) and PR
• Who: the contributors

[hoffie]

Section, if it's a singular limiting feature. If multiple areas are affected, don't use the "tag:" format, use the content if it's necessary to limit the scope of the description - it may be obvious.

I really like the tag-style as it makes it possible to group entries and to enable Changelog skimming. As a Linux user I could skip all Windows entries. I agree thought hat there are types of changes which are hard to tag, so there may be exemptions.

Source: the issue (if raised) and PR

I think we haven't been consistenly adding the issue numbers as well. The changelog helper currently doesn't (but it probably could when the Github metadata is up-to-date (Fixes:))

I don't think "contributed by" needs saying -- the format is condensed: the text in brackets at the end is a list (separated by commas, no "and") of contributors. If that needs explaining, say it once.

I've just taken the style which has been there (I think it moved from coded by to contributed by which is a bit more generic), but I'm open to changing that.

In general, I'd rather like to get this PR merged at some point. It's been sitting around for quite some time, yet it is the tool I've been using to generate all the recent changelog PRs. We can always iterate on further improvement ideas later.

[pljones]

Section, if it's a singular limiting feature. If multiple areas are affected, don't use the "tag:" format, use the content if it's necessary to limit the scope of the description - it may be obvious.

I really like the tag-style as it makes it possible to group entries and to enable Changelog skimming. As a Linux user I could skip all Windows entries. I agree thought hat there are types of changes which are hard to tag, so there may be exemptions.

Yes, by "Section" I mean "UI:" or whatever. But "UI, Command Line, Client, Server, Windows, Linux, MacOS, Android, iOS:" seems a bit unhelpful... it's really helpful if the change only affects one area and becomes less helpful the more areas the change covers.

[ann0see]

Going to approve this now.

[ann0see]

Maybe include a FIXME comment explaining that this could be improved