[FR] Releasing: include link to changelog in GH release

What’s the problem this feature will solve?

I’m subscribed to this repo’s release notifications (thank you for making GH releases!)

When a new release is made, I want to check the changelog to see if I need to upgrade right away, or make some changes to a project.

This is my flow:

1. Open release notification e.g. https://github.com/pypa/setuptools/releases/tag/v59.1.1
2. Click to go to repo homepage: https://github.com/pypa/setuptools
3. Look for a link to the docs.
4. It’s not the one at the top right, that’s a link to https://pypi.org/project/setuptools/
5. Scroll down to the README
6. See links for Installation Instructions, distutils-sig mailing list, bug tracker, PSF Code of Conduct, Tidelift’s Learn more and Tidelift security contact. None of those.
7. Check the badges.
8. One of those is “docs: passing”, click that
9. Scroll down to find History in the left menu, click it
10. Bingo!

Describe the solution you’d like

Please could you include the https://setuptools.pypa.io/en/latest/history.html link in the release body? Then it’s a single click from release to the changelog.

Alternative Solutions

No response

Additional context

I see https://github.com/jaraco/jaraco.develop is used for creating the GitHub release:

https://github.com/jaraco/jaraco.develop/blob/main/jaraco/develop/create-github-release.py

Perhaps the changelog link could be added to project_urls in setup.cfg, then extracted from repo.get_project_metadata() (it’s a "Project-URL").

Then passed as a new parameter to project.create_release(tag), and used in the GitHub API call as body:

self.session.post(releases, json=dict(tag_name=tag, name=tag))

https://github.com/jaraco/jaraco.develop/blob/main/jaraco/develop/github.py

Code of Conduct

• I agree to follow the PSF Code of Conduct

[septatrix]

I strongly think that a better and cleaner solution will be to add the changelog url to the project_urls inside setup.cfg and optionally embed the changes in the github release (although this might be a bit more complicated).

First and foremost not everyone looks in the GH releases. Adding a link to the project_urls or even inside the README will be seen by many more people. Furthermore when looking at an older release in GH I would like to see the changes for that release. With a link to the documentation this would not be the case. Instead the changes should be embedded inside the release. This is also robust against a possible url change in the future which would otherwise result in all the links being broken. There already exist many tools for automatically generating such a changelog which can be easily used inside a github workflow.

[jaraco]

Nice!

Oh, that’s interesting. Setuptools appears to have a stale or customized badge. Most skeleton-based projects use RTD directly. I would want to support that scheme too (and maybe just switch Setuptools to align with the skeleton).

One tweak I’ll want to make is in the elif to have line.startswith('.. image::...'). You’ll notice that in the skeleton the badge is commented out. That’s because some projects don’t have RTD enabled, so in that case, there would be no RTD link.

Where would this routine live? Would it be in the setuptools plugin?

I’m happy to host it in jaraco.develop, which could also implement the setuptools plugin.

Could you point me to some examples of a setuptools plugin?

setuptools_scm implements a finalize_distribution_options hook in order to supply a version on the distribution. You may need to inspect the Setuptools code to determine what attribute(s) need to be modified to accept the project URLs (note, it might not be what setup() or setup.cfg expects).

Hope that helps.

Oh, and one other tip - in the plugin, you may wish not to hard-code “README.rst” but instead accept the project’s “Description” (aka long_description) as input.