Consider keeping CHANGES?

[tony]

Hi, and thank you for the project!

Around 20f71ab in #1643 a decision was made to use GitHub releases instead of CHANGES. I can't find the conversation on the tracker, if there was one! (sorry, if there was please let me know!)

I'm a bit surprised by this decision. The reason why is releases have been in my experience, notoriously difficult to page through as scale and they're not as portable or resilient as a changelog file. They are more of an complement, not a replacement to the changelog..

Having a single file changelog has benefits: over time, they can be sync'd to the git tag, e.g. flask's 1.1.3 changes). They can also be searched and scroll through very efficiently. It's sometimes possible to use a symlink from CHANGES to/from CHANGES.md or CHANGES.rst to get the benefit of formatting when viewing and not breaking the link to the old file.

Any more information on why the single file changelog was deprecated in favor of releases?

[Andrew-Chen-Wang]

I think, if the decision is to continue using GitHub changes, you may as well create a GH Action that takes the release and prepends the description to the CHANGES file and commit.

[tony]

Some projects highlight of what's valuable in the release. e.g. a longstanding bug that was quashed, a new method or changed method, upcoming deprecation, etc.

The releaser usually has a good idea of what's significant and it's fresh on their mind. Sometimes they'll also arrange them tidily: New features, security related, bug fixes, breaking changes, deprecations, etc.

• Django's release notes, 4.0's for example, and deprecation timeline
• Flask's release notes: e.g. 2.0.x
• Numpy
• gunicorn

[chayim]

@tony I'm neither against nor for maintaining a CHANGES file. Currently we use the release-drafter to augment our releases, and then edit the list. Have you seen an action (or similar) that could help maintain this?

What I don't want to have happen, is our not updating CHANGES, once we reinstate.

[ThiefMaster]

Please bring back the "simple" changelog (CHANGES.md or whatever).

• It's a huge mess to go through a paginated list of GitHub releases if you want to quickly look for changes between two versions or breaking changes.
• Prereleases are not interesting for most people, but e.g. to find the potential breaking changes in 4.0.0 I can't just look at the 4.0.0 release because it's referencing the prereleases - IMHO the stable release should also include all changes from prereleases and maybe a separate list of changes since the last prerelease for those who are upgrading from a prerelease

[tony]

I'm neither against nor for maintaining a CHANGES file. Currently we use the release-drafter to augment our releases, and then edit the list.

release-drafter (workflow) is an automated system. Tools like that won't work for curated release notes since it's the maintainer's discretion to convey what's valuable.

For CHANGES.md, a mixture of these can help:
a. In PRs the maintainer deems noteworthy: request contributors modify CHANGES.md along with any docs
b. Post-merge of PRs: have a maintainer update the CHANGES.md / docs while it's fresh on the mind. e.g. if it's a deprecation, bug, breaking change, etc.
c. Before PyPI release and git tag of final release: double check / sort / organize the changelog notes for the release.

Prioritizing / what would go to the top:

• New Features
• Anything requiring intervention on the user's part: version compatibility (e.g. python, redis) Breaking change like default settings, API changes, deprecations
• Bug fixes
• Other misc and small contributions

[chayim]

While yes, the release-drafter is an automated system, our use of it isn't. We currently rely on the drafter only to draft release notes - which in turn are edited. This is a (small) improvement on the past CHANGES usage which was ordered by descending date.

I completely understand the value of grepping through release, rather than a browser. Given our use of the release drafter, do you think the following changes to solve both needs:

1. When we publish pre-releases (again, this is fairly new) rather than link to prior changes, we include the full list of changes as part of the text (including the version) - since the last release (i.e including all release candidates).
2. Prior to release to PyPI, the same release process takes the release-drafter changes and prepends that in the CHANGES file, as formatted currently in the RELEASES view?

Our current use of the release drafter is breaking changes, then features, bugs, finally followed by maintenance. WDYT?

[Andrew-Chen-Wang]

There are lots of changes happening here at the moment, so keeping a summarized CHANGES would be better. However, I'm pretty sure what appears in the changes for dependabot is GitHub release descriptions, so whatever is in the release description would go into the CHANGES.

I think to not miss anything, I would just parallel the CHANGES with the GitHub release descriptions. It'll be come messy, but it'll be synchronized.

[chayim]

Ya'll have me convinced. Let's see what we can do to reinstate - and automatically in some fashion. Thank you for the explanation and the patience folks. What an awesome community!

[tony]

@chayim Will the missing versions also be added to CHANGES, e.g. 4.0.0, 4.1.0?

It just came up today for me that being able to see the file at a glance would be helpful

[chayim]

Yup! @dvora-h will be restoring this shortly.