4.0.0 release plan #9056
Comments
tk0miya
assigned shimizukawa, tk0miya, stephenfin, jfbu, francoisfreitag, TimKam and jakobandersen
|
㊗️ |
|
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. |
|
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
<#9056 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAHEYA4SN4TYSDI6YYIYTYLTHM2YRANCNFSM42LDEIZQ>
.
|
|
I don't know I will have time on weekdays. But it's not impossible. |
|
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. |
|
It is indeed an icky coupling with the domains, though it is difficult to get around. Ok for me to wait for 4.1. |
|
Thank you for understanding :-) |
|
@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. |
|
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. (But I couldn't confirm it well because of lack of time...) |
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 Line 26 in fcb7d01 |
I agree here with adding a range of versions, these seems like the best approach to prevent issues in the future. |
|
@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
<#9056 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAHEYAYD75OGGAQ3LL6TKMDTHW4JPANCNFSM42LDEIZQ>
.
|
Who confirms it? Who will do widely test? That sounds great if you'll do that! Contributions are always welcome. |
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? |
|
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. |
|
@tk0miya I think the argument is more that we should have the testing flow upstream from released packages. The way it currently works:
I think the proposed workflow is:
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 |
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. |
I have two issues.
|
@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? |
|
@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). |
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? |
|
@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 :-) |
|
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. |
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.
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 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. |
|
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) |
|
4.0.0b1 depends on |
|
Ah, I meant pinning the issue; which is a Github feature. Sorry for the confusion! 😅 |
|
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. |
|
Done it. |
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" b) AttributeError because of missing document.settings when parsing included 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 If additional issues arise, these will be handled in a Docutils 0.17.2 bugfix release. |
|
If we can confirm that Sphinx and alabaster are working well with 0.17, I'd be 👍 on pinning to |
|
I'm perfectly confused by the pinning of docutils. So I stopped releasing for a while. refs: #9088 |
|
@tk0miya sorry it took us a few days to finally get to this. @humitos and I have just validated that Sphinx with alabaster looks good with Sphinx 4.0 beta and docutils 0.17.
The only noticeable visual difference I observed, after comparing both versions side to side, are in emphasized code lines (baseline, test). I get the impression that alabaster is not maintained anymore (last commit is from January 2020 and says "Last ever LICENSE copyright update"), therefore I don't think it's worth trying to make a new release of alabaster fixing this small visual difference. In conclusion: in line with the conditions we agreed here and in #9088, my understanding is that Sphinx 4.0 can pin |
|
Now I just released the 4.0.0b2 package. And I posted announce to sphinx-users, sphinx-dev and python-announce-list. I'll wait for reactions from users in a week. So the final release will be shipped on 8th May. Thank you for your support all :-) |
|
Thanks @tk0miya and I'm glad you are feeling better! ^.^ |
I think it's not related to the themes. It comes from a change in #7942. |
|
@tk0miya I think we're good to release 4.0 on 8th May 🎉 Thanks for working with us here to minimize impacts for users, and @astrojuanlu, @humitos, @pradyunsg, and others for jumping in to help test things. Hopefully we can make this process smoother in the future by thinking more about how to pin dependencies (#9091), and building on the work we've done here to test releases of major dependencies (#9088). I'm excited about the collaboration here, and hope we can build on it for future releases. |
Summary: sphinx 4.0 release got delayed bc of sphinx-doc/sphinx#9088 maybe we should spend some time upgrading it to 4.0 once it's released and resolve deps on our end all at once (e.g. pin whats needed) -- (may 8th according to sphinx-doc/sphinx#9056) Test Plan: manually re-indexed search so api doc shows up Reviewers: sashank Reviewed By: sashank Differential Revision: https://dagster.phacility.com/D7785
|
It seems no issues are reported since beta2. So I'll do releasing in tomorrow at noon in JST (about 10-12hrs later). |
|
From now on, I start releasing! |
|
Done. Thank you for all! |
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?
Any comments?
Note: issues marked as 4.0.0: https://github.com/sphinx-doc/sphinx/milestone/74
The text was updated successfully, but these errors were encountered: