changelogs for Cabal-3.14 and (incomplete) cabal-install-3.16 #10323

ulysses4ever · 2024-09-06T15:20:39Z

I added a WIP changelog for the tool which is easier, I think: we just remove all the tiny changelog files and at 3.16 will generate and append an update for this WIP (and it becomes the final release-notes/cabal-install-3.16...md).

Some doubts I have:

I got a bunch of messages from changelog-d, which I don't understand: https://gist.github.com/ulysses4ever/881571e08f0fff4f8dc4d63880d4e52f
~~I'm not sure about deduplication: should one change touching Cabal and cabal-install be mentioned in both changelogs?~~
- It seems having a change in both changelogs is fine.
Wiki says that a PR removing the little changelog files should go separately, why is that? Why not one PR?
- For 3.12, it was one PR: https://github.com/haskell/cabal/pull/10124/files We should update the wiki...

Template B: This PR does not modify behaviour or interface

E.g. the PR only touches documentation or tests, does refactorings, etc.

Include the following checklist in your PR:

Patches conform to the coding conventions.
N/A ~~[ ] Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).~~

fgaz · 2024-09-06T15:47:13Z

I got a bunch of messages from changelog-d, which I don't understand: https://gist.github.com/ulysses4ever/881571e08f0fff4f8dc4d63880d4e52f

"Missing PRs" is the list of PRs that don't have a changelog entry. You should have a quick look at them to ensure we didn't forget entries for user-relevant ("Template A" now) PRs.

"Extra (unmerged) PRs" is the list of changelog entries with an invalid PR number (that is, the PR number wasn't found in the log). These are almost always typos and should be fixed.

ulysses4ever · 2024-09-06T16:47:10Z

Thanks for the explanation! I wish this info was put at a very visible place. Maybe in the messages the tool prints.

"Missing PRs" is the list of PRs that don't have a changelog entry. You should have a quick look at them to ensure we didn't forget entries for user-relevant ("Template A" now) PRs.

There are 174 unique entries on this list (I updated it so that it only shows unqie ones btw). This feels a little intimidating...

geekosaur · 2024-09-06T17:05:41Z

One complication is that you will get PRs listed as missing because they're for a different component than you're dumping changelogs for.

ulysses4ever · 2024-09-06T17:29:49Z

Yes! It looks like a significant shortcoming of changelog-d...

ulysses4ever · 2024-09-07T17:25:52Z

I submitted a PR against changelog-d which will fix the missing PR message to only report PRs missing from the whole set of changelog-d/ entries, not just the entries for the given package. https://codeberg.org/fgaz/changelog-d/pulls/17

geekosaur · 2024-09-07T17:28:12Z

Some future changelog-d work that should reduce if not eliminate duplication: allow specifying multiple packages, and check that a given changelog entry matches any of them. That way, if an entry specifies both Cabal and Cabal-syntax, it will only be output once.

ulysses4ever · 2024-09-08T22:32:38Z

I plan to run my fork tonight to hopefully get a more manageable list of PRs to double-check for exclusion from the release notes.

ulysses4ever · 2024-09-09T03:07:10Z

I plan to run my fork tonight to hopefully get a more manageable list of PRs to double-check for exclusion from the release notes.

Okay, I tried it and it only struck about 20 PRs (bringing the number down to 154). As far as I see, the issue is that changelog-d is not smart enough to account for backports. For example, take #9578, which was backported and certainly appeared in 3.12: changelog-d still reports it as missing because that particular PR, of course, did not appear in 3.12, and the tool thinks that it should be in 3.14 release notes...

At this point, I consider the "Missing PR" feature of changelog-d dysfunctional and suggest we move forward and wait until users uncover any unaccounted changes. While undesirable, missing things in release notes is not the end of the world. For future releases, it'd be great to teach changelog-d about backports.

geekosaur · 2024-09-09T15:23:20Z

Keep in mind that changelog-d (nor any other tool that doesn't use the GitHub API) doesn't have access to information such as whether it's a backport. I also wonder about trying to get features added to changelog-d that only we would use; I was careful about that with respect to my additions, but they weren't very intrusive to the other (two, I think?) users to begin with. Injecting a passive requirement to use Mergify for backports is probably over the line.

geekosaur

Mostly formatting, but a few questions should get some consideration. I don't think they should hold it back, though.