From ec7bed6989e96c19c5508940f1a16fd574e57f1e Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 9 Aug 2023 10:26:30 +0200 Subject: [PATCH] Post: Use `build.os` instead of `build.image` (#233) * Post: Use `build.os` instead of `build.image` Announcement for https://github.com/readthedocs/readthedocs.org/pull/10589 * Apply suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Update date --------- Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- use-build-os-config.rst | 59 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 use-build-os-config.rst diff --git a/use-build-os-config.rst b/use-build-os-config.rst new file mode 100644 index 0000000..3b47a1e --- /dev/null +++ b/use-build-os-config.rst @@ -0,0 +1,59 @@ +.. post:: August 9, 2023 + :tags: builders, deprecation + :author: Manuel + :location: BCN + :category: Changelog + + +Use ``build.os`` instead of ``build.image`` on your configuration file +====================================================================== + +We are announcing the deprecation of ``build.image`` config key in favor of ``build.os``. +Read the Docs *will start requiring* a ``build.os`` config key for all projects in order to build documentation successfully. +**We will start failing builds using "build.image" on their config file on October 16, 2023**. + + +Deprecation timeline +-------------------- + +We understand this change will affect many of our users, +so we have a timeline to communicate this deprecation to our users effectively. + +* **Monday, August 28, 2023**: Do the first brownout (temporarily enforce this deprecation) for 12 hours: 00:01 PST to 11:59 PST (noon) +* **Monday, September 18, 2023**: Do a second brownout (temporarily enforce this deprecation) for 24 hours: 00:01 PST to 23:59 PST (midnight) +* **Monday, October 2, 2023**: Do a third and final brownout (temporarily enforce this deprecation) for 48 hours: 00:01 PST to October 3, 2023 23:59 PST (midnight) +* **Monday, October 16, 2023**: Fully remove support for building documentation using "build.image" on the configuration file + + +Migrating to ``build.os`` +------------------------- + +If you have a project on Read the Docs that is using ``build.image``, +**you will need to migrate to the new config key as soon as possible** to continue building your project. + +There are some small differences between ``build.image`` and ``build.os`` that we detail here: + +- ``version: 2`` must be used with ``build.os`` +- To specify the Python version, you have to use ``build.tools.python`` + +Below is an example of a valid ``build`` section of your configuration. +Make sure to make these changes before **October 16, 2023**: + + +.. code:: yaml + + version: 2 + build: + os: "ubuntu-22.04" + tools: + python: "3.11" + +You can read about the ``build.os`` key, including all possible values, in our `"build.os" documentation `_. + +Contact us +---------- + +`Contact us`_ if you have any questions, +and let us know if you are having trouble using a this new config key for any reason. + +.. _Contact us: https://readthedocs.org/support/