Schema includes new Python versions before they are supported in the build environment (causing premature Renovate PRs)

[vivodi]

Description

I noticed a synchronization issue regarding the schema.json update and the actual build environment support for Python 3.14.

Previously, I encountered build errors when trying to use Python 3.14, even though it was already listed as valid in the schema file.
It works now, but there was a time lag (whether hours or days) between the schema update in this repository and the actual infrastructure support.

Impact

We use Renovate to automate our dependency updates based on your schema.

1. Renovate detected the change in schema.json (allowing 3.14) immediately after it was merged into the main branch.
2. It opened a PR to update our configuration (e.g., chore(deps): update dependency python to v3.14 Flexget/Flexget#4679).
3. The PR checks failed because the Read the Docs build servers had not yet been deployed with the new version support at that specific moment.

Hypothesis

I suspect this happens because the schema.json lives in the source code repository. When a PR merging support for a new Python version is merged, the schema updates immediately on GitHub, but there is a delay before that code is deployed to the production build servers.

Suggestion

Publish the official schema to a live URL (e.g., on docs.readthedocs.io or an API endpoint) representing the current production state.

If we could point Renovate to a URL that is only updated after (or during) the production deployment, it would ensure the schema is never ahead of the actual build capabilities. Relying on the file in the main branch of the source repo seems to be the root cause of these premature PRs.

[humitos]

I suspect this happens because the schema.json lives in the source code repository. When a PR merging support for a new Python version is merged, the schema updates immediately on GitHub, but there is a delay before that code is deployed to the production build servers.

This is exactly what happened. We merge everything into main and we deploy only once a week. There will be always a gap between what's in master and what's in production.

If you want to check for the code that's deployed in production, you can use rel branch for that.

[vivodi]

@humitos However, even using the schema from the rel branch results in a timing lag. There is still a delay between when a new release is created/tagged in the repository and when that release is actually deployed and active on readthedocs.org.

Here is the timeline that confirms this issue:

1. RTD Release Commit: The latest commit on your rel branch (65a5ac9) was created at Nov 26, 2025, 12:03 AM GMT+8.
2. Renovate Update: Our Renovate detected the change and created a new commit (21a8a80) at Nov 26, 2025, 12:57 AM GMT+8.

Although Renovate ran 54 minutes after your release commit, the build still failed because the build environment for Python 3.14 had not yet been fully deployed.

This suggests that relying on any Git branch (even rel) is risky for automation tools because the schema updates precede the actual infrastructure deployment.

[humitos]

Yes. There is a lag between we merge PRs and deploy the changes to production. rel branch will have the minimum of that time.

[vivodi]

Yes. There is a lag between we merge PRs and deploy the changes to production. rel branch will have the minimum of that time.

@humitos Ideally, I would hope for a schema source that is perfectly consistent with the current live build system.

If that is not strictly possible due to your deployment process, could you consider providing an endpoint with release timestamps for the supported runtime versions (Python, Golang, Rust)?

This would allow us to use Renovate's Custom Datasource mechanism (see documentation: https://docs.renovatebot.com/modules/datasource/custom/) combined with the minimumReleaseAge configuration. With accurate timestamps, Renovate can automatically wait for a set period (to account for the deployment lag) before opening a PR.

For example, a data structure like this would be extremely helpful for automation tools:

{
  "pythonReleases": [
    {
      "version": "3.13",
      "releaseTimestamp": "2024-11-24T18:21Z"
    },
    {
      "version": "3.14",
      "releaseTimestamp": "2025-11-26T08:00Z"
    }
  ]
}

[stsewd]

Some options:

• Merge the schema changes after the deploy is done
• Expose an endpoint with the current schema app.readthedocs.org/schema.json or something.

I think I'd be fine with the second option.