Deprecation: require projects define a configuration file

[agjohnson]

Edit: if you arrived at this issue for any reason, make sure to read the blog post that contains all the important info

For some background here, we identified a number of issues that stem from our historical decision to provide a default configuration file and experience to projects that do not define a project configuration file. Because of this stance, we do have a number of projects that do not know about our configuration file and rely on these defaults. This applies to both new projects (for example projects using our tutorial template) and well aged projects (projects started using Sphinx 1.8.5 for example).

Deprecation of this pattern will require that all projects define a Read the Docs configuration file in order to build. In most cases, a basic configuration file can be suggested to the project.

The downstream effect of requiring a configuration file is:

• We can drop support for old build images that are also used by builds without a configuration file.
• We can start to drop support for Sphinx 1.8.5, as we won't automatically opt projects into this version.

We discussed why we could provide new defaults to projects, and the conclusion here was a little nuanced and opinionated in our favor. But at the center of this conversation was also that all other similar services require the user define a configuration file, so this doesn't need to be an expected pattern on our platform.

The order of operations here would be:

• Deprecation: add warning for required configuration #10348
• Deprecation: set dates for requiring configuration file and notify users #10351
• Projects: project creation form configuration file example/templates #10352
• Do anything we can to get projects to add a configuration file before the cutoff date

[steveschnepp]

Would it be possible to have a default for every configuration option. Ideally set to the recommended one?

Such as build.os & build.tools.python being set to the best¹ supported version. This would enable you to rollout new version gradually, as you will be in the driver seat. And for projects that depend on a particular version, they can opt-in to it.

Therefore if I'm just fine with every default, I'd have a file with just version inside. (Even that could have a default, currently 2).

PS: Thanks for your service, it's awesome!
PPS: Requiring an explicit config file is indeed a good idea on many levels.

Footnotes

1. Not necessarily the latest. But the one that you are the most comfortable with. ↩

[humitos]

Hi @steveschnepp! Thanks for you comment and your suggestion here 👍🏼

Would it be possible to have a default for every configuration option. Ideally set to the recommended one?

Such as build.os & build.tools.python being set to the best supported version. This would enable you to rollout new version gradually, as you will be in the driver seat

This is exactly what we have tried and it's how it currently works. Right now, if there is no .readthedocs.yaml file we set every configuration option to a particular default (e.g. Python 3.7). The problem we have here is that it's impossible to maintain updated without breaking thousands of projects with any minor change of these defaults. Every time we tried to update the Python version or the OS version, we broke so many projects that we had to rollback. In the end, we weren't able to update those defaults and we arrived at the situation we are today: the defaults are pretty old and for some use-cases they are completely broken 😞

This is part of the background behind this decision. If you want to know more, you can read our blog post about this at https://blog.readthedocs.com/migrate-configuration-v2/. I hope this explanation helps.

PPS: Requiring an explicit config file is indeed a good idea on many levels.

We are true believers that "explicit is better than implicit" 😉

[steveschnepp]

Thanks!

Actually it was that blog post that led me to here, as I wanted to open a new issue about the defaults, but since I found this one, I simply added a comment. 😉

I understand that the current defaults are old. But let's simply say : those are the v1 defaults.

On the other hand, the v2 defaults should be evolving over time, and indeed they might break many projects.
Yet it's by design, therefore it shall be properly documented. Those projects can then opt-in to fixed versions if they need to.

Which is a part of why requiring to have an explicit config file is a good idea.

We are true believers that "explicit is better than implicit" 😉

Well, for configuration, I was in that camp also. But now, I'm much more in the other side.

As as a consumer, I just want to use the sanest defaults and not think too much about them, unless I really need to.

If everything is explicit, it needs some maintenance from my side, and I won't automatically benefit from any upgrades/enhancement on your side.

[ericholscher]

This is getting tracked in our largest list of deprecation (#10587)