Release 1.1 with upper bounds on dependencies

[agjohnson]

The goal is to get 1.1 out that doesn't break when Sphinx 6 or docutils are released. The existing 1.1 milestone has a lot of extra bugs/bug fixes, which would be best off in a 1.2 release.

[agjohnson]

I've repaired a number of issues building at CI. #1316 has working CI builds.

[benjaoming]

I don't quite understand this issue, can you elaborate @agjohnson ? 🙏

[agjohnson]

Pinged in chat. The note here is that we might delay a release if we continue going through the 1.1 milestone bugfixes. We'll want to do some testing on latest Sphinx and docutils, and ensure those pins do not introduce any display changes, build errors, or otherwise break the dependency chain for users.

[benjaoming]

By pinning, do you mean introducing upper bounds < on more of the transient dependencies, i.e. not ==?

[agjohnson]

The current specifier for Sphinx is https://github.com/readthedocs/sphinx_rtd_theme/blob/master/setup.cfg#L35, so really wide open. We'll want to tune that down to at least avoid bringing in Sphinx 6 and docutils versions we can't support.

[benjaoming]

Ah okay, then I get you, I understanding "pinning" as ==

[agjohnson]

Ah I see, yeah we use that term fairly loosely I suppose

[benjaoming]

Not sure if correct language

[benjaoming]

@agjohnson these are our current direct dependencies:

sphinx_rtd_theme/setup.cfg

Lines 34 to 37 in e741681

	install_requires =
	sphinx >=1.6,<6
	docutils <0.18
	Jinja2 <3.1

small note: we'll bump docutils to 0.18 and maybe also to 0.19

Should we investigate transitive dependencies and potential of putting upper bounds of some of those or can this issue be considered solved?

[agjohnson]

We'll use this issue to track an actual release going out. We can reassign this issue while you're away, but the actual work behind the release is indeed looking close.

[agjohnson]

these are our current direct dependencies:

@benjaoming To clarify, those are the current dependencies specified in master. Release 1.0.0 has no upper bounds on Sphinx:

https://github.com/readthedocs/sphinx_rtd_theme/blob/1.0.0/setup.py#L120-L123

The aim of 1.1 release was to get out a fairly minor release that just pins dependencies so that we have more protection from Sphinx and docutils releases.

The next release, 1.2 or 2.0, can focus more on fixing issues with docutils 0.18 and 0.19, etc. We have more work to do to resolve display bugs with docutils 0.18 footnotes/citations.

For that, I think the following issues are on the wrong milestone and should be 1.2:

• Support docutils 0.18.x #1302
• Support for docutils 0.19.x #1323
• Adds support for docutils 0.19 #1336
• Support docutils 0.18 #1304

[benjaoming]

There are a lot of people asking for docutils 0.18 and I would feel okay that the footnotes have a visual regression for docutils 0.18 that can be fixed during QA of 1.1b1 (I'll add the first set of styling ASAP).

#1322 was posted separately for this reason.

[benjaoming]

Bumping #1302 etc to the 1.2 milestone regardless, the 1.1 release can ship and be QA'd without it.

[agjohnson]

I do agree on adding a docutils 0.18 and 0.19 fixes, but this does seem like a good point to split out two separate, smaller releases.

Historically, we've been bad about creeping scope on theme releases and this has delayed fixes from going out for users. One of the conclusions we came to was that we should cut smaller releases more frequently. This does require being mindful of the true amount of work attached to each milestone, but users benefit from faster fixes, and we benefit from lower potential for breakage on each release.

[benjaoming]

I agree, I was treating the 1.2 milestone as a milestone that wasn't actually in the roadmap. But now it is so it makes it easier to avoid the 1.1 scope creep. Also, it might be useful for some projects to choose between 1.1 (docutils<0.18) and 1.2 (docutils<0.19).

[ericholscher]

A pre-release of 1.1.0 is out! You can help test it by upgrading to the latest pre-release, 1.1.0b3. Install it with pip install sphinx-rtd-theme==1.1.0b3 and make sure your docs look good!

Full changelog is here: https://sphinx-rtd-theme.readthedocs.io/en/latest/changelog.html

[benjaoming]

Will close this once we see that readthedocs/readthedocs.org#9701 works

[benjaoming]

The new release is announced and works for the first builds tested.