nextflow-io / nextflow-io/nextflow

Feature request: Structured changelog

Open
#7,178 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Groovy
Stars
3.5k
Forks
811
Avg merge
2d 11h
Merged PRs (30d)
61

Description

The Nextflow Changelog and release notes 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 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 and releases page.

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing changelog.txt and the linked GitHub release notes, then compare the referenced MultiQC changelog script and resulting CHANGELOG.md. Define the release categorisation and metadata convention before planning automation. Done means releases are easier to scan in Markdown, with grouped changes and optional highlights.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, release, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.