4.0.0 release plan

[tk0miya]

According to our annual release cycle, this April is time for the major release. I think this schedule is good for the release. What do you think?

• Apr 10th:
  • Beta release (feature freeze)
  • call for translation
  • Create a new branch: 4.x and 4.0.x
  • 4.x will be used for develop 4.1
  • 4.0.x will be used for develop 4.0.0 (feature freezed)
• Apr 24th: final release

Any comments?

Note: issues marked as 4.0.0: https://github.com/sphinx-doc/sphinx/milestone/74

[shimizukawa]

㊗️

[ericholscher]

Is it possible to have the release done on a weekday, so that if major issues are hit with RTD or other downstream users, we can be around to fix them? I realize it's a trade off between folks who are doing this work in their jobs vs. free time -- but I do think it might be best to ship them on a weekday, if possible.

We just hit this with the docutils release, and woke up Monday morning to a number of bug reports, so it would be great to coordinate this stuff a bit more. Certainly some of this can be caught in testing, but there's such a widespread user base, there will always be edge cases we can't catch in beta.

[grubert]

On Tue, 6 Apr 2021 at 18:42, Eric Holscher @.***> wrote:

Is it possible to have the release done on a weekday, so that if major issues are hit with RTD or other downstream users, we can be around to fix them?

I realize it's a trade off between folks who are doing this work in their jobs vs. free time -- but I do think it might be best to ship them on a weekday, if possible.

that is my tradeoff sorry for hitting anyone with docutils 0.17

We just hit this with the docutils release, and woke up Monday morning to a

number of bug reports, so it would be great to coordinate this stuff a bit more. Certainly some of this can be caught in testing, but there's such a widespread user base, there will always be edge cases we can't catch in beta.

do you have a test loading prerelease stuff once a ... week so that if a beta is out for two weeks is this safer or is it simply release on ... tuesday (not the first day into week but not already weakened by days)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/9056#issuecomment-814267777, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHEYA4SN4TYSDI6YYIYTYLTHM2YRANCNFSM42LDEIZQ .

[tk0miya]

I don't know I will have time on weekdays. But it's not impossible.

[jakobandersen]

I'm hoping to get #9023 and #8313 done for v4 due to (semi-)breaking changes. However, the latter requires #8929 to avoid breaking existing intersphinx functionality for the C domain. @tk0miya, are you fine with the design of it?

[tk0miya]

Now, I don't have time to review #8929 in detail. But I think env and domains should not be coupled with intersphinx. So I'd like to implement it on 4.1.

[jakobandersen]

It is indeed an icky coupling with the domains, though it is difficult to get around. Ok for me to wait for 4.1.

[tk0miya]

Thank you for understanding :-)

[ericholscher]

@tk0miya @grubert Appreciate the comments here. I fully appreciate the constraints involved around working on this stuff, and want to specifically thank you for your work on these projects. Having it released on a weekday is not a huge requirement, and becomes less of an issue if we test beta releases more prior to them going out to at least find any widespread issues.

I'd love to offer some help at the RTD level to see if we can possibly increase testing of betas and integration of our the entire stack (docutils -> Sphinx -> Sphinx themes -> RTD) prior to major releases. Does docutils have a similar place for us to track beta timelines? It would be great to be able to coordinate releases of these tools a bit better, if that isn't a burden on the maintainers, but I think at least working on the RTD side to do more testing prior to release is something we can commit to without adding workload to you.

[tk0miya]

I believe docutils-develop list is a good place to know the schedule of the release. I first heard the plan of the 0.17 on the list. https://sourceforge.net/p/docutils/mailman/message/37217330/

(But I couldn't confirm it well because of lack of time...)

[return42]

I believe docutils-develop list is a good place to know the schedule of the release.

There is also a section "Future changes" in the https://docutils.sourceforge.io/RELEASE-NOTES.htm which could give one some hints about changes in the next release .. but in lack of time I do not check it regularly.

I think it is the best to pin the docutils version, to something what is widely tested (or even better a range of versions >=0.12,=<0.16)

https://github.com/sphinx-doc/sphinx/blob/fcb7d01422fa5fd7540f4ee1dcc2746bb0dec56e/setup.py#L26

[Blendify]

I think it is the best to pin the docutils version, to something what is widely tested (or even better a range of versions >=0.12,=<0.16)

https://github.com/sphinx-doc/sphinx/blob/fcb7d01422fa5fd7540f4ee1dcc2746bb0dec56e/setup.py#L26

I agree here with adding a range of versions, these seems like the best approach to prevent issues in the future.

[grubert]

@Eric Holscher @.***> ... having one container run a day/week with pip install --pre ... is this an option ?

On Thu, 8 Apr 2021 at 16:26, Eric Holscher @.***> wrote:

@tk0miya https://github.com/tk0miya @grubert https://github.com/grubert Appreciate the comments here. I fully appreciate https://www.ericholscher.com/blog/2018/feb/7/the-post-i-never-published/ the constraints involved around working on this stuff, and want to specifically thank you for your work on these projects. Having it released on a weekday is not a huge requirement, and becomes less of an issue if we test beta releases more prior to them going out to at least find the widespread issues.

I'd love to offer some help at the RTD level to see if we can possibly increase testing of betas and integration of our the entire stack (docutils -> Sphinx -> Sphinx themes -> RTD) prior to major releases. Does docutils have a similar place for us to track beta timelines? It would be great to be able to coordinate releases of these tools a bit better, if that isn't a burden on the maintainers, but I think at least working on the RTD side to do more testing prior to release is something we can commit to without adding workload to you.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/9056#issuecomment-815868835, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHEYAYD75OGGAQ3LL6TKMDTHW4JPANCNFSM42LDEIZQ .

[tk0miya]

I think it is the best to pin the docutils version, to something what is widely tested (or even better a range of versions >=0.12,=<0.16)

Who confirms it? Who will do widely test? That sounds great if you'll do that! Contributions are always welcome.

[return42]

Who confirms it?

RTD can test .. may be others with a huge base of documents .. and yes I am also willing to help and contribute. I have several projects in which I can test upgrades of docutils (or other stuff).

Or we are building a suite of "test documentation" .. if something like this not already exists.

If I can help I will do it .. but I do not have perfect concept at hand I could suggest .. comments, thoughts?

[tk0miya]

If you can't accept the broken of OSS packages, please pin your packages now. I think there are no perfect programmers. So bugs are usually appeared in the new packages, not only docutils. I guess Sphinx-4.0 also contains some bugs and troubles. So you must pin the version of Sphinx also ASAP. And please wait for it is widely tested.

[ericholscher]

@tk0miya I think the argument is more that we should have the testing flow upstream from released packages. The way it currently works:

• docutils releases betas nobody tests
• docutils releases a final version, which gets installed by everyone because sphinx doesn't pin it
• sphinx is currently broken on the current version for new users, who might have no idea what docutils is
• users scramble to fix sphinx and get a release out that fixes things in a few days

I think the proposed workflow is:

• docutils releases a final version, but it isn't automatically used by sphinx users
• users who understand python packaging can install latest docutils with the latest sphinx, find issues and file bugs
• the new version of sphinx comes out that supports the latest docutils after users have been trying it for a few weeks

This moves the burden of discovering bugs onto advanced users who understand the ecosystem instead of new users who are setting up a broken environment while the releases aren't compatible.

Of note, we could use the existing RTD theme repo as a test case for this: https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#id29

[jakobandersen]

• users who understand python packaging can install latest docutils with the latest sphinx, find issues and file bugs

This seems like the weak link of this strategy. From a pure Sphinx perspective, isn't this basically just another kind of docutils beta in disguise?

Is there a way we can have a CI test with the newest development version or beta docutils? similarly to how we test against the development version of Python, whatever state it is in. Then it is "just" a matter of enough test coverage.

[tk0miya]

My large concern is who will unpin (unrestrict) the version of docutils. Will the RTD team send a PR? In 0.17's case, I did test Sphinx with it (see https://github.com/sphinx-doc/sphinx/pull/8870). But I could not find the trouble. So it means I don't have right to do it. I'm okay if somebody will confirm the docutils release and update it.

[tk0miya]

Is there a way we can have a CI test with the newest development version or beta docutils?

It's not difficult. We can install the HEAD of docutils from here: https://repo.or.cz/docutils.git . We can do test with it on CI. But it's hard to detect the troubles of HTML rendering like 0.17's case...

[return42]

Of note, we could use the existing RTD theme repo as a test case for this

I have written a primer for the searx contributors https://searx.github.io/searx/dev/reST.html

update: I also have https://return42.github.io/linuxdoc/ which contains a test suite and I am familiar with the builds of https://www.kernel.org/doc/html/latest/ just to name some testable resources.

May be we can assemble up a "reference documentation".

But it's hard to detect the troubles of HTML rendering like 0.17's case...

That is the work which needs to be done, every automated solution will have it leaks, I think. If we find a (small) concept and have a "reference documentation" assembled I am willing to do some regularly test.

[tk0miya]

Note (just for me):

• I think the version pinning brings us safety via preventing unexpected version up. But it requires costs for the update.
  • In fact, we had pinned the babel package for a long time, unexpectedly.
  • We need to pay costs to get bug fixes and new features.
  • As discussed, it's difficult to find the all bugs. They will be leaked easily.
  • IMO, it's hard to keep paying the costs (much expensive to us!)
  • As I said above, I can accept pinning if somebody will keep paying the costs.
• Personally, I prefer Linus's law: https://en.wikipedia.org/wiki/Linus%27s_law
  • Releasing a package without pinning will cause problems.
  • Surely, it's painful. But many eyeballs helps us to find and fix bugs.
  • The maintainers will not pay the cost for bug detecting. But another costs for troubleshoot will be needed :-p
• I don't think docutils is fragile.
  • Do you remember the troubles between 0.12 to 0.16?
  • If my memory is correct, no big changes were introduced. (But I admit docutils-0.17 surly contains them)
  • So I can't say we really need to pay costs to confirm the updates in the future too.

I'm not good at discussing in English (TBH, it might be not good in Japanese too). So I'd like to say all you to thank you for discussing with me!

[tk0miya]

I worried @grubert might not noticed to this issue. ping.

[ericholscher]

My large concern is who will unpin (unrestrict) the version of docutils. Will the RTD team send a PR? In 0.17's case, I did test Sphinx with it (see #8870). But I could not find the trouble. So it means I don't have right to do it. I'm okay if somebody will confirm the docutils release and update it.

That's definitely something we can commit to, and partially what I was talking about above. I'd also love to talk about getting funding for Sphinx & docutils through something like the grant that RTD recently got. I'm happy to do some work here to help pay the ongoing costs, as you mentioned.

I think we could work with the top 3-4 themes who likely also have some workflow for handling breaking changes in the output of Sphinx & docutils itself, which would be great in the development process of Sphinx itself.

We're definitely happy to spend resources here working to stop large UX issues, since we pay the bug detecting cost in support requests across our userbase. I'd much prefer to do the work up front and make sure that we're finding bugs in development vs. in support requests, if we can work towards making that happen.

[grubert]

On Fri, 9 Apr 2021 at 18:16, Takeshi KOMIYA @.***> wrote:

Is there a way we can have a CI test with the newest development version or beta docutils?

It's not difficult. We can install the HEAD of docutils from here: https://repo.or.cz/docutils.git . We can do test with it on CI. But it's hard to detect the troubles of HTML rendering like 0.17's case...

for the manpage-writer i did layout regression tests (see sandbox/manpage-writer) groff output to latin and postscript and comparing to previous outcome

for html firefox --headless to png could help ... maybe

—

You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/9056#issuecomment-816794973, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHEYAYTBBS5FOPWXL7PMT3TH4R7TANCNFSM42LDEIZQ .

[tk0miya]

As a just idea, is there any chance to add version restriction into the readthedocs or sphinx_rtd_theme?

[Blendify]

As a just idea, is there any chance to add version restriction into the readthedocs or sphinx_rtd_theme?

Yes we added restrictions to docutils in https://github.com/readthedocs/sphinx_rtd_theme/commit/ca2719b32fcae38923d4830963431e54ded69aae

[tk0miya]

Sounds good.

[grubert]

On Fri, 9 Apr 2021 at 19:35, Takeshi KOMIYA @.***> wrote:

Note (just for me):

• I think the version pinning brings us safety via preventing unexpected version up. But it requires costs for the update.
  • In fact, we had pinned the babel package for a long time, unexpectedly.
  • We need to pay costs to get bug fixes and new features.
  • As discussed, it's difficult to find the all bugs. They will be leaked easily.
  • IMO, it's hard to keep paying the costs (much expensive to us!)
  • As I said above, I can accept pinning if somebody will keep paying the costs.
• Personally, I prefer Linus's law: https://en.wikipedia.org/wiki/Linus%27s_law
  • Releasing a package without pinning will cause problems.
  • Surely, it's painful. But many eyeballs helps us to find and fix bugs.
  • The maintainers will not pay the cost for bug detecting. But another costs for troubleshoot will be needed :-p
• I don't think docutils is fragile.
  • Do you remember the troubles between 0.12 to 0.16?
  • If my memory is correct, no big changes were introduced. (But I admit docutils-0.17 surly contains them)
  • So I can't say we really need to pay costs to confirm the updates in the future too.

I'm not good at discussing in English (TBH, it might be not good in Japanese too).

the important thing is the discussion. i am a technician meaning i work on problems i assume the good will of the coworkers and in this safe space linus law works perfect. if something is not clear to me i try to formulate it again ... different, thereby i learn

So I'd like to say all you to thank you for discussing with me!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/9056#issuecomment-816842423, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHEYAYYG5LBFCTRJ2KYFWTTH43HZANCNFSM42LDEIZQ .

[return42]

As a just idea, is there any chance to add version restriction into the readthedocs or sphinx_rtd_theme?

At searx we also pinned https://github.com/searx/searx/pull/2741

But this does not speak for the quality of sphinx. If this is the solution it needs to be documented in sphinx's user guide .. is this really what we want?

As @ericholscher says: sphinx is currently broken on the current version for new users, who might have no idea what docutils is

Do you remember the troubles between 0.12 to 0.16?

Yes, I also had problems with v0.16, in projects I contribute.

[tk0miya]

But this does not speak for the quality of sphinx. If this is the solution it needs to be documented in sphinx's user guide .. is this really what we want?

Hmm? Pinning version on sphinx_rtd_theme relates the quality of Sphinx? I don't understand what you are saying. What should we add document?

Yes, I also had problems with v0.16, in projects I contribute.

Okay, please pin the Sphinx also. The 4.0 also brings the problems.

[return42]

I'm not good at discussing in English

Feel welcome ... me too :-)

What should we add document?

Perhaps I have misunderstood you, or we have a different opinion of what a product is responsible for. You said

As a just idea, is there any chance to add {docutils} version restriction into {user theme}

What I think: Not only RTD theme is affected by incompatibilities, potential all themes can be effected when the HTML markup of the HTML-5 writer is changed.

Or with other words and in a more general manner; If one builds a product which has a API and the API is changed by an underlying library and this lib is changed in a incompatible manner, the product owner is responsible for the changes in product's API. So I think, there are two solutions:

1. the product owner pins the underlying lib
2. the product owner documents incompatibilities

Okay, please pin the Sphinx also. The 4.0 also brings the problems.

But I guess you will have documented the incompatibilities (CHANGES) for what your product changes are responsible.

[grubert]

On Sat, 10 Apr 2021 at 11:00, Markus Heiser @.***> wrote:

What I think: Not only RTD theme is affected by incompatibilities, potential all themes can be effected when the HTML markup of the HTML-5 writer is changed.

Or with other words and in a more general manner; If one builds a product which has a API and the API is changed by an underlying library and this lib is changed in a incompatible manner, the product owner is responsible for the change in API. So I think, there are two solutions:

1. the product owner pins the underlying lib
2. the product owner documents incompatibilities

Okay, please pin the Sphinx also. The 4.0 also brings the problems.

But I guess you will have documented the incompatibilities (CHANGES https://www.sphinx-doc.org/en/master/changes.html) for what your product changes are responsible.

docutils 0.17 was hit on two sides

• html5 new semantics
  instead of

  . the driver here is html/www/webbrowser
• python3.6 in containers with 7bit ascii the driver here is ... never change a running system although docker is newer then ASCII encoding

interesting times :-)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sphinx-doc/sphinx/issues/9056#issuecomment-817103955, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAHEYA2LCZTHZM4MSIQ2QQDTIAHRRANCNFSM42LDEIZQ .

[tk0miya]

Or with other words and in a more general manner; If one builds a product which has a API and the API is changed by an underlying library and this lib is changed in a incompatible manner, the product owner is responsible for the changes in product's API. So I think, there are two solutions:

I understand your idea. But I feel it's too strict to manage the open source software to me.

At first, I don't know the product owner of Sphinx. At least, I'm not. Do you know them? Additionally, I don't know the standard DOM structure of Sphinx output. Indeed, introducing the semantic tags is incompatible. But I had modified DOM structured on fixing bugs. But I did not mention it on CHANGES ever. If we have to mention the change of DOM structure (or LaTeX output) on each change, I feel the Sphinx core is untouchable... At last, I have no idea how to document it on Sphinx's CHANGES. Is this right:"The semantic tags <section>, <figure>, ... and so on will be used if you're using docutils-0.17 or newer"?

Note: If DOM structure is important promise of Sphinx, we should also pin the pygments, right?

[return42]

At first, I don't know the product owner of Sphinx.

Call it the release manager, the maintainer or more widely the community.

I understand your idea. But I feel it's too strict to manage the open source software to me.

I don't think so, at least not in general. E.g. have a look at the kernel development ..

But I understand your arguments, since open source projects are often limited by its resources.

Here comes the point where @ericholscher, me and may be other want to offer some help / that's why we discuss here, I think.

Note: If DOM structure is important promise of Sphinx, we should also pin the pygments, right?

My experience is, that each project for its own has a different view on this aspect. E.g at searx we pin all libs we are using requirements.txt, but we normally do not pin underlying libs.

To pin or not is most often related to some degree, if it is a product, a tool used in tool chains or it is a pure lib.

For me, searx is a product, sphinx is a tool and and docutils is more a lib and I think it is a bad practice to have semantic versioning and do API changes in a minor patch level .. and this is what docutils do.

So for me the question is; in what level do I handle such a problematic lib. The best would be docutils stop to have major changes in minor releases. But the experience is also, they will continue with this procedure. So what the alternatives are? I go to the next degree to the sphinx community and ask how can we handle this .. and how can I help?

If sphinx community can't handle this due to the limited resource or other good reasons I have to pin this problematic lib. But this will not only affect me, this will affect all users of sphinx. That's why I want to offer some help to sphinx, to find a solution that is less burdensome for users of sphinx.

[tk0miya]

Sorry, I don't understand the goal of this discussion... I don't know why do you mention about the version management of docutils in the last comment. What should "Sphinx project" do for docutils? I feel it's another topic.

Note: About version pinning, it seems agreed now. At least, nobody objects to introduce it now.

[tk0miya]

Now I just release the 4.0.0b1 package. And I posted announce to sphinx-users, sphinx-dev and python-announce-list. https://pypi.org/project/Sphinx/4.0.0b1/

Additionally, I created new branches; 4.x and 4.0.x.

• 4.x will be used for develop 4.1
• 4.0.x will be used for develop 4.0.0 (feature freezer)

From now on, the 4.0.x branch is feature freezed. Please let us know if you still have new features for 4.0.0.

Thanks,

[tk0miya]

From now on, the 4.0.x branch is feature freezed. Please let us know if you still have new features for 4.0.0.

I have two issues.

• I will add a new configuration variable for MathJax3: https://github.com/sphinx-doc/sphinx/issues/8195
• I might add additional codes for python properties (if needed): https://github.com/sphinx-doc/sphinx/issues/7523

[jakobandersen]

From now on, the 4.0.x branch is feature freezed. Please let us know if you still have new features for 4.0.0.

@tk0miya, it would be great if we could get #9023 done for 4.0.0. It dramatically changes the C and C++ HTML output so one could consider it somewhat breaking. There are additional next issues with formatting and C++ features that depends on it as well. Do you have a minute to double check my response to the remaining issues?

[tk0miya]

@return42 Sorry for confusing you. I'd not like to confuse you. But my poor English skill (and discussion skill) would cause my misunderstanding. I really don't understand the goal of the discussion with you yet. If it's the same as @ericholscher said, we have to discuss how to do it (about the workflow).

[return42]

If it's the same as @ericholscher said, we have to discuss how to do it (about the workflow).

Ah, OK, sorry for being impatient .. yes, lets discuss how we can establish a workflow for .. may be we better discuss this in another thread, not dedicated to the Sphinx 4.0.0. @ericholscher what do you think?

[tk0miya]

@jakobandersen Oops... I missed your comment. I just posted comments to #9023. And I'll review it again in a few days. Please wait for a while. I'd like to merge it to the 4.0.0 release. Let's go forward :-)

[felix-hilden]

I tried to collect the points about pinning Docutils to the issue linked above. Hopefully it is a good enough place to continue the discussion.

[ericholscher]

If it's the same as @ericholscher said, we have to discuss how to do it (about the workflow).

Thanks for following up on this. I agree that moving forward here to discuss implementation of a testing process is the best use of our time. It sounds like we have #9088 for discussing that in depth (thanks @felix-hilden), so I won't discuss it more here.

Note: About version pinning, it seems agreed now. At least, nobody objects to introduce it now.

This is great to hear @tk0miya -- thanks for talking through this with us. I will think a bit more in depth about the next steps here and do a PR for it. I agree that pinning pygments is probably good also, to reduce unexpected breakage. If we have a good process for testing changes, we want to make sure we have a development step to "ship" those new changes. I don't think we can keep track of dependencies of dependencies that might cause output changes, so there's also some discussion needed here about what additionally needs to be pinned.

I think we should move the pinning discussion into another thread as well, so folks can get back to discussing 4.0 release features :) I created #9091 to discuss that topic in depth.

[pradyunsg]

Requesting to pin this for visibility, so that users doing beta testing downstream can find this "issue" more easily.

(this is something that pip does, and I've received feedback that it's very useful for folks trying to keep track of the discussion)

[tk0miya]

4.0.0b1 depends on docutils>=0.14,<0.17. I think it's already pinned. Is there anything to do more additionally? I don't understand what "visibility" means.

[pradyunsg]

Ah, I meant pinning the issue; which is a Github feature. Sorry for the confusion! 😅

[ewjoachim]

I believe @pradyunsg is requesting if an admin can click on this "Pin issue" button (👇) which would be located in the right sidebar on this issue page

This would ensure the issue appears at the top of the issue list, make it more visible and reachable.

[tk0miya]

Done it.

[gmilde]

From now on, the 4.0.x branch is feature freezed. Please let us know if you still have new features for 4.0.0.

I suggest to rise the Docutils dependency to < 0.18.

Motivation:

There are three known issues with Docutils 0.17:

a) import error for docutils.writers.latex2e with locale-encoding == "ascii" in Python 3.5 and 3.6.

b) AttributeError because of missing document.settings when parsing included rST parts with the recommonmark parser.

c) backwards-incompatible changes to HTML output of the html5_polyglot writer.

Issues a) and b) are fixed in Docutils 0.17.1 (released 17 Apr 2021).

Issue c) is no bug for a new "major" release, so 4.0 is the best chance to get bug fixes and improvements from Docutils 0.17.x in Sphinx fast.

If additional issues arise, these will be handled in a Docutils 0.17.2 bugfix release.