search

pypa / setuptools

Official project repository for the Setuptools build system
https://pypi.org/project/setuptools/
MIT License
2.32k stars 1.14k forks source link

Restore logical ordering of changelog #4314

Open jaraco opened 1 week ago

jaraco commented 1 week ago

I'm not sure putting the changes in numerical order is correct. Having them in temporal order provides better fidelity about what changes are included in a given release. In the current ordering, it looks like v69.5.1 includes no changes from v69.5.0, when in fact, 69.4.2 was released between 69.5.0 and 69.5.1, so the changelog now seemingly incorrectly signals that v69.5.0 includes v69.4.2 and that v69.5.1 had no significant changes. Same applies for v69.3.1 between v69.4.0 and v69.4.1.

Also, dates are shown in the rendered changelog.

I think we should revert this change, despite the confusion it might cause. If someone wants a changelog sorted by version number, they should re-render the changelog that way. You can mechanically convert from logic oldering to sorted versions, but not vice-versa (without additional information from the commit history).

Originally posted by @jaraco in https://github.com/pypa/setuptools/issues/4304#issuecomment-2066199209

jaraco commented 1 week ago

@hugovk Based on my description, do you want to advocate not to revert the changes?

hugovk commented 1 week ago

Fine by me to revert the changes.

For some reason, I ended up at the https://github.com/pypa/setuptools/blob/main/NEWS.rst which doesn't have the dates. I probably got the new release notification to https://github.com/pypa/setuptools/releases, then went to the repo homepage and looked for the changelog file.

It's a nice touch to add the dates during the docs build! Perhaps a link could be added to the top of the raw NEWS.rst that points repo visitors to the rendered https://setuptools.pypa.io/en/latest/history.html, and strip out that link during the docs build?

Original ordering (date) Current ordering (version)

In the current ordering, it looks like v69.5.1 includes no changes from v69.5.0, when in fact, 69.4.2 was released between 69.5.0 and 69.5.1, so the changelog now seemingly incorrectly signals that v69.5.0 includes v69.4.2 ...

Ah right, I see what you mean.

and that v69.5.1 had no significant changes.

For me, both of these indicate v69.5.1 had no significant changes. I was actually wondering why something was even released if it has no significant changes, and guessed it might be some docs thing or other.

So was v69.5.1 released to include the v69.4.2 bugfix?

I think it might be a good idea to also explicitly list the bugfix under v69.5.1. When there's a forked branch for bugfixes like this, I don't assume all previous changes are in the current version.