search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.43k stars 2.1k forks source link

5.3.0 release plan #10896

Closed AA-Turner closed 1 year ago

AA-Turner commented 1 year ago

I intend to release Sphinx 5.3.0 next weekend, 16/10/22.

Issues marked against 5.3.0: https://github.com/sphinx-doc/sphinx/milestone/133

Please alert me to any PRs/issues that should be included in 5.3.0.

As previously mentioned, the next version after 5.3.0 will be 6.0, which will be released at the end of October.

A

ericholscher commented 1 year ago

I just wanted to clarify the timing on Sphinx 6 release. We were working under the assumption that we had until next year before the removal of jQuery, as noted here: https://github.com/sphinx-doc/sphinx/pull/10470

I dropped Docutils 0.16 and 0.17 in different commits. I would advocate for a higher minimum to reduce the matrix of potential Sphinx versions x Docutils versions, and by the time Sphinx 6 is released (April 2023) we may have Docutils 0.19 and 0.20.

Can you confirm that jQuery is going to be removed at the end of October? I'm worried that this will cause a pretty big break in the ecosystem, and I'm not sure how ready the various themes and extensions are for this change.

AA-Turner commented 1 year ago

The timeline can be delayed if need be. My desire is to simplify Sphinx's development--two long-lived branches don't really make sense, as we only support the latest version and only make releases from 5.x (I don't believe there is widespread testing of the master branch). A faster release cadence of smaller versions should make the upgrade process less painful. We would still intend to keep deprecations for a good length of time before removal, though.

The warning has been in the docs since January, though it should likely be more prominent in the 6.0 entry -- I'll address this. One of the reasons I want to focus only on the 6.0 release and close 5.x development is to see what extent the changes in 6.0 (Python 3.8+, Docutils 0.18+, EMCAScript 2018+) have, so I can see what mitigations are needed in extensions/themes.

A

jfbu commented 1 year ago

two long-lived branches don't really make sense, as we only support the latest version and only make releases from 5.x (I don't believe there is widespread testing of the master branch). A faster release cadence of smaller versions should make the upgrade process less painful.

The release process of a master branch was associated with a beta-testing period of circa a month or so (perhaps longer) which theoretically gave opportunity for the community to become aware of and test documented breaking changes and possibly uncover problems. If keeping only one long-lived branch, does this mean that there will be specific time periods during the release cycle where PRs introducing breaking changes get merged? I am asking out of curiosity, as I have no strong opinion.

jfbu commented 1 year ago

Issue #10903 must be resolved in time for 5.3.0 release...

AA-Turner commented 1 year ago

The release process of a master branch was associated with a beta-testing period of circa a month or so (perhaps longer) which theoretically gave opportunity for the community to become aware of and test documented breaking changes and possibly uncover problems. If keeping only one long-lived branch, does this mean that there will be specific time periods during the release cycle where PRs introducing breaking changes get merged? I am asking out of curiosity, as I have no strong opinion.

Breaking change should be merged as early as possible, but is OK any time before the first public beta release of the X.0 version of Sphinx.

A

AA-Turner commented 1 year ago

Sphinx 5.3.0 has been released. Thanks to all for your contributions.

A