Choosing the Right Default Version for Your Read the Docs Project

Problem: Users see outdated or confusing documentation

When a library publishes frequent releases, newcomers often land on the latest build, which may contain undocumented features or breaking changes. Meanwhile, users looking for a stable reference expect the documentation that matches the version they installed. If the default version served by Read the Docs (RTD) does not align with your audience’s expectations, you risk confusion, increased support questions, and a perception of poor maintenance.

Thesis: Align the default RTD version with your release strategy by using explicit version labels, redirects, and a clear default‑version policy.

How Read the Docs handles versions

RTD watches your repository via a webhook. On each push to a linked branch or tag, it spins up an isolated virtual environment, installs dependencies from requirements.txt (or the dependencies declared in conf.py), runs Sphinx, and publishes the generated HTML to a URL that encodes the version name, e.g., https://project.readthedocs.io/en/latest/ or https://project.readthedocs.io/en/stable/. The platform also serves a version‑switcher dropdown that lets visitors pick any built version.

Two special version names are reserved:

• latest – tracks the default branch (usually main or master).
• stable – points to the version you designate as “stable” in the RTD admin interface (often a tag like v1.2.0).

Only one of these can be the default version shown to anonymous visitors; the other remains accessible via the dropdown or a direct URL.

Worked example: Setting stable as the default for a SemVer‑styled project

Assume you maintain a Python package examplelib that follows semantic versioning. You want users who arrive at https://examplelib.readthedocs.io/ to see the documentation for the most recent released version, while developers can still view the cutting‑edge latest build.

1. Prepare the repository

   Ensure you have a docs/ folder with a Sphinx conf.py and a requirements.txt that lists Sphinx and any extensions.

   # docs/requirements.txt
   sphinx>=5.0
   sphinx-rtd-theme>=1.0
   # add any package‑specific dependencies here
   

2. Link the repo to RTD

   In the RTD dashboard, create a new project, connect your GitHub (or GitLab) repository, and grant RTD the repository:read scope (required for the webhook). No additional permissions are needed for public repos.

3. Define version labels

   Push a tag for each release, e.g.:

   # Run locally, you need write access to the repo
   $ git tag v1.2.0
   $ git push origin v1.2.0
   

   RTD will automatically detect the tag and create a version named v1.2.0.

4. Set the stable version

   In the RTD project admin → Versions tab, locate the tag you just pushed (e.g., v1.2.0), click the three‑dot menu, and choose Set as stable. This tells RTD to serve stable from that tag.

5. Make stable the default

   Still in the Versions tab, find the stable line, open its settings, and enable Set as default version. Anonymous visitors to https://examplelib.readthedocs.io/ will now see the documentation for v1.2.0.

6. Optional: Redirect latest to stable for SEO

   If you prefer that even the latest URL points to the stable release, add a redirect rule in the admin → Redirects page:

   # Source: /en/latest/
   # Destination: /en/stable/
   # Type: 302 (temporary) – preserves the ability to view true latest later
   

Trade‑offs and limitations

Choosing stable as the default improves the experience for production users but introduces a few considerations:

• Build frequency: The latest version still triggers on every push to the default branch. If your project has many commits, this can increase CI load on RTD’s shared runners. Mitigate by limiting pushes to main or using [skip rtd] in commit messages when a change does not affect docs.
• Cache stale: RTD fronts its static files with a global CDN and a proxy cache. After you promote a new tag to stable, the CDN may continue serving the previous stable build for a short period (typically a few minutes). You can verify the update by requesting the page with a cache‑busting query string, e.g., curl -I https://examplelib.readthedocs.io/en/stable/?_=$(date +%s) and checking for a 200 response and the expected Last-Modified header.
• Private repositories: If your code is private, RTD needs OAuth permissions to read the repo. Some organizations restrict the repository:read scope, which can prevent the webhook from firing. In that case, you must manually trigger builds via the RTD API or use a self‑hosted RTD instance.

Actionable closing

To ensure your documentation serves the right audience:

1. Adopt a clear versioning policy (e.g., every released tag becomes stable).
2. Set that tag as the default version in the RTD admin.
3. Keep the latest build active for contributors who need to see in‑progress changes.
4. Monitor build times in the RTD Builds tab and adjust commit frequency or use skip flags if you notice timeouts.
5. After promoting a new stable tag, confirm the change with a direct request or by checking the version dropdown in the browser.

By aligning the default RTD version with your release cadence, you reduce confusion, lower support overhead, and present a polished, reliable documentation experience to both users and developers.