Decide on release structure for backward incompatible changes

[agjohnson]

We have several layers of backwards incompatible changes lined up, and need to discuss our plan further. So far, these backward incompatible changes are:

• Bootstrap port
• Dropping support for Sphinx <2.0 (dropping support for Python 2.7 then as well)
• Dropping support for old Python 3 versions -- 3.1<=>3.5?
• Dropping support for html4 writer -- this makes bootstrap support easier
• Don't check in static assets to repository
• Template changes, use basic theme as base
• Some minor changes, like dropping IE11 support/etc
• Others?

Additionally, team has mentioned that having an initial 1.0 release before any backwards incompatible changes are released. And we would also need some releases that emit deprecation notices.

A non-exhaustive list of the users that we care about:

• Users installing directly via Git
  • These users should almost all be using a proper release. Many are installing from master because we had bug fixes unreleased there.
• Users installing unpinned theme but using an older Sphinx
  • Sphinx 1.8 dependency is still very common
• Users installing unpinned dependencies and them overriding CSS
  • This is very common on our business hosting, and these users are largely not traditional developers that would be aware of deprecation. We need to be very careful with these users.
• Users using the theme as a submodule, for whatever reason
  • These are most likely advanced users that would be able to resolve a submoulde pointing to master, and repoint to a tag if neccessary.
  • These users could probably mostly use Sphinx theme operations and a properly installed release.

Questsions then to answer:

• Any other user cases we're concerned about?
• What can we do to limit the effect of deprecation and backwards incompatible changes for each user?
• What solution are we giving each user?
• Is there a way that we can use deprecation notices to nudge users in the right direction?
  • Warnings will likely go unnoticed in RTD build output
  • Do we need application logic to help?
  • We've been installing using unpinned dependencies for new projects, which is problematic for a backwards incompatible theme release
• We originally mentioned a separate repository or separate package for a Bootstrap theme. If we don't have great answers for how to avoid backwards incompatible changes
• What number of releases do we need?
  • Release with deprecation notices
• What do we want the last release with python2.7 support or Wyrm support to look like?
  • What changes/fixes are required to leave off the theme in a usable, but unmaintained state?

We can start with some discussion here, but it would really help to discuss this in a meeting with theme maintainers next.

[Daltz333]

I am -1 against releasing a 1.0. 1.0 is typically marked as stable, and that means we'll be immediately releasing backwards incompatibility after a 1.0 release.

I am +1 for deprecation, this is the right thing to do.

If a separate repository is intended, the ideal goal would be to eventually deprecate the entirety of sphinx_rtd_theme then and provide a migration strategy toward the new repo? Maintaining two separate themes seems troublesome.

[Blendify]

I think the goal seems to keep everything in one repository. A 1.0.0 version does not mean that the theme is stable but that a major breaking change was introduced, see https://semver.org/

[Daltz333]

So would a 1.0.0 release be made, and then quite soon a 2.0.0 release be made? I think that's quite unusual and will be confusing to users who want to know which version to pin.

[Blendify]

Yes that would be the idea, I think this helps knowing which version to pin. Each major version one stand for one major breaking change. Most users should not pin a version unless they make customizations. In that case they can look at the major breaking changes and determine easily if the breaking change applies to them.

[agjohnson]

Yeah, I personally also have similar reservations about an initial 1.0 version. We aren't yet talking about any major breaking changes in a 1.0 release, the team discussed bumping to 1.0 before any Bootstrap/etc breaking changes.

I do agree this seems like it could be confusing for users. For users that are pinned to a release that requires Wyrm, it will be confusing to upgrade to a 1.0 release that is effectively end of life as soon as we release it. This seems just as feasible on the existing 0.X development line.

A counter argument is that a 1.0 release could aid in isolating users that are using 0.X release normally, and users that specifically need a theme based on Wyrm. The majority of users should be able to upgrade 0.5.x to 2.x (Bootstrap release) without any problem, but basically no users would be able to gracefully upgrade from 1.0 (last Wyrm release) to 2.0.

[agjohnson]

If a separate repository is intended, the ideal goal would be to eventually deprecate the entirety of sphinx_rtd_theme then and provide a migration strategy toward the new repo? Maintaining two separate themes seems troublesome.

After thinking about this one a bit more, I'm ... not sure at all. This would be something to discuss a bit more. We have several options:

• Same repository, same PyPI namespace
  • This plan is the least confusing for the most number of users
  • Users with vanilla installation of the theme wouldn't notice a change
  • This plan is rather confusing for a small subset of users -- anyone pointing a submodule to the repo, extending/overlaying CSS on the existing CSS, or forking our theme
  • Users requiring Wyrm based theme need to point to theme final Wyrm release
  • Users installing via pip directly at our repository need to know that installing from master will break the style output of their site eventually. This would be automatic, as soon as bootstrap PRs are merged to master.
  • Users with submodule to the theme repo should be able to adjust. The change to a new commit/branch is manual, not automated
• New repository, new PyPI namespace
  • Doesn't break anything for anyone
  • Still the most destructive, as all sphinx_rtd_theme users need to know about new theme name
  • We'd still only support one theme, I don't see development continuing on Wyrm based theme
• New development continues in new repository, old repository is historical, same PyPI namespace instead
  • Users pointing directly to old repository get Wyrm based theme still
  • Users installing via pip directly from github get the old theme as well
  • Users installing via PyPI and extending CSS will have broken styles unless they are pinned

[agjohnson]

Also, @readthedocs/theme-committers -- feel free to chime in on any of this here. After we collect some feedback and ideas here, we can decide whether we should have a meeting to wrap up discussion here. Maintainers would be welcome to join, and we'd probably be focused on the technical decisions above.

[Blendify]

One other thing we need to drop is some sphinx template variables/blocks in the future we want to inherit as much as possible from sphinx's basic theme; for example extra_css_files needs to be removed.

As it stands right now, 1.0 looks like dropping some very old python3 versions, improving html5 to match html4 and setting up the stage to remove more things in the future.

I would like to drop sphinx 1.x before a version with bootstrap. So we could consider bootstrap to be version 3.

I would prefer if we could keep everything in this repository if possible keeping the pypi namespace.

[agjohnson]

I think 1.0 is only dropping sphinx <1.6, we shouldn't be dropping python3 versions just yet.

Agreed that we probably want to align dropping sphinx 2 and moving to bootstrap. There are a few changes that are sounding like they would make sense in a big 2.0 or 3.0 release.

Templates changes aren't on the deprecation list yet either, we should start throwing warnings there too.

[Blendify]

Templates changes aren't on the deprecation list yet either, we should start throwing warnings there too.

I do not think this is possible, if so let me know.

---

With the way things have been looking here is what I have:

• v1
  • HTML5 Fixes
  • Drop support for sphinx1.6< and very old python versions
  • Don't check in static assets to repository
• v2
  • Fontawesome5 with shim v4 shim
  • Require sphinx2
  • Drop python2
  • Dropping support for html4 writer
  • Webpack5
  • npm7
• v3
  • Bootstrap port (4/5)
  • Some minor changes, like dropping IE11 support/etc
  • Visual refresh
  • Higher sphinx/python dependency? Sphinx3?
  • v4
  • bootstrap 5 if not in v3
  • Fontawesome6
  • Higher sphinx/python dependency? Sphinx4?

As development has started for v1 (master), v2, and, v3 we should probably create official branches for each so PRs can be merged.

[agjohnson]

With the way things have been looking here is what I have:

I think this is close the my mapping as well, except:

• We need deprecation warnings. This might extend the number of release or at very least the time frame for releases.
• No visual refresh in v3, this should be a v4 thing. We can't change too much at once or the release will be unmanageable and users will be confused why so much changed/broke on their theme/etc.

As development has started for v1 (master), v2, and, v3 we should probably create official branches for each so PRs can be merged.

I'm generally against multiple branches of main development, it would be too much to coordinate for maintainers here. We should instead time our work based on the roadmap we define. It would probably be worth digesting some of the changes we already have before going too much deeper with future changes in fact.

I'd still like to get additional feedback from core team here. Next step is I'd like to have a maintainers meeting to discuss technical issues we have here.

[Daltz333]

What is there to coordinate when development on this repo is slow to non-existent?

From an outsider view, there is no active maintainer of this repo, maybe @Blendify

[agjohnson]

@Daltz333 Several of RTD core team regularly contribute here and there is already significant friction to developing on one branch, let alone 3 or 4. In the interest in continuing to allow multiple maintainers and core team to work on this repository concurrently, a single development branch is the least amount of effort. This is inline with the rest of the projects core team maintains.

[Blendify]

We need deprecation warnings. This might extend the number of releases or at very least the time frame for releases.

This has been mostly handled in several patches:

• Warnings for python 2: 3693d4c325f36032c1586ec6f3dede18a32dd0ef
• Warnings for sphinx 1.x 3693d4c325f36032c1586ec6f3dede18a32dd0ef
• Warnings for theme options https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/__init__.py#L27

The only thing that is missing is warnings for template changes.

No visual refresh in v3, this should be a v4 thing

Sounds good, basically, this would be https://github.com/readthedocs/sphinx_rtd_theme/pull/1055

I'm generally against multiple branches of main development, it would be too much to coordinate for maintainers here. We should instead time our work based on the roadmap we define. It would probably be worth digesting some of the changes we already have before going too much deeper with future changes in fact.

This would be fine as long as we can keep the momentum going so things don't stall. Also, there is currently not much other work being done by other contributors besides myself so I don't think it would be that hard to maintain. Given that we can assign milestones to PRs it is relatively easy to stay organized so I am okay with either git flow.

[Daltz333]

This would be fine as long as we can keep the momentum going so things don't stall.

This was precisely my concern. I'd hate to see things stall again for the sake of "waiting it out".

[agjohnson]

This would be fine as long as we can keep the momentum going so things don't stall.

This should be fine, I don't want to see work here stall out either. I would still advise against getting ahead of our roadmap though.

This was precisely my concern. I'd hate to see things stall again for the sake of "waiting it out".

For some context that is missing here: this sphinx theme is tightly integrated into RTD and we are very dependent on the theme working in specific ways. Until the theme and theme features are more decoupled from RTD, we need to match the roadmap of RTD and the team's priorities. For instance, none of the changes lined up here are particularly technically difficult in isolation. The complexity of these changes all comes from RTD, RTD users and customers using this theme, and all the edge cases using this theme. Removing Wyrm is going to be a particular headache, not because it's a chunk of technical work, but because there is a high probability to break documentation without warning for our users and customers.

[Daltz333]

For some context that is missing here: this sphinx theme is tightly integrated into RTD and we are very dependent on the theme working in specific ways. Until the theme and theme features are more decoupled from RTD, we need to match the roadmap of RTD and the team's priorities. For instance, none of the changes lined up here are particularly technically difficult in isolation. The complexity of these changes all comes from RTD, RTD users and customers using this theme, and all the edge cases using this theme. Removing Wyrm is going to be a particular headache, not because it's a chunk of technical work, but because there is a high probability to break documentation without warning for our users and customers.

This sounds like the typical case of technical debt 😦

[Blendify]

For some context that is missing here: this sphinx theme is tightly integrated into RTD and we are very dependent on the theme working in specific ways.

Can you expand on this if I am missing anything:

• rtd expects compatibility with sphinx 1.x
• the versions badge menu
• the version number as displayed in in the blue search box area

[Daltz333]

I think there are several ways of easing the pain...

• Communication! Clearly communicate all backwards incompatible changes. A large amount of RTD users including myself modify the CSS (including patching the broken styling of the docs). Clear communication on X being fixed or changed is necessary
• Heavily recommend version pinning. This should be done regardless, otherwise development is blocked by users, which becomes technical debt. This is a current issue RTD has...
• Transparency! Combined with communication, RTD core team should outline the goals and expectation of this project and project goals in a timely manner. If this project is in too much technical debt for changes to not get merged in a timely manner (within 2 years??), we'd like to know (we will likely fork this theme and push forward with development of our own).

[Daltz333]

One suggestion for a common release process is development and stable branch. Both of these are pushed to PyPi, but development is "bleeding edge".

Alternatively, you could make two repositories. Development and LTS. Where LTS is the current, and development is the contribution repo. Things can slowly get added to LTS or cherry picked in. Either way, I'd love some way to get active development features without combining 7 different PRs.

[agjohnson]

This is all helpful feedback @Daltz333 :+1:

One suggestion for a common release process is development and stable branch. Both of these are pushed to PyPi, but development is "bleeding edge".

Absolutely, our (intended) approach is similar in effect. Maintainers here decided a while ago that we should be moving to cut frequent RC or dev releases, and stop our current pattern of waiting for PRs to align to cut a release. I'm a big fan of this change. Our process is closer to this after the big pile of changes to support html5 writer, but our process has still not quite caught up yet. I'd really like to cut a 1.0 RC this week so that users can start installing and testing the backlog of 0.5.1 changes.

The RC or dev release part of this conversation is very important, because rc/dev releases greatly reduces our risk to cutting a broken release.

I think there are several ways of easing the pain...

This is actually very timely, we just had most of this discussion today.

* Communication!

Yes, absolutely this. This needs to come in a few different flavors:

• Build warnings about deprecations. This is easy to implement, but easy for users to miss too.
• RTD notifications and communication. We know what projects use our theme to build and what versions they use. We can escalate to contacting projects when we want to fully deprecate something
• Guide users to upgrade with content. Hopefully new features and documentation around new features will lead to users naturally upgrading

* Heavily recommend version pinning.

This is a big one. RTD historically did a lot to set up the build environment for users. This was novel, but also lead a lot of projects now to relying on various magic mechanisms in RTD. We can't remove these now without breaking projects randomly. In the future, we are going to specify little to no dependencies for new projects. Old projects however are difficult to change.

* Transparency!

This is obvious but also quite difficult in application. The issue that we have is there are a lot of users this theme. There are a lot of pageviews of this theme too -- considering forks and non-RTD usage, easily 20M+ monthly pageviews. Most are through RTD, but not all are. Core team's primary concern is with broad usage of this theme on RTD community and commercial hosting.

A lot of the contributions we get might scratch an itch for a particular user or subset of users, but these contributions usually get caught up, and stall out, in the complexity of supporting all of the various use cases this theme has to support. Use cases include browser support, RTD specific features, downstream usage like forked themes and customized themes, how the theme is installed, or how projects on RTD historically used the theme.

So, the best place that contributions can help push forward on contributions to help test against these cases. Core team should enumerate or describe these different scenarios in more detail, this seems like a good place to start.

Thinking about this however, it might make sense to have a larger automated test suite as well. This way, users can easily be familiar with all of the fun and exciting ways this theme can break for users, and can actually see how changes break these use cases. Otherwise, this onus falls primarily on the core team, and this is another big reason development slows or contributions stall out.

Core team can also be explicit about what usage we support. I think the other natural part of that is reducing the number of cases that we support so that this isn't so damn complicated. Conversations like not supporting installation via Git URL or not supporting our flyout menu outside RTD are all related to reducing the amount of scope creep the theme needs to worry about.