Deprecation: set dates for requiring configuration file and notify users #10351

agjohnson · 2023-05-24T22:39:00Z

This is related to #10348, but separate because this is going to be a larger marketing push instead of a technical change.

With on site notifications enabled, the next step to educating users will be to send some direct emails, write a blog post or two, and probably try any other avenue that we can to reach our users. We talked about reviving some of the work on the RTD assistant code as well, but at very least we should probably expect to jump in and assist some of our larger and older projects.

This is a list of a few of the things that we talked about doing here:

Use a feature flag to decide whether or not hard fail the builds that are not using a configuration file at all or are using v1. This will be useful in the future when we want to make the builds to fail during a reduced period of time to inform users/customers about this deprecation. Related #10351

humitos · 2023-05-25T13:58:44Z

We probably want a feature flag so we can manage which projects get this logic and have a way to disable the logic without a deploy

I implemented this in #10355

Write an email notification to be sent to project maintainers every week or so

I've already implemented this in #10354. We can update the email with more information once we have a blog post and more documentation written around this issue.

humitos · 2023-05-25T14:22:24Z

Having a timeseries question on metabase would be a great addition

I created the followings, which will be useful to track adoption here:

Number of rojects specifying version: 1 in the config file with a build in the last 30 days
Projects without readthedocs.yaml config file (timeserie) (takes some time to compute)
Number of projects without a config file with a build in the last 30 days

agjohnson · 2023-05-25T16:44:49Z

Projects without readthedocs.yaml config file (timeserie)

This one seems like the most useful graph for monitoring active builds/projects. It's probably the first graph we'll want to check 👍

The version 1 configuration graph is handy, I'm glad that number is fairly low. The non timeseries project count seems like the query is similar to the timeseries graph above, so I'd probably just use that.

I feel like I wanted a different graph here for counting the total number of projects (not builds or projects that are active), but I can't say how that would be used much different than this graph above. Perhaps removing the timeframe from the query? It's okay if this is just a static number that we can note and check up on, it doesn't need to be timeseries.

humitos · 2023-05-25T17:38:17Z

I feel like I wanted a different graph here for counting the total number of projects (not builds or projects that are active)

We don't have this data outside the Build or BuildData objects. We need a build (even if it's old) to know if they are building with/without a configuration file. We could check all the projects that have had at least one build since we started collecting data on Telemetry. This may be slow, but I think it's possible. I'll give it a try. I'm also interested in this number 👍🏼

agjohnson · 2023-05-25T17:41:29Z

Yeah, I think that's what I was looking for, though it also seems like that will be close to the timeseries figure too.

humitos · 2023-05-30T11:39:39Z

I created https://ethicalads.metabaseapp.com/question/372-projects-without-readthedocs-yaml-config-file?days=180 which gives us the number of projects that are not using a configuration file. It's based on BuildData objects, so it only considers the last 180 days -- which I think it's enough for our purpose ¹. Currently, this number is 22.9k

note that we don't have other way to check whether or not they are using a configuration file than looking into BuildData unfortunately. ↩

This is a continuation of the work done for * #10351 * #10342 * #10348 * #10355 In that work we added notifications, warning messages and finally a feature flag to start failing the builds without a configuration file or using v1. This commit removes all the code for config file v1 and building without a configuration file. Due to that, it also removes the code that allows users to use the older Docker images (testing, latest, stable) This work can be merged once we enable the feature flag to fail the builds for all the projects and we are happy with the results.

agjohnson · 2023-05-30T17:40:37Z

Excellent, that seems good enough. We only really need this for a second spot check on overall progress anyways.

humitos · 2023-05-31T13:21:11Z

Once we merge #10354, we will have the number of total projects without a configuration file logged in New Relic because of this line:

readthedocs.org/readthedocs/projects/tasks/utils.py

Lines 231 to 235 in 400214f

    
           log.info( 
        
               "Sending deprecated config file notification.", 
        
               query_seconds=(datetime.datetime.now() - start_datetime).seconds, 
        
               projects=n_projects, 
        
           )

agjohnson · 2023-05-31T17:36:19Z

I've edited with the dates we discussed in our meeting today:

July 24 first brownout date, times TBD
Aug 7 second brownout date, times TBD
Aug 28 is where we may decide to extend our timeframe and patch build images
Sep 4 is the cutoff date where we start failing builds

ericholscher · 2023-05-31T22:19:41Z

Updated the blog post with those dates: readthedocs/blog#221

* Config: deprecated notification for builds without config file When we detect a build is built without a Read the Docs configuration file (`.readthedocs.yaml`) we show multiple notifications: - a static warning message in the build detail's page - a persistent on-site notification to all maintainers/admin of the project - send a weekly email (at most) This is the initial step to attempt making users to migrate to our config file v2, giving them a enough window to do this and avoid breaking their builds in the future. Closes #10348 * Test: invert logic * Build: fail builds without configuration file or using v1 Use a feature flag to decide whether or not hard fail the builds that are not using a configuration file at all or are using v1. This will be useful in the future when we want to make the builds to fail during a reduced period of time to inform users/customers about this deprecation. Related #10351 * Update copy to follow the same style * Upgrade `common/` to use the latest versions for pre-commit This is an attempt to solve the issue with the CircleCI `checks` test. * Dont trigger the task on each build, and linting * Linting * Lint * Latest `common/` * Apply suggestions from code review Co-authored-by: Anthony <[email protected]> --------- Co-authored-by: Anthony <[email protected]>

humitos · 2023-06-21T18:00:21Z

I'm going to close this issue because all the work is done here or was split into other issues. We just need to come back with some adoption numbers close to the dates to know how things are going on.

agjohnson · 2023-08-30T00:53:03Z

The date that is next up is our final cut off. Are we comfortable continuing with our plan or do we need to extend this timeframe?

In May 22.9k projects weren't using a configuration file, but I don't know where the figure is today as the Metabase question won't load.

@humitos do you have an up to date figure here?

humitos · 2023-08-30T10:28:26Z

IMO, we are fine sticking with our plan. We have been notifying users every week since we started and doing some support to help them migrate to the YAML file.

In May 22.9k projects weren't using a configuration file, but I don't know where the figure is today as the Metabase question won't load.

With the increase of spam we have had it's hard to know how many of those are spam with a simple query 😞

There are other queries that could help here as well (using 30 days):

…10367) * Deprecation: remove code for config file v1 and default config file This is a continuation of the work done for * #10351 * #10342 * #10348 * #10355 In that work we added notifications, warning messages and finally a feature flag to start failing the builds without a configuration file or using v1. This commit removes all the code for config file v1 and building without a configuration file. Due to that, it also removes the code that allows users to use the older Docker images (testing, latest, stable) This work can be merged once we enable the feature flag to fail the builds for all the projects and we are happy with the results. * Deprecation: update documentation of config file * Deprecation: update config file to remove old keys * Deprecation: update config file v2 docs to deprecate keys - python.version - python.system_packages People should not be using these keys. * Remove auto-install requirements file found on project * Make the deprecated fields read-only as discussed * Remove tasks to send emails about deprecations * Lint & Tests * Remove reference to v1 config file docs * Normalize `get_build_config()` * Update tests for config file * Update tests for collectors * Update tests to follow the new deprecations * Remove invalid tests * More updates related to the config files * Update more tests * Lint

agjohnson added Improvement Minor improvement to code Needed: design decision A core team decision is required labels May 24, 2023

This was referenced May 24, 2023

Deprecation: require projects define a configuration file #10342

Closed

Deprecation: add warning for required configuration #10348

Closed

humitos added this to 📍Roadmap May 25, 2023

github-project-automation bot moved this to Planned in 📍Roadmap May 25, 2023

humitos mentioned this issue May 25, 2023

Build: fail builds without configuration file or using v1 #10355

Merged

humitos mentioned this issue May 29, 2023

Post: deprecation of building without config file readthedocs/blog#219

Merged

humitos mentioned this issue May 30, 2023

June 2023 newsletter - open for ideas readthedocs/blog#218

Merged

8 tasks

humitos mentioned this issue May 30, 2023

Deprecation: remove code for config file v1 and default config file #10367

Merged

benjaoming mentioned this issue Jun 21, 2023

Docs: Update tutorial and repo with .readthedocs.yaml #10454

Closed

3 tasks

agjohnson assigned humitos Jun 21, 2023

humitos closed this as completed Jun 21, 2023

github-project-automation bot moved this from Planned to Done in 📍Roadmap Jun 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deprecation: set dates for requiring configuration file and notify users #10351

Deprecation: set dates for requiring configuration file and notify users #10351

agjohnson commented May 24, 2023 •

edited by benjaoming

Loading

humitos commented May 25, 2023

humitos commented May 25, 2023 •

edited by agjohnson

Loading

agjohnson commented May 25, 2023

humitos commented May 25, 2023

agjohnson commented May 25, 2023

humitos commented May 30, 2023 •

edited

Loading

agjohnson commented May 30, 2023

humitos commented May 31, 2023

agjohnson commented May 31, 2023

ericholscher commented May 31, 2023

humitos commented Jun 21, 2023

agjohnson commented Aug 30, 2023

humitos commented Aug 30, 2023

Deprecation: set dates for requiring configuration file and notify users #10351

Deprecation: set dates for requiring configuration file and notify users #10351

Comments

agjohnson commented May 24, 2023 • edited by benjaoming Loading

humitos commented May 25, 2023

humitos commented May 25, 2023 • edited by agjohnson Loading

agjohnson commented May 25, 2023

humitos commented May 25, 2023

agjohnson commented May 25, 2023

humitos commented May 30, 2023 • edited Loading

Footnotes

agjohnson commented May 30, 2023

humitos commented May 31, 2023

agjohnson commented May 31, 2023

ericholscher commented May 31, 2023

humitos commented Jun 21, 2023

agjohnson commented Aug 30, 2023

humitos commented Aug 30, 2023

agjohnson commented May 24, 2023 •

edited by benjaoming

Loading

humitos commented May 25, 2023 •

edited by agjohnson

Loading

humitos commented May 30, 2023 •

edited

Loading