Hi, thank you for the project!

A single, curated change file is ideal for conveying the value of changes across releases.

Note: This is a bikeshed / matter of taste from a downstream user perspective, apologies if this draws away from technical discussion.

Background

In 0.3+ release notes in the Changelog file was replaced by linking to GitHub Releases.

Elsewhere, the core strawberry project maintains a changelog as of 0.209.7.

Proposal

• Maintain CHANGELOG.md

• Hand-curate changelog instead of machine-generate it

• Keep GitHub Releases also

  It drive engagement and has benefits, but not be a replacement for what a changelog does.

Comparison

Changelog file (CHANGELOG.md)

Pros:

• Portable
• Scrollable: changes across versions, 0.3.0 -> 0.2.1
• Linkable:
  • Anchor link to versions
  • Link to git tag releases via URL

Cons:

• For super active projects (e.g. Linux Kernel?), it'd need to be broken up into multiple files
• Takes more effort to maintain

Releases (GitHub Releases)

Pros:

• Automated adding of changes via PRs between git tags
• Mentions / shoutouts to contributors (for this I think it's worth keeping)
• Can show up in news feeds (for those who like that)
• Comparison tools:
  • Automated tool adds diff link
  • Select box to compare

Cons:

• Automated changes aren't a replacement for a maintainer's handmade release notes

  2 minutes of effort would give a better outcome than the automated notes.

  Example: Mention of pre-commit updates, doc updates, intermixed with bug fixes

• Bloat (in the eyes of a downstream user that simply wants to see what's happening)

  • Paginated, not scroll friendly
  • Blog-like design (white spacing, type setting)
  • Unnecessary elements: Asset files (I don't know if anyone uses these?)

• Not portable