Skip to content

fix: repair the Academy course registry, and correct tenant backup coverage - #522

Open
g-despot wants to merge 2 commits into
mainfrom
docs/academy-links-and-tenant-backups
Open

fix: repair the Academy course registry, and correct tenant backup coverage#522
g-despot wants to merge 2 commits into
mainfrom
docs/academy-links-and-tenant-backups

Conversation

@g-despot

Copy link
Copy Markdown
Contributor

Two unrelated defect classes, one commit each — review them separately.

1. The Academy course registry had drifted

AcademyAdmonition/courses.json is the map from docs pages to Academy courses, and it had gone stale in four ways: one entry pointed at the wrong course (embedding-model-evaluation → wa150-py instead of wa260-py), one carried a since-renamed title, one advertised wa280-py which 404s, and four live courses had no entry at all. The component's own usage example also named a courseId that does not exist.

Every id written here was checked three ways: an entry in the Academy courses.json, a matching directory on disk, and a live 200. vdb101m-ts and wa101t-js are deliberately excluded — both are declared in the Academy catalog but neither is actually served.

netlify.toml: two legacy paths had no successor rule and fell through to the /academy/py/* catch-all, so readers following old chunking and multimodal links landed on the Python starter course. Netlify takes the first matching rule, so ordering is the fix — the two new rules sit above the catch-all. Verified by replaying rule resolution against both the old and new file; six probes change, every regression probe is byte-identical, and the same rules placed below the catch-all resolve back to the wrong course.

Note this registry is not a surface: adding an entry does not put a course in front of a reader until a page uses <AcademyAdmonition courseId="…"/>. Several pre-existing entries are likewise unreferenced.

2. Two pages said backups exclude inactive tenants

They haven't since 89c457f9a9. Backups include ACTIVE and INACTIVE tenants — inactive shards are read straight off disk with no activation — and only FROZEN/OFFLOADED are skipped, because they hold no local data. concepts/data.md and manage-collections/multi-tenancy.mdx both carried the old claim; deploy/configuration/backups.md already had the substance right.

The direction of this error matters. It tells operators their inactive tenants are unprotected, so they either activate every tenant before each backup — pointless work on a live multi-tenant cluster, and self-defeating — or build a workaround for a problem that no longer exists.

The floor is not simply v1.37. The change was backported: present in v1.35.17, v1.36.10 and v1.37.0, absent from v1.35.16 and v1.36.9. A bare "starting in v1.37" would tell a reader on the supported 1.36 line that they lack the feature, so all three pages now name the backported versions. backups.md needed only that correction.

Restore behaviour for offloaded tenants is deliberately not claimed. Core shows their status survives and their shard is omitted from the descriptor; whether a restored offloaded tenant can be onloaded was not verified.

I grepped docs/, _includes/ and blog/ for other statements of the claim, then inspected every file containing both "backup" and "inactive|offload". These three were the only sites.

Verification

npm run build-dev exits 0. The broken-link and broken-anchor lists are byte-identical to a pre-change baseline build — 4 pre-existing broken links and 1 pre-existing broken anchor, none related to this change. Both new #manage-tenant-states anchors validate. Rendered HTML checked on all three tenant pages and on four pages carrying an AcademyAdmonition.

Related

The matching Academy-side content fixes are weaviate/weaviate-academy#71.

🤖 Generated with Claude Code

https://claude.ai/code/session_011KDHXjWpoPozpZh6RpdgRW

The AcademyAdmonition registry had drifted from the Academy site:

- embedding-model-evaluation pointed at wa150-py (A Gentle Deep Dive into
  AI Models) rather than wa260-py, the course its own title and description
  describe.
- The wa050-py entry still carried its old title, A Quick Tour of Weaviate.
- An entry advertised wa280-py, which has no directory and returns 404.
- Four live courses had no entry at all: wa220-py, wa230-py, wa910-py and
  wa921-py. Every added id was checked against both the Academy courses.json
  and the on-disk course directory, and confirmed to return 200.
- The usage example in index.jsx named a courseId that does not exist.

netlify.toml: two legacy paths, /academy/py/standalone/chunking/* and
/academy/py/starter_multimodal_data/*, had no successor rule and fell through
to the /academy/py/* catch-all, landing chunking and multimodal readers on the
Python starter course. Netlify applies the first matching rule, so the two new
rules are placed above the catch-all; verified by replaying rule resolution
against both the old and new files.

vdb101m-ts and wa101t-js are deliberately excluded: both are declared in the
Academy catalog but neither is served.
Two pages stated that backups exclude inactive tenants. That stopped being
true when backup/restore of INACTIVE tenants shipped in commit 89c457f9a9.
Backups now include ACTIVE and INACTIVE tenants; inactive shards are read
straight off disk with no activation, and only FROZEN/OFFLOADED are skipped
because they hold no local data.

The stale claim tells operators their inactive tenants are unprotected, so
they either activate every tenant before each backup, which is pointless work
on a live multi-tenant cluster, or build a workaround for a problem that no
longer exists.

The floor is not simply v1.37: the change was backported, and is present in
v1.35.17, v1.36.10 and v1.37.0 while absent from v1.35.16 and v1.36.9. A bare
v1.37 would tell a reader on the supported 1.36 line that they lack the
feature. backups.md already had the substance right and only needed the
backported versions added.

Restore behaviour for offloaded tenants is deliberately not claimed here; only
that their status survives and their shard is omitted.

@orca-security-eu orca-security-eu Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Orca Security Scan Summary

Status Check Issues by priority
Passed Passed Infrastructure as Code high 0   medium 0   low 0   info 0 View in Orca
Passed Passed SAST high 0   medium 0   low 0   info 0 View in Orca
Passed Passed Secrets high 0   medium 0   low 0   info 0 View in Orca
Passed Passed Vulnerabilities high 0   medium 0   low 0   info 0 View in Orca

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant