Improve changelog

[KatrinIhler]

Currently the changelog for minor releases of the stable version doesn't include changes that also went into legacy, so it's hard to find out what actually changed when updating. Also the usability for release managers could be improved, e.g. to figure out where exactly the cut-off point was between the old and new release.

[KatrinIhler]

Open question: Possible to do that automatically when creating the release?

[KatrinIhler]

Thought about this for a bit and decided that it's best to see how well Github still generates release notes once the editor and/or Admin interface are switched over to the new branching model. If it works well, maybe we should do that for Opencast as well and just edit them a bit afterwards to add / highlight the most relevant information. That would also mean no longer distinguishing between changelog & release notes.

A few disadvantages that come to mind:

• Info no longer in the documentation
• Requires more careful tagging of PRs
• Could potentially be very long
• Doesn't distinguish between changes that went directly into stable vs those that bubbled up through legacy
• Maybe difficult to decide what to diff a major release against? Probably latest minor release of the previous version?

Thoughts welcome.

[gregorydlogan]

Thought about this for a bit and decided that it's best to see how well Github still generates release notes once the editor and/or Admin interface are switched over to the new branching model. If it works well, maybe we should do that for Opencast as well and just edit them a bit afterwards to add / highlight the most relevant information. That would also mean no longer distinguishing between changelog & release notes.

Having now done the work (unreleased):

• Requires more careful tagging of PRs

This is going to be required to make this work properly. Which is fine, but we should probably turn the relevant bot(s) and PR check(s) on so that things can't/won't go in without appropriate tags

• Could potentially be very long

Yep, though I feel like our velocity is generally low enough that it shouldn't be a problem aside from major releases

• Doesn't distinguish between changes that went directly into stable vs those that bubbled up through legacy

Yeah, though if I'm upgrading to N.m do I care if it was X.o or A.b which introduced the change?

• Maybe difficult to decide what to diff a major release against? Probably latest minor release of the previous version?

So this caught me up at first. GHA automagically pick the last release in the branch, unless it's a major release in which case it picks the latest release. So if I release 16.8, it'll diff against 16.7. If I push the tags for 16.8 and 15.9 at the same time you get a race to see which publishes last for your 17.0 release. This, IMO, sucks, but I can see why it's happening. It's at least easy to fix in the GH since you can just tell the release which version to diff against and it will regenerate things. This is less ideal when part of your GHA workflow takes that output and commits to the codebase. In short, your docs changelog now lives either exclusively in GH, or is now a copy of the GH version and thus no longer the source of truth.

I would agree that we should deploy this with admin, editor, and studio and then wait for a few releases (plus a major, ideally) to see where the bugs are. Once we've got those ironed more or less out we can do the upstream codebase.

[KatrinIhler]

@gregorydlogan Do you remember what the status is here? I know this was waiting for... something. I guess we want to wait until the submodule thing is through?

[gregorydlogan]

Yeah let's do the submodule stuff first. Unless this is ready as is, in which case merge it and we can do whatever needs doing in a follow on pr.

I'm half tempted to remove the need for this entirely as part of the submodules stuff and switch over to the gh automated release notes, but that might be a bridge too far.

[KatrinIhler]

I'm half tempted to remove the need for this entirely as part of the submodules stuff and switch over to the gh automated release notes, but that might be a bridge too far.

That's basically what this means by now actually, the PR is already merged.