Docs: policy for supported tools and dependencies #7859
Conversation
docs/supported-tools.rst
Outdated
|
|
||
| Conda: | ||
| Miniconda2 ``4.6.14`` | ||
| (could be updated to use the latest version by default). |
There was a problem hiding this comment.
I think we can start sampling more projects to use update_conda_at_startup, we have noticed that this solves some OOM errors, and it's faster :)
There was a problem hiding this comment.
Yeah. However, we have found also that sometimes a conda upgrade broke the build. So, there is some tradeoff here.
I think the best solution here is to continue the path towards mamba.
There was a problem hiding this comment.
I don't think we should push to mamba as a replacement for conda, it should be an option. We already update pip on each build, if conda breaks is probably temporary and not so usual.
There was a problem hiding this comment.
It's true we update pip. However, pip is way more stable than conda in our experience 😄
There was a problem hiding this comment.
Another difference between upgrading pip and conda is that conda could take a lot of time to update.
| mock: | ||
| ``1.0.1`` (could be removed in the future). | ||
|
|
||
| pillow: | ||
| ``5.4.1`` (could be removed in the future). | ||
|
|
||
| alabaster: | ||
| ``0.7.x`` (could be removed in the future). | ||
|
|
||
| commonmark: | ||
| ``0.8.1`` (could be removed in the future). | ||
|
|
||
| recommonmark: | ||
| ``0.5.0`` (could be removed in the future). |
There was a problem hiding this comment.
I think we should put all these under a feature flag to stop installing them on new projects.
There was a problem hiding this comment.
I think we should remove all these optional ones at the same date for new projects.
There was a problem hiding this comment.
Can we replace all occurrences of "could be removed in the future" with a set date? That will make this policy easier to publish.
Following this, there are definitely some action items to pick. For instance, adding warnings in build logs and contacting users directly. But I think it's fine to start with a nice coherent policy.
|
|
||
| * - ``2.7.x`` | ||
| - Jan 01, 2020 | ||
| - Nov 31, 2021 |
There was a problem hiding this comment.
This is overdue... but we didn't have this policy before... so
There was a problem hiding this comment.
It's also a huge change, and will likely still lead to a lot of yelling.
There was a problem hiding this comment.
This looks good to me. I'd like to talk a little more about some topics and make some adjustments before merging. I like the idea of having these policy, tho. It will help us to organize ourselves and have better communication to our users.
I don't think we should offer extended support for any version (Python or package) after their own EOL. I'm fine if they keep working for a while after their own EOL, but I don't think we should compromise ourselves.
I assume that all the dates listed here are suggestions. What did you base on to define them? For example, it says we will support old Sphinx versions (some <2.x) for some more years.
I also think we should have a plan to communicate users when we are about to reach the end of support date. Find out what projects are pinning these dependencies reaching EOL and communicate them via email, for example.
It could be good have a closing paragraph explaining "What to do?" if any of your projects have reached (or is about to) the EOL date.
docs/supported-tools.rst
Outdated
|
|
||
| * - ``3.x`` | ||
| - Apr 5, 2020 / ??? | ||
| - 5.0 is released or later/early |
There was a problem hiding this comment.
What does "or later/early" mean? It seems like we don't really know 😄
There was a problem hiding this comment.
This is a date that isn't decided yet, but are aiming to 5.0, but something can happen, and we should be ready to stop supporting this version or keep supporting it.
There was a problem hiding this comment.
This should be clarified in some manner in the policy.
On the three points defined in the document: release date, latest update, usage (this mainly on our current pinned versions, since there isn't an easy way to query what versions users are using).
This is offered for our users on .com, this is similar to what ES cloud does. As they are paying us for support, I think it makes sense. For the community side, having a grace period should be good as well, some users may forget about any notice or not be around for some time.
Don't think it is useful to get the exact data (this is even complicated as we would need to parse all builds in storage). Having an email sent to everyone should be just fine, and publishing a blog post when a date is close. |
Co-authored-by: Manuel Kaufmann <[email protected]>
| * - ``1.8.x`` | ||
| - Sep 12, 2018 | ||
| - Mar 10, 2019 | ||
| - Nov 31, 2022 |
There was a problem hiding this comment.
Just noting for others: this date is dependent on deprecating Python 2.7 first. Sphinx>=2 requires Python>=3.5. A year seems like a good amount of lead time for projects to make the switch.
|
|
||
| sphinx-rtd-theme: | ||
| Projects created before October 20, 2020 (January 21, 2021 for :doc:`/commercial/index`) use ``0.4.3``. | ||
| New projects use the latest version. |
There was a problem hiding this comment.
I'm not sure about not installing the theme in the future as well. Like, it's an external dependency, but it's a "core" product as well.
There was a problem hiding this comment.
Yea, not sure what is best here. I think we can probably just not install it and let users handle it?
There was a problem hiding this comment.
Not installing it means fixing the “what happened?” issue when you find out that the rendering of your documentation locally does not match what Read The Docs shows.
However, it’s a great theme, and if it’s not installed by default, it will be somewhat harder for people to discover it, or at least it will become less popular due to people tending to leave whatever is default.
There was a problem hiding this comment.
@Gallaecio we are trying to do less "magic" for users in favor of being more explicit and having reproducible builds locally. In this case users would need to add the theme to their requirements, we would update or add guides to help users with this.
| --------------------- | ||
|
|
||
| Our policy defines how long a given tool or dependency is considered supported. | ||
| Read the Docs will contact all users when an end of support date is close, |
There was a problem hiding this comment.
Do we have the ability to do this? I don't think we store versions of these anywhere.
There was a problem hiding this comment.
For python I think we can do it, for the other versions is complicated yeah, maybe just communicate this in our newsletter now that we have one :D
|
|
||
| sphinx-rtd-theme: | ||
| Projects created before October 20, 2020 (January 21, 2021 for :doc:`/commercial/index`) use ``0.4.3``. | ||
| New projects use the latest version. |
There was a problem hiding this comment.
Yea, not sure what is best here. I think we can probably just not install it and let users handle it?
| mock: | ||
| ``1.0.1`` (could be removed in the future). | ||
|
|
||
| pillow: | ||
| ``5.4.1`` (could be removed in the future). | ||
|
|
||
| alabaster: | ||
| ``0.7.x`` (could be removed in the future). | ||
|
|
||
| commonmark: | ||
| ``0.8.1`` (could be removed in the future). | ||
|
|
||
| recommonmark: | ||
| ``0.5.0`` (could be removed in the future). |
There was a problem hiding this comment.
I think we should remove all these optional ones at the same date for new projects.
docs/supported-tools.rst
Outdated
| We guarantee that these dependencies will work with all current supported versions of our tools, | ||
| you don't need to specify them in your requirements. | ||
|
|
||
| - readthedocs-sphinx-ext |
There was a problem hiding this comment.
This should link to the repo.
| * - ``1.7.x`` | ||
| - Feb 12, 2018 | ||
| - Sep 5, 2018 | ||
| - Nov 31, 2022 |
There was a problem hiding this comment.
Are these the .org or .com EOL? We should probably keep them the same, TBH, and just handle case-by-case users as we need to.
There was a problem hiding this comment.
These are .org. I'm fine having the same date. I was thinking more about support requests than compatibility support.
|
|
||
| * - ``2.7.x`` | ||
| - Jan 01, 2020 | ||
| - Nov 31, 2021 |
There was a problem hiding this comment.
It's also a huge change, and will likely still lead to a lot of yelling.
|
+1000 on good communication. And also, if we can, inform our decisions with data: #8124 |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
@stsewd I wonder if we can split the docs around installed versions out from this PR, so we can merge it without agreeing on the policy? |
|
Done in #8503 |
|
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. |
|
This still seems worth doing. |
| Read the Docs will contact all users when an end of support date is close, | ||
| after that date your builds may start failing and you will need to upgrade in order to receive support. |
There was a problem hiding this comment.
@humitos wouldn't you say that this is possible?
| Read the Docs will contact all users when an end of support date is close, | |
| after that date your builds may start failing and you will need to upgrade in order to receive support. | |
| Read the Docs will share advice when a end date for support is known. | |
| If detection of tool usage is possible, users will be contacted directly. | |
| After the end date, your builds may start failing and you will need to upgrade or change the tool in order to receive support. |
There was a problem hiding this comment.
Yeah, we are tracking "all packages installed in the virtualenv" now. So, if we want, we could contact "all users building their docs with Sphinx==3.2.1"
There was a problem hiding this comment.
I'm poking around to see if this documentation change can go in before the Diátaxis refactor, but I'm thinking it might be too much. Unless someone feels like it's a good occasion to kick the ball up field and start running? :)
The policy looks great to me, and I think not having one might be worse than having one that may need some updates. I haven't seen anything in this policy that for instance promises too much?
| mock: | ||
| ``1.0.1`` (could be removed in the future). | ||
|
|
||
| pillow: | ||
| ``5.4.1`` (could be removed in the future). | ||
|
|
||
| alabaster: | ||
| ``0.7.x`` (could be removed in the future). | ||
|
|
||
| commonmark: | ||
| ``0.8.1`` (could be removed in the future). | ||
|
|
||
| recommonmark: | ||
| ``0.5.0`` (could be removed in the future). |
There was a problem hiding this comment.
Can we replace all occurrences of "could be removed in the future" with a set date? That will make this policy easier to publish.
Following this, there are definitely some action items to pick. For instance, adding warnings in build logs and contacting users directly. But I think it's fine to start with a nice coherent policy.
| External dependencies (Conda) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| These are the dependencies that are installed by default when using a Conda environment: |
There was a problem hiding this comment.
Has any of this changed?
| External dependencies (Python) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| These are the dependencies that are installed by default when using a Python environment: |
There was a problem hiding this comment.
Has any of this changed?
|
|
||
| * - ``2.7.x`` | ||
| - Jan 01, 2020 | ||
| - Nov 31, 2021 |
|
We have something similar at https://docs.readthedocs.io/en/stable/build-default-versions.html It's also outdated, since it mentions only two doctools
It does not defines "how/when Read the Docs upgrades these dependencies" tho --which I think the policy on this PR does. That said, I wouldn't target this policy to be finished and merged before the Diataxis refactor since it will require a lot of discussion to define the process. |
|
Sounds good @humitos 👍 I'm marking it as blocked for now - of course continuing to work on it can be fine. |
|
I'm closing this PR for now since lot of things have changed, we are supporting multiple doc tools now and we want to move away from having one and only one "fixed builder" and replace them with versioned builders at some point. |
Ok, I think this should be ready.
I didn't list six, since it was added just as a workaround #7717
Let me know what you think about the dates and the process.
I didn't put an end of date for some internal deps, but I think we should decide on one (or at least put all those under a feature flag and all projects before that date will use it)