Releases: Use a single, curated CHANGELOG file?

[tony]

Hi, thank you for the project!

A single, curated release file, with changes sorted top to bottom by how important they are to the user in the eyes of the maintainer will deliver the best experience.

Current situation

As of October 23rd, 2023 at v3.1.5

Release notes mention "See Releases page on github"

There's no changelog file.

A single, curated CHANGELOG file

GitHub Releases aren't a replacement for a changelog files to most downstream users.

A changelog file can be connected to a git tag (making linking easy), can be scrolled through, use built-in searching, and is portable. A few extra minutes of preparation can help convey the benefits and impact of a release.

Example: Curating releases

https://github.com/graphql-python/graphene-django/releases/tag/v3.0.0

In its current state, unimportant package updates and typos are strewn across, when the user is likely trying to see a summary of changes from 2.x -> 3.0.

In contrast, see a page like this (separate project: Graphene): https://github.com/graphql-python/graphene/wiki/v3-release-notes#whats-new-in-graphene-v3

Though it'd take more time prepare - I think the usefulness to end users would make it worth it.

Example: GitHub releases vs Changelog

GitHub releases requires paginating through many releases, including prereleases that may not be important from the user's perspective once a final version is release. There's typesetting and spacing that is more indicative of a blog.

Changelogs can be scrolled through, as an example (separate project: Strawberry) https://github.com/strawberry-graphql/strawberry/blob/main/CHANGELOG.md.

Similar requests

• Add a CHANGELOG graphene#149 (graphene project, rather than graphene-django itself)