privacytracker follows semver: the <MAJOR>.<MINOR>.<PATCH> of the app matches the version this docs site documents. The shipped version today is 0.1.2, and the docs site is single-version — it always reflects main. Nothing has been archived yet. This page is the recipe for the first time that changes. The v1.1 / v1.2 version numbers in the examples below are illustrative placeholders for previous minor and new minor; substitute the real pair when you cut one. This page is for the docs maintainer cutting a new version, not the casual contributor. Day-to-day editing flows through CONTRIBUTING.md.

​
Versioning strategy

Three rules:
  1. One docs version per app major.minor. Major version 2.x and minor 1.2 each get their own version slot. Patch versions (1.1.1, 1.1.2, …) ride along on the parent minor’s docs — patches don’t change docs by definition.
  2. The default version is always the latest. Visitors land on the most-recent version unless they pick an older one from the version switcher.
  3. Old versions are read-only. Once v1.1 is archived because v1.2 shipped, we don’t backport docs fixes to v1.1 unless the fix addresses behaviour specific to the v1.1 codepath. Typos and broken links on archived versions stay there.

​
When to cut a new version

Cut a new docs version when:
  • The app ships a new minor (v1.1 → v1.2) and something in the docs is now wrong for the previous minor. If the new minor only adds features without breaking previous behaviour, cutting a new version is optional — current docs cover both.
  • A breaking config change lands. If AUDITOR_ADMIN_TOKEN semantics change, the previous version’s docs need to stay accurate for the people on the previous release.
  • A breaking API change lands. Same reason — integrators on the old API need the old reference.
Don’t cut a new version for:
  • Patch releases.
  • Doc-only improvements.
  • Changes that are strictly additive (a new feature, a new endpoint).

​
Adding a version in Mintlify

Mintlify supports per-version navigation via navigation.versions. The current docs.json uses the simpler navigation.tabs shape — adding a second version means migrating into the versions array.
1

Create the archive folder

Copy every page that should be frozen for the previous version into a top-level folder named after that version:
Inside v1.1/, leave the content alone — it’s a snapshot.
2

Migrate docs.json into the versions shape

Mintlify renders a version dropdown in the topbar once navigation.versions has more than one entry.
3

Add a Note callout to archived pages

At the top of each v1.1/*.mdx page, add:
Use a small script rather than editing each file by hand:
4

Run npm run check

The smoke check follows links across all versions. If any cross-version reference is broken, fix it now — old versions linking to new content is fine, new versions linking back into archived versions is usually a bug.
5

Update CONTRIBUTING.md

Add a Don’t edit v1.1/ line to the contributing guide so future contributors don’t try to update archived pages.

​
Removing an old version

We don’t remove old versions — visitors with bookmarks to /v1.1/configuration should still land on real content, even if it’s stale. Disk cost is negligible (a few MB per version). The exception is if a version is misleading in a way that hurts users — e.g., it documents a security pattern that’s since been found insecure. In that case:
  1. Add a <Warning> to every page in the affected version pointing at the current version.
  2. Update the version’s changelog.mdx to call out the issue.
  3. Don’t delete; deletion breaks search-engine results that lead to the stale page.

​
URL shape

Default version: /configuration, /develop/architecture, etc. Archived version: /v1.1/configuration, /v1.1/develop/architecture. The version dropdown in the topbar handles switching automatically — readers don’t have to remember the URL prefix.

​
Search across versions

Mintlify’s built-in search indexes only the active version by default. To index all versions (so a search for AUDITOR_ADMIN_TOKEN finds matches in v1.1 and v1.2), add to docs.json:
Trade-off: a single search result list mixing versions can confuse visitors who don’t realise they’re on an old page. Default-version-only search is usually the right call.

​
Sync-changelog implications

The changelog automation writes to changelog.mdx (the default-version path). After cutting v1.1 as an archived version:
  • Archived v1.1/changelog.mdx should be frozen in time — don’t let the sync workflow overwrite it. The workflow already only writes to the top-level path, so this is automatic.
  • The current changelog.mdx continues to receive new release entries.
If a maintainer ever needs to back-port a changelog correction to an archived version, do it manually — the automation is intentionally one-way.