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

hugovk commented 3 years ago

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:

Open release notification e.g. https://github.com/pypa/setuptools/releases/tag/v59.1.1
Click to go to repo homepage: https://github.com/pypa/setuptools
Look for a link to the docs.
It's not the one at the top right, that's a link to https://pypi.org/project/setuptools/
Scroll down to the README
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.
Check the badges.
One of those is "docs: passing", click that
Scroll down to find History in the left menu, click it
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

[X] I agree to follow the PSF Code of Conduct

hugovk commented 3 years ago

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").

This uses pep517.meta but "the entire pep517.meta module is going to be removed to some point in the future" (https://github.com/pypa/pep517/issues/100#issuecomment-721053231) so maybe it's not wise to build more on top of it.

jaraco commented 3 years ago

I'm in favor of supporting this. I'd prefer to support it in jaraco/skeleton as a procedure that applies to all projects. My main reluctance there is that it's yet another piece of metadata that has to be customized for each project, but only for those that support RTD (not all projects incorporate RTD because of the overhead that adds). Currently, there's one thing that needs to be customized when enabling RTD - the badge in the readme (that you found eventually). I'd like to see something like:

A routine that detects RTD is enabled by parsing the README and extracts the URL.
A plugin for setuptools that adds a Documentation Project-URL if that badge is enabled.
A routine in jaraco.develop that adds a link to the changelog if a documentation URL is available in the metadata.

If this functionality were added, it would rely on the existing signals to generate the metadata in useful places.

Step 2 could be skipped, but there have been other requests to include the documentation URL in PyPI.

Would you be willing to work on this?

hugovk commented 3 years ago

I'd need some pointers.

Step 1: Something like this:

def rtd_badge_doc_link():
    found_badge = False
    with open("README.rst") as f:
        for line in f:
            if found_badge:
                return line.split()[-1]
            elif ".. image:: https://img.shields.io/readthedocs/" in line:
                found_badge = True
    return None

returns https://setuptools.pypa.io for setuptools.

Where would this routine live? Would it be in the setuptools plugin? Which repo would the plugin be part of? I don't have experience with setuptools plugins, could you point me to some examples?

jaraco commented 3 years ago

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.

septatrix commented 3 years ago

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.

hugovk commented 1 year ago

Hi! Sorry, this dropped off my todo list and isn't important for me now, so I'll unvolunteer myself :) I don't mind if this issue is closed or if someone else takes care of it.

jaraco commented 1 year ago

The crux of this issue is that the README is static. I'd really much rather not have to supply essential metadata in the README, but instead have the readme reflect important metadata. I noticed recently that https://github.com/hynek/hatch-fancy-pypi-readme offers some dynamism in the README, but it's still largely pulling from other static fragments and substitutions and it's for hatch only.

I welcome others to take this up, but I have other priorities (distutils migration, pkg_resources deprecation) before I get to the features that would make this problem easier (zero config). I welcome others to contribute.

pypa / setuptools