diff options
Diffstat (limited to 'docs/development.rst')
| -rw-r--r-- | docs/development.rst | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..c4ee9a4 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,209 @@ +Development +=========== + +The theme developers follow the guidelines below for development and release +planning. Documentation authors can decide which theme release works best for +their project based on required browser/operating system combinations or +dependency support. + +.. _supported-browsers: + +Supported browsers +------------------ + +Official browser support is determined by the most popular browser/operating +system combinations in our pageview analytics. Officially supported combinations +are commonly tested during development, and are always tested before final +release of a new version of the theme. + +Older releases of supported combinations, and some less common combinations, are +considered partially supported. This means that we do not consistently test +these combinations, however we do expect user experience to be comparable with +supported combinations. + +.. csv-table:: Supported browser combinations + :widths: 6, 12, 4 + :header-rows: 1 + :file: supported-browsers.csv + +.. versionadded:: 1.0 + Supported browser and operating system combinations added + +There are several browser/operating system combinations that are not supported +by the theme developers at all. Unsupported combinations do not receive testing +or development, and we likely won't accept major contributions for these +combinations. + +Unsupported browser/operating system combinations include: + +Internet Explorer (any OS, versions <=10) + **Unsupported.** IE11 is the last partially supported version. We do no + testing on prior versions. + +Internet Explorer (any OS, version 11) + We currently only partially support IE11, and only test for major bugs. + Support will be removed in the :ref:`roadmap-release-3.0.0` release. + +Opera (any OS, any version) + **Community support only.** We do not receive enough traffic with this + browser to officially support it in testing and development. + +.. _supported-dependencies: + +Supported dependencies +---------------------- + +The theme officially supports the following dependencies in your Sphinx project: + +.. list-table:: Supported dependencies + :header-rows: 1 + :widths: 10, 10 + + * - Dependency + - Versions + * - Python + - 3.6 or greater + * - Sphinx + - 5 or greater + * - docutils + - >= 0.14, < 0.19 + +.. deprecated:: 2.0 + Sphinx < 5 support removed + +.. deprecated:: 2.0 + Python < 3.6 support removed + +.. deprecated:: 2.0 + docutils < 0.14 support removed + +.. versionadded:: 1.0 + Sphinx 4.0 support added + +.. deprecated:: 1.0 + Sphinx 1.6 support removed + +.. versionadded:: 1.0 + docutils 0.17 support added + +Roadmap +------- + +We currently have several releases planned on our development roadmap. Backward +incompatible changes, deprecations, and major features are noted for each of +these releases. + +Releases follow `semantic versioning`_, and so it is generally recommended that +authors pin dependency on ``sphinx_rtd_theme`` to a version below the next major +version: + +.. code:: console + + $ pip install "sphinx_rtd_theme<2.0.0" + +.. _semantic versioning: http://semver.org/ + +.. _roadmap-release-1.0.0: + +1.0.0 +~~~~~ + +:Planned release date: August 2021 + +This release will be a slightly backwards incompatible release to follow the +:ref:`release-0.5.2` release. It will drop support for Sphinx 1.6, which is a rather old +release at this point. + +This version will add official support for the Sphinx 4.x release series and +it resolves bugs with the latest release of Docutils, version 0.17. + +Starting with this release, several deprecation warnings will be emitted at +build time: + +Direct installation is deprecated + Support for direct installation through GitHub is no longer a suggested + installation method. In an effort to ease maintenance, compiled assets will + eventually be removed from the theme repository. These files will only be + included in the built packages/releases available on PyPI. + + We plan to start putting development releases up on PyPI more frequently, so + that installation from the theme source repository is no longer necessary. + + Built assets are tentatively planned to be removed in version :ref:`roadmap-release-3.0.0`:. + +HTML4 support is deprecated + Support for the Sphinx HTML4 writer will be removed in the :ref:`roadmap-release-2.0.0` + release. + +.. _roadmap-release-1.1.0: + +1.1.0 +~~~~~ + +:Planned release date: 2021 Q3 + +We aim to follow up release :ref:`release-1.0.0` with at least one bug fix release in +the 1.x release series. The 1.1 release will not be adding any major features +and will instead mark the last release targeting projects with old dependencies +like Sphinx 1.8, HTML4, or required support for IE11. + +.. _roadmap-release-2.0.0: + +2.0.0 +~~~~~ + +:Planned release date: 2023 Q3 + +This release will drop support for old Python and Sphinx versions. + +Note the following backwards incompatible changes are planned for this +release: + +Python < 3.6, Sphinx < 5 and Docutils < 0.14 will not be tested + Official support will drop for these version, though they may still continue + to work. Theme developers will not be testing these versions any longer. + +HTML4 support will be removed + Starting with this release, we will only support the HTML5 writer output, + and builds attempting to use the HTML4 writer will fail. If you are still + using the HTML4 writer, or have the ``html4_writer = True`` option in your + Sphinx configuration file, you will need to either remove this option or pin + your dependency to ``sphinx_rtd_theme<=3`` until you can. + + This option was suggested in the past to work around issues with HTML5 + support and should no longer be required to use a modern combination of this + theme and Sphinx. + +.. _roadmap-release-3.0.0: + +3.0.0 +~~~~~ + +:Planned release date: 2024 Q1 + +This release is not yet fully planned. +However, we already know that we will be dropping support for older version of different dependencies and browsers. + +Sphinx 5, Python < 3.8 and docutils < 0.18 support will be removed + Sphinx 5 is the latest version that supports Python 3.6 and 3.7, + and docutils < 0.18. + +Internet Explorer 11 support will be dropped + `IE11 reached end of life on 14 June 20222 <https://endoflife.date/internet-explorer>`_, + so we are not supporting it on newer versions, + starting on 3.0.0. + +.. _roadmap-release-4.0.0: + +4.0.0 +~~~~~ + +:Planned release date: 2024 Q2 + +This release is not yet planned. +There are plans to potentially replace Wyrm with Bootstrap in a release after 3.0. + +Also tentatively planned for this release is finally removing built CSS and +JavaScript assets from our repository. This will remove the ability to install +the package directly from GitHub, and instead users will be advised to install +development releases from PyPI. |