Repository navigation
Closed
Labels
bugSomething isn't working.Something isn't working.t-toolingIssues with this label are in the ownership of the tooling team.Issues with this label are in the ownership of the tooling team.
Description
The v3.0.0 release on 2026-05-20 ran the Version docs job with the pre-bump version 2.5.1 instead of 3.0.0. As a result:
website/versioned_docs/version-2.5/was wiped and re-created from the currentdocs/directory (which contained v3 content) — so2.5now hosts v3 docs.website/versioned_docs/version-3.0/was never created.website/versions.jsonis still["2.5", "1.12", "0.6"].- The published docs site at https://docs.apify.com/api/client/python therefore serves v3 content under the
2.5dropdown entry and has no3.0entry at all.
The bad commit is e0a0bc8 (docs: Version docs for v2.5.1 [skip ci]). The workflow log shows: Version: 2.5.1, Major.Minor: 2.5, Major: 2.
The pipeline fix that prevents this from recurring is tracked separately in #806. This issue covers the data restore only — do not touch any workflows.
Expected end state
website/versions.jsonequals["3.0", "2.5", "1.12", "0.6"](in that order).website/versioned_docs/version-2.5/matches the directory tree at commit 5f7f7b1 — the genuine v2.5 docs:- no
04_upgrading/upgrading_to_v3.mdx - no
02_concepts/10_custom_http_clients.mdx,11_timeouts.mdx,12_typed_models.mdx - smaller
api-typedoc.json(1820266 bytes)
- no
website/versioned_sidebars/version-2.5-sidebars.jsonmatches the file at commit 5f7f7b1.website/versioned_docs/version-3.0/exists and is a fresh Docusaurus snapshot of the currentdocs/directory — v3 content:upgrading_to_v3.mdx,10_custom_http_clients.mdx,11_timeouts.mdx,12_typed_models.mdx, the v3api-typedoc.json(~7.5 MB).website/versioned_sidebars/version-3.0-sidebars.jsonexists. Indent with 4 spaces to match the otherversion-*-sidebars.jsonfiles.- No
changelog.md,pyproject.toml, or.ruff_cache/paths underwebsite/versioned_docs/version-3.0/— they are gitignored at the repo root (see.gitignore) but easy to accidentallyrmfrom disk and forget.
Suggested approach
Docusaurus' built-in versioning does almost all of this. Recipe verified locally on master:
git checkout -b fix/docs-versioning-v3-restore
# 1. Restore version-2.5 to its pre-bug state.
# `rm -rf` first — `git checkout <sha> -- <dir>` does NOT delete files that
# exist in the working tree but not in <sha>.
rm -rf website/versioned_docs/version-2.5
git checkout 5f7f7b1 -- \
website/versioned_docs/version-2.5 \
website/versioned_sidebars/version-2.5-sidebars.json \
website/versions.json
# 2. Generate version-3.0 from current docs/.
cd website
uv run python generate_module_shortcuts.py # populates module_shortcuts.json (gitignored)
pnpm install
pnpm exec docusaurus docs:version 3.0
pnpm exec docusaurus api:version 3.0
cd ..
# 3. Reformat the new sidebar to 4-space indent (docusaurus writes 2-space).
python3 -c "
import json
p = 'website/versioned_sidebars/version-3.0-sidebars.json'
data = json.load(open(p))
with open(p, 'w') as f:
json.dump(data, f, indent=4)
f.write('\n')
"
# 4. Tidy up files docusaurus copied that are gitignored at repo root.
rm -rf website/versioned_docs/version-3.0/.ruff_cache
rm -f \
website/versioned_docs/version-3.0/changelog.md \
website/versioned_docs/version-3.0/pyproject.toml
# 5. Commit (use `docs:` prefix so post-merge `Doc release` triggers on master).
git add -A website/versioned_docs/ website/versioned_sidebars/ website/versions.json
git commit -m "docs: restore version-2.5 and add version-3.0"
git push -u origin fix/docs-versioning-v3-restoreAcceptance criteria
-
cat website/versions.jsonoutputs["3.0", "2.5", "1.12", "0.6"](in that order). -
find website/versioned_docs/version-2.5 -type f | wc -lreturns53. -
ls website/versioned_docs/version-2.5/04_upgrading/lists onlyupgrading_to_v2.mdx. -
ls website/versioned_docs/version-3.0/04_upgrading/lists bothupgrading_to_v2.mdxandupgrading_to_v3.mdx. -
wc -c website/versioned_docs/version-2.5/api-typedoc.jsonreturns1820266. -
git status --shortshows no untracked files insidewebsite/versioned_docs/version-3.0/after the commit. - The PR uses the
docs:conventional commit prefix in its title. - The PR diff touches only
website/versioned_docs/,website/versioned_sidebars/, andwebsite/versions.json. No workflow changes.
References
- Bad commit: e0a0bc8
- Last good state for
version-2.5: 5f7f7b1 - Successful release run with the bug visible in logs: https://github.com/apify/apify-client-python/actions/runs/26156928273
- Pipeline fix (separate PR): ci: pass bumped version and post-bump ref to docs jobs in release flow #806
- Existing working draft of this fix: docs: restore version-2.5 and add version-3.0 #805 — will be closed once the agent's PR lands.
Reacted by Copilot
Metadata
Metadata
Labels
bugSomething isn't working.Something isn't working.t-toolingIssues with this label are in the ownership of the tooling team.Issues with this label are in the ownership of the tooling team.
Activity