Deprecation: set dates for requiring configuration file and notify users

[agjohnson]

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:

• Decide on some dates.
  • First brownout date is July 24. We'll fail builds in ~2h blocks for each build peak (Asia morning, Europe morning, Americas morning)
  • Second brownout date is Aug 7. We will fail builds in blocks again
  • Cutoff date is Sept 4, 1 week before urllib3 deprecation of libssl 1.1.1
• Add a feature flag so we can manage which projects get build errors for a missing configuration file and so we have a way to disable the logic without a deploy
  • Build: fail builds without configuration file or using v1 #10355
• Set some milestones we'll aim for. Re-evaluate our plan if we're wrong
  • Watch drop in project count around notification start, brownout dates, and leading up to Aug 28.
  • Aug 28 is our last chance to extend our dates and we can just patch our build images
  • Look at adoption numbers, number of projects without a configuraton file
  • Having a timeseries question on metabase would be a great addition
• Write an email notification to be sent to project maintainers every week or so
  • Include dates, example configuration or link to examples, etc
• Blog post, probably a copy of the email notification in some fashion
• Mention in newletters too
• Update the tutorial to mention the YAML file Docs: Update tutorial and repo with .readthedocs.yaml #10454
• Update the tutorial repository to include a YAML file Docs: Update tutorial and repo with .readthedocs.yaml #10454
• Update config file v1 documentation page to mention the blogpost (see Docs: Config file deprecation warnings #10372)

[humitos]

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]

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]

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]

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]

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]

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

Footnotes

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