let’s discuss how to move towards changelogs / release notes for ImageJ / Fiji / SciJava repositories. It would be great to come up with a semi-automatic strategy that can be used by core developers and contributors.
In gitter we discussed this already to some extend and want to continue here.
Some of my thoughts:
Where do we need changelogs?
There could be any subset of these options (tell me if I missed one):
- a changelog for each (core) repository, attached to releases or in a separate file
- a changelog for each Fiji release, maybe living on the Wiki
- a changelog entry for each upload to an update site, included in the
What’s part of the changelogs?
- user related changes
- developer related changes (distinguishing between fixes / features / breaking changes)
- responsible developers / contributors
How are they created?
- manually (per release / upload)
- semi-automatic: we retrieve descriptions of changes and give the option to edit them before writing them into a changelog
- fully automatic: no edit step in between
How would a (semi)automatic changelog work?
Retrieve commit messages
- pro: I got the feeling that for many ImageJ repos the commit messages are more informative than the PRs (if the PR even exist)
- contra: they are not editable without rewriting the history. I think this is a mayor downside.
- contra: there would be way more commits than PRs to review before releasing a changelog
Retrieve PR messages
- pro: editable
- pro: we could use a template
- pro: with templates the PR readability would improve and it might be easier to review them
- contra: not always a PR for all changes
- contra: we need to change our habits / this is additional work for maintainers to enforce a template
Technically both is possible, I played a bit around with retrieving commit messages, here is my test.
The scikit-image people have a semi-automatic approach using PR messages. I think we can learn a lot from them. Have a look at their PRs, their script to generate release notes and the release procedure where the script is used.