8.0.0 release plan

[AA-Turner]

I intend to open Sphinx 8 for development either later today or tomorrow, with a release planned for the end of next week (though I'm open to arguments to delay).

This release would be only removing expired deprecations, dropping support for Python 3.9, and consequent refactorings -- I wouldn't expect any new features to be included.

A

cc: @sphinx-doc/developers @sphinx-doc/triagers

[picnixz]

I'd like to delay the release, unless you are willing to take over the deprecation in intersphinx (#12083) in case I'm not available next week (I'm finalizing the last bits of my final manuscript).

I fixed all conflicts in the PRs for that so it should be fine. Ideally, I would like to be able to review everything that will be release in 8.x before publishing the first draft, but I'll only be able to do so starting mid August. I think there are multiple people that are on holidays as well so it'd be better to wait a bit (for instance, if there are new bugs appearing due to 747).

[AA-Turner]

I was trying to avoid making a release in August, as that is typical holiday season (at least in Europe). I am happy to cover #12083 and #12087 if we don't delay.

Also of note is that Sphinx 8 will break breathe (breathe-doc/breathe#943, breathe-doc/breathe#984, breathe-doc/breathe#964, breathe-doc/breathe#977; all the same paths issue). @michaeljones / @jakobandersen are you able to merge any of these / make a new breathe release?

A

[chrisjsewell]

Thanks for the heads-up @AA-Turner!

Yeh I think, as long as all the known regressions from 7.4 are fixed, and it's only dropping deprecations,
we should get it out ASAP, to avoid further building up a backlog of issues/PRs for new things.

I've worked on intersphinx, I can also double-check those PRs if necessary

[picnixz]

Ah I see. Actually, #12083 is about removing the very old intersphinx format which was planned for removal in 8.x. But if you think we don't need to remove it at this point, no need to press it (I mean, we can always delay the removal by 1 version to avoid surprises).

[chrisjsewell]

I would also like for #12597 to be considered

[jayaddison]

Ah I see. Actually, #12083 is about removing the very old intersphinx format which was planned for removal in 8.x. But if you think we don't need to remove it at this point, no need to press it (I mean, we can always delay the removal by 1 version to avoid surprises).

This is about the format of the intersphinx_mapping configuration entry only, right? As in: we're not deprecating the v1/v2 inventory formats, but suggesting removal of an old-style config entry for remote mappings, which has emitted warnings since v6.2 onwards.

Refreshing my memory of #12087 in a few moments..

[picnixz]

This is about the format of the intersphinx_mapping configuration entry only, right

Yes. It was the very first way to specify intersphinx mappings without a named inventory. But the maintenance cost was really not easy and there are a lot of paths to be taken just to take care of un-named inventories. Also, it conflicted with the resolution algorithm (when you don't know which inventory to target...).

#12087 is about fixing an issue when you change the URL of your project (you end up having TypeError if you don't wipe out your cache). So it's a bug fix only (so it doesn't really need to be incorporated into 8.x, it's just that it uses the assumptions that I only have the new format, otherwise it's too complicated...).

[jayaddison]

Ok; I remember most of those details now. I'll have another read through them both to try to provide some additional support for the release (if we do that soon).

[picnixz]

I don't really care about the second PR but the one removing the old intersphinx format is definitely something that I would like to incorporate (at least, it would ease my life for future work).

[jayaddison]

I don't really care about the second PR but the one removing the old intersphinx format is definitely something that I would like to incorporate (at least, it would ease my life for future work).

Personally I am somewhat interested in both of them (I think the reproducibility fix from #12087 would be a nice clean transition alongside 8.x), so despite being tempted only to offer to support one.. I think I would prefer to try to understand and include both :)

[michaeljones]

Breathe is not really maintained at the moment. We're (rather passively) looking for funding for future development. Please don't delay any release for us. Sorry that the lack of maintenance on Breathe will result in some disruption though.

[n-peugnet]

Are you not interested in including #12238 (or a rework of this proof of concept)? As it has a quite important breaking change. Otherwise it would be delayed to the next major.

Or maybe please provide some feedback as of how to improve it.

[jfbu]

#12656 is currently a blocker... (edit: see #12668) (fix has been merged)

[AA-Turner]

To my knowledge, there is nothing more outstanding blocking Sphinx 8.0.0. Please let me know if I have missed anything.

I might make a pre-release 8.0.0rc1 if that would be useful, please do say, but otherwise the plan remains to release 8.0.0 on or around the 26th-29th.

cc downstream for awareness and/or pre-release testing:

• @agoose77 / @choldgraf (https://github.com/executablebooks/sphinx-book-theme)
• @drammock (https://github.com/pydata/pydata-sphinx-theme)
• @hugovk (https://github.com/python/python-docs-theme)
• @humitos (https://github.com/readthedocs/sphinx_rtd_theme)
• @jarrodmillman (https://github.com/numpy/numpydoc)
• @jbms / @2bndy5 (https://github.com/jbms/sphinx-immaterial/)
• @jdknight (https://github.com/sphinx-contrib/confluencebuilder)
• @joeced (https://github.com/sphinx-contrib/matlabdomain)
• @lucyleeow (https://github.com/sphinx-gallery/sphinx-gallery)
• @mgeier (https://github.com/mgeier/insipid-sphinx-theme/ & https://github.com/spatialaudio/nbsphinx/)
• @pradyunsg (https://github.com/pradyunsg/furo)

A

[chrisjsewell]

I might make a pre-release 8.0.0rc1 if that would be useful

I think that would be helpful thanks; there's been a few more commits than I expected in the last few days 😅

[2bndy5]

If you established a release plan that involves pre-release candidates, then we (downstream devs) could automate the pings for new releases (via user account subscriptions/watched notifications).

That way @AA-Turner wouldn't have to manually ping a growing list of downstream devs.

[AA-Turner]

We typically only do pre-releases for major (X.0) releases. GitHub does have a feature where one can subscribe to labels (type:task in this instance), but it seems not enabled everywhere (CPython has it, but this repo doesn't).

A

[2bndy5]

Given the "breaking" changes encountered in various minor bumps, would it not be prudent to extend the pre-release policy to minor versions as well?

[2bndy5]

Unfortunately, dependabot does not pay attention to pre-releases, so we're out of luck there as well.

[2bndy5]

I guess you could also use an issue template that includes the growing list of manual pings. Something like .github/ISSUE_TEMPLATES/release-plan.md might look like

name: Release Plan (for sphinx developers only)
about: Gather feedback before a release
title: ' release plan'
labels: 'type:task'
assignees: ''

---

This is our release plan for vX.Y.Z

blah blah blah ...

<details><summary>Pinging downstream developers for feedback</summary>

- @agoose77 / @choldgraf (https://github.com/executablebooks/sphinx-book-theme)
- @drammock (https://github.com/pydata/pydata-sphinx-theme)
- @hugovk (https://github.com/python/python-docs-theme)
- @humitos (https://github.com/readthedocs/sphinx_rtd_theme)
- @jarrodmillman (https://github.com/numpy/numpydoc)
- @jbms / @2bndy5 (https://github.com/jbms/sphinx-immaterial/)
- @jdknight (https://github.com/sphinx-contrib/confluencebuilder)
- @joeced (https://github.com/sphinx-contrib/matlabdomain)
- @lucyleeow (https://github.com/sphinx-gallery/sphinx-gallery)
- @mgeier (https://github.com/mgeier/insipid-sphinx-theme/ & https://github.com/spatialaudio/nbsphinx/)
- @pradyunsg (https://github.com/pradyunsg/furo)

</details>

[AA-Turner]

Sphinx 8.0.0rc1 has been released.

A

[hugovk]

• @hugovk (python/python-docs-theme)

I built the CPython docs (with python-docs-theme) with Sphinx 7.4.7 and 8.0.0rc1, a did a spot check diff of some of the files, and they were identical (other than the timestamp and Sphinx version in the footer).

[eli-schwartz]

Gentoo could probably help out at least a bit as a general rule -- we did package this prerelease and it got picked up by our tinderbox that attempts to rebuild all packages in Gentoo (with unstable dependencies), including a fair number of packages that have a documentation build.

That's how we noticed #12686. :)

cc @mgorny

[AA-Turner]

Sphinx 8.0.0 has been released.

A