Feature request: Structured changelog
The [Nextflow Changelog](https://github.com/nextflow-io/nextflow/blob/master/changelog.txt) and [release notes](https://github.com/nextflow-io/nextflow/releases) are functional but.. not the easiest thing to consume. It has a few issues:
* `.txt` instead of `.md`, so it lacks any formatting or headings / softliniks
* A flat list of all merged PRs, which is typically quite a lot
* No differentiation between large and small items. A huge new feature might only get one line, whereas 4 version bumps get 4.
The difficulty in reading this means that, in practice, no-one reads it. Changes in releases often come as a surprise and the changelog is only used as "reference in hindsight", rather than an important piece of documentation that folks proactively read when upgrading.
How to write a good changelog is a whole thesis topic in itself, but I think that with minimal effort we could make it a lot more digestable:
1. Use Markdown, with links and headings and other formatting
2. Group changes into categories
3. Optionally manually note anything of particular interest at the top of each set of release notes
With a little setup, most of this can be done automatically, reducing manual work at the time of release. Typically this is done either with labels or with PR title conventions. As reference, I quite like how we do it for MultiQC now:
1. Every PR gets assigned to a release milestone and given 1 or more labels
2. At the time of release, I run a [changelog script](https://github.com/MultiQC/MultiQC/blob/main/scripts/print_changelog.py) which checks the relevant milestone, gets all merged PRs, categorises them by their label and constructs the markdown
3. I do a manual review, occasionally shuffling items around and adding anything I think is important to the top as a manual highlight. I typically do at least a "release headline" sentence with a minimal summary
4. For the GitHub releases (not `CHANGELOG.md`) I occasionally also add a screenshot or a bit more to the intro, as I think more people read these and it's easy to include file assets.
See [resulting `CHANGELOG.md`](https://github.com/MultiQC/MultiQC/blob/main/CHANGELOG.md) and [releases page](https://github.com/MultiQC/MultiQC/releases).
It would be great if we could choose some kind of convention for this and build a little automation around it.
Switching the `.txt` to `.md` is an easy first-step. Curious also to hear thoughts from @christopher-hakkaart re: docs / changelog.
1 条评论