Changelog/release notes sections do not have stable anchors

[dgelessus]

Description
The section headers in the changelog/release notes do not have proper stable anchor IDs. Instead, they have generic numbered IDs like id123. This makes it impossible to link to a specific section of the changelog in a way that will continue working in the future: for example the section for version 20.0 has anchor ID id6 in the current stable version of the docs, and anchor ID id35 in the current latest version. These IDs seem to be assigned sequentially from the start of the file, so they are guaranteed to change when a new version section is added.

Expected behavior
Each version section (and preferrably also each subsection) should have a unique anchor ID that does not change when a new pip release is added to the changelog.

(I'm violating the issue template a bit here - this is a documentation issue, so pip version, OS, etc. don't really apply.)

[pradyunsg]

The only project that I know does anything to solve this issue is virtualenv: https://virtualenv.pypa.io/en/latest/changelog.html#features-20-0-21

I am not particularly a fan of solving this issue like that tho. :)

[maxwell-k]

I think we need to clarify what the requirement is in this issue, there is some more discussion over in #8620

[maxwell-k]

Sorry I was a little slow to re-read the initial report:

Each version section (and preferrably also each subsection) should have a unique anchor ID that does not change when a new pip release is added to the changelog.

Each version section is very achievable and there are lots of examples to follow. Each sub section is more difficult. I suggest splitting this proposed requirement into two and quickly implementing "each version section".

[dgelessus]

Thank you for looking into this!

My main request is being able to link to a specific version in the release notes in a way that doesn't break when new versions are added. That way when I'm in an issue/review discussion talking about a change in pip's behavior, I can provide a link to the relevant section of the release notes and say "here's the pip release where the change happened".

The ability to also link to a specific subsection would be "nice to have", but I would also be happy if only the version sections have unique anchors and the subsections don't. In most cases the list of changes for one version is short enough that you can find a specific change even if you don't know what subsection it's under.

[McSinyx]

To keep the discussion easy to follow, I suggest commenting about the requirements and general approaches here and only talk about implementation-specific details in the PRs.

Personally I'd favor seeing this incrementally improved, i.e. merging GH-8620 almost as-is and perform the subsection work in a follow-up.

@maxwell-k, IIUC, by

I am not particularly a fan of solving this issue like that tho. :)

@pradyunsg probably mean he doesn't like the way e.g.

Features - 20.0.21

looks. As suggested in the mentioned PR, we can instead label each subsection using something like

.. _features-{(versiondata.version.replace('.', '-')}}:

Regardless of which path we take, we'll still need towncrier>=19.9.0rc1 for this task, preferably by nudging its maintainers to prepare for a stable release if possible.

[wimglenn]

Just saw this, it seems to affect more than just the changelog section - same in the user guide
https://pip.pypa.io/en/latest/user_guide/#using-pip-from-your-program
used to anchor but now it's https://pip.pypa.io/en/latest/user_guide/#id9 which won't be stable in the likely event that a section gets added above.

[uranusjr]

@wimglenn The problem to this issue is that the changelog page is machine-generated. The section you are referring is written by a human, and likely broken by a botched merge conflict resolution. Feel free to submit a pull request to amend it. Specifically, this line should be moved to right above the relevent secion.

[abitrolly]

So the issue is that Sphinx can not slugify headers with numbers like 19.2 (2019-07-22) to turn them into html link anchors.

Can anyone compile a minimal example of this misbehaviour to report upstream?

[pradyunsg]

@abitrolly that's because it's a heading without "letters". Any page with only digit+symbols heading would have this issue. Here's an example page:

Hi
==

1.2.0
-----

1.1.0
-----

1.0.0
-----