ReadTheDocs Versioning and Release Management

Last updated: July 22, 2026 Document type: Operations guide

For maintainers: understand how ReadTheDocs automatically builds and manages documentation versions across releases.

Overview

ReadTheDocs (RTD) automatically tracks and builds documentation for different versions of the SDK based on git tags and branches. This allows users to view documentation for the specific version they’re using.

Current configuration

The .readthedocs.yml configuration enables docs builds on RTD, but version visibility is controlled by RTD project state:

  1. master branch is typically available as latest.

  2. Git tags are discovered by RTD as version candidates.

  3. Versions appear in the selector only when they are active and built in RTD.

  4. stable is an alias managed in RTD (commonly the latest release tag).

How versioning works

Release versions (git tags)

When you tag a commit with a version number (e.g., v2.0.5), RTD:

  1. Detects the tag as a version candidate.

  2. Builds and exposes it only if that version is active and built (manually or via automation rules).

  3. Serves docs at https://britecore-sdk.readthedocs.io/en/v2.0.5/ once built.

Users can then select that version from the RTD version switcher (bottom-left of documentation).

Branch tracking

  • master branch → Latest development docs

  • Other branches → Not built by default

Release matrix

After several releases, RTD shows:

Version

URL

Status

2.0.5

/en/v2.0.5/

stable (highest tag)

2.0.4

/en/v2.0.4/

old release

2.0.3

/en/v2.0.3/

old release

Latest

/en/latest/

master branch

Creating a new release

Step 1: Create a git tag

git tag v2.0.6 -m "Release version 2.0.6"
git push origin v2.0.6

Step 2: Update version in pyproject.toml

[project]
version = "2.0.6"

Commit and push:

git add pyproject.toml
git commit -m "Bump version to 2.0.6"
git push origin master

Step 3: RTD build and activation

After pushing the tag, RTD detects it. To ensure it appears in the version selector:

  1. Confirm the tag version is active in Admin -> Versions.

  2. Trigger/retry a build for the tag if it is not already built.

  3. Optionally add/update Automation Rules so future v* tags auto-activate and build.

  4. Verify the docs URL exists (for example, /en/v2.0.6/).

RTD web interface

Viewing builds

  1. Go to https://readthedocs.org/projects/britecore-sdk/

  2. Navigate to Builds tab

  3. See all recent builds (master branch and all tags)

  4. Click any build to see logs and output

Configuring versions

  1. Go to Admin → Versions

  2. Toggle versions on/off (hidden versions still accessible via direct URL)

  3. Set “default version” (what loads when user visits root URL)

  4. Mark which version is “stable”

Current defaults:

  • Default version: “latest” (master branch)

  • Stable version: highest tag (auto-selected)

FAQ

Q: Can users view docs for older releases?

A: Yes, as long as those versions are active and built in RTD. Users can:

  1. Click the version switcher (bottom-left of any doc page)

  2. Select any version from the list

  3. Or visit the URL directly: /en/v2.0.3/

Q: Will RTD build from all my branches?

A: No. By default, master maps to latest. Other branches/tags must be enabled in RTD project settings (or covered by automation rules) to be built and shown.

Q: What if I want to hide an old version?

A: RTD provides version hiding:

  1. Go to Admin → Versions

  2. Toggle the version off (“Hidden”)

  3. The docs are still built and accessible via direct URL, but don’t appear in the version switcher

This is useful for yanked releases or pre-releases.

Q: Can I build docs for release candidates?

A: Yes, but you’ll need a different naming scheme. Examples:

  • v2.1.0rc1 (release candidate) — tags matching this still work

  • v2.1.0a1 (alpha) — also supported

All follow semantic versioning patterns that RTD recognizes.

Q: Why do I only see latest and stable in the selector?

A: This usually means tag versions are discovered but not active/built. Check Admin -> Versions and ensure each release tag is enabled and has a successful build.

Q: How do I update docs for a released version?

A: Create a bug-fix tag:

# Create from existing tag (e.g., 2.0.5)
git checkout v2.0.5
git checkout -b hotfix-docs
# Make doc fixes
git add docs/
git commit -m "Fix docs for v2.0.5"
git tag v2.0.5.post1
git push origin v2.0.5.post1

RTD will build v2.0.5.post1 as a new version.