Skip to content

docs/admin: Remove stale version-gated notes for Sourcegraph < 6.0 - #1881

Closed
marcleblanc2 wants to merge 1 commit into
mainfrom
remove-stale-version-notes
Closed

docs/admin: Remove stale version-gated notes for Sourcegraph < 6.0#1881
marcleblanc2 wants to merge 1 commit into
mainfrom
remove-stale-version-notes

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Why

The docs still carried version-conditional notes for releases that are years out of support: "as of release 3.36", "supported in Sourcegraph 5.4 or more", "these will be removed in Sourcegraph 3.34", etc. The latest docs version is 7.7, the SLA supports N‑1 major (6.x), and archived docs sites go back to v6.7. So any note that gates behaviour on a Sourcegraph version below 6.0 no longer helps anyone on a supported version, and readers on older versions have the legacy docs sites.

What changed

Removed version gates, kept the feature described unconditionally (~40 spots across ~30 files): search contexts, rev:at.time, repo metadata, Batch Changes publishing/steps.mount/changesetTemplate.fork/schema versions, login form config, permission sync, Perforce, src serve-git, AWS CodeCommit, webhooks, telemetry allowlist, Code Insights (aggregations, retention, capture groups, language stats, repository scope, quickstart), Cody troubleshooting/Azure token, blobstore/minio, Docker Compose migration, Kubernetes custom resources, zoekt watchdog, SSH rsa-sha1, GitHub App badge.

Deleted whole sections that only described a long-finished transition:

  • Batch Changes FAQ: "From Campaigns to Batch Changes" (3.26 → 3.34)
  • Code Insights limitations: "[Released] available in 3.35+" list and "Older versions' limitations (3.30 or older)"
  • Code Insights quickstart: 3.24–3.31 prerequisites and the "enable the experimental feature flag" step (steps renumbered)
  • Code Insights data retention: "Accessing this feature prior to 4.5"
  • Code Insights common reasons: "[For versions pre-3.40] fork:no / archived:no" section
  • Cody FAQ: "Why were embeddings removed once my instance was upgraded to v5.3?" (the following FAQ entry covers the same ground)

Deleted pages that only documented a one-time migration on a 3.x/4.x version, with redirects added in src/data/redirects.ts and existing redirects retargeted so there are no chains:

Deleted page Redirects to
/self-hosted/how-to/blobstore-update-notes (4.2.1) /self-hosted/how-to/blobstore-debugging
/self-hosted/how-to/precise-code-intel-worker-crashloopbackoff (3.22) /code-navigation/troubleshooting
/self-hosted/how-to/dirty-database-pre-3-37 /self-hosted/how-to/dirty-database
/admin/how-to/lsif-scip-migration (4.5 → 4.6) /self-hosted/how-to/clear-codeintel-data
/admin/how-to/converting-version-contexts-to-search-contexts /code-search/working/search-contexts

Inbound links from self-hosted/index.mdx, self-hosted/how-to/index.mdx, admin/how-to/index.mdx, blobstore-debugging.mdx, dirty-database.mdx, clear-codeintel-data.mdx, code-search/features.mdx, and opengrok.mdx were updated. Two links in technical-changelog.mdx to the deleted pages were removed because dev/check-links.mjs does not follow redirects.

Upgrade docs: rewrote the Postgres 12 EOL notice in past tense (it still said the 5.10 release was "expected for November 25th, 2024"). Other upgrade-path docs (migrator, multi-version upgrades, Kustomize v4.5.0 migration, Postgres 12→16) deliberately keep their old-version references, since multi-version upgrades from v3.20+ are still supported.

Left alone on purpose

  • Notes about 6.x versions (model config 6.4/6.7, auto-edit 6.0+, batch change templates 6.6, Postgres 16 in 6.0, autoupgrade removal) — still inside the N‑1 support window. Re-run the search with [3-6] when 8.0 ships.
  • Code-host version numbers (GitHub Enterprise Server 3.3, Bitbucket Server 5.4/5.5) — not Sourcegraph versions.
  • site-config.mdx schema comments and #deprecation-notice anchor on the webhooks page — generated/linked from the product schema.
  • managing-access-tokens.mdx "tokens created before 5.3 do not expire" — still true for those tokens.
  • install-vscode.mdx "Sign In to Sourcegraph Instances v5.1 and above" — quotes a UI label.
  • fetch-sboms.mdx / verify-container-signatures.mdx "5.9.0 through 7.0.2852" — precise, still-relevant range.

How they were found

rg -n -i '(newer|older|later|earlier|prior|before|after|as of|since|starting|introduced|added|deprecated|removed|available|requires|support|from).{0,40}\bv?[3-5]\.[0-9]+(\.[0-9]+)?\b|\bv?[3-5]\.[0-9]+(\.[0-9]+)?\b.{0,40}(or (later|newer|more|above)|and (later|newer|above|up)|\+)' \
  docs --glob '!docs/technical-changelog.mdx' --glob '!docs/releases.mdx' --glob '!docs/**/updates/**'

Every hit was read by hand; the regex also catches code-host versions, rev:v4.5.0 query examples, and Alpine image tags, which were left unchanged.

Verification

  • npx tsc --noEmit — clean
  • pnpm build✅ No dead links found!, ✓ Compiled successfully, static pages generated

Amp threads

Sourcegraph 7.7 is the latest release and the SLA supports N-1 major
(6.x), with archived docs sites going back to v6.7. Notes that gate
behaviour on versions older than 6.0 ("as of 3.36", "supported in
5.4 or more", "will be removed in 3.34") no longer help anyone on
a supported version, so this removes them and states the current
behaviour unconditionally.

Also:
- Delete how-to pages that only described one-time migrations on
  3.x/4.x versions (blobstore update notes, precise-code-intel-worker
  CrashLoopBackOff, pre-3.37 dirty database, LSIF->SCIP migration,
  version contexts -> search contexts) and add redirects.
- Drop the Campaigns->Batch Changes rename section and the
  "older versions' limitations" sections from Code Insights docs.
- Rewrite the Postgres 12 EOL notice in past tense (it referenced
  "upcoming" releases from 2024).
- Remove two changelog links to deleted pages so check-links passes.

Upgrade-path docs (migrator, multi-version upgrades, Kustomize
migration, Postgres 12->16) keep their old-version references since
multi-version upgrades from v3.20+ are still supported.

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-01a07e69-d410-7318-bb5b-b229f69e1956
@vercel

vercel Bot commented Sep 8, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sourcegraph-docs Ready Ready Preview Sep 8, 2026 2:05am UTC

Request Review

@marcleblanc2 marcleblanc2 changed the title docs: remove stale version-gated notes for Sourcegraph < 6.0 docs: Remove stale version-gated notes for Sourcegraph < 6.0 Sep 9, 2026
@marcleblanc2 marcleblanc2 changed the title docs: Remove stale version-gated notes for Sourcegraph < 6.0 docs/admin: Remove stale version-gated notes for Sourcegraph < 6.0 Sep 9, 2026
@marcleblanc2

Copy link
Copy Markdown
Contributor Author

Moved to #1936 (branch renamed to marc/remove-stale-version-notes).

@marcleblanc2
marcleblanc2 deleted the remove-stale-version-notes branch September 11, 2026 17:27
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