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.