Skip to content

docs: Update upgrade docs for supported 7.x and 8.x releases - #2106

Open
enriquegh wants to merge 5 commits into
mainfrom
enrique/update-upgrade-types
Open

enriquegh wants to merge 5 commits into
mainfrom
enrique/update-upgrade-types

Conversation

@enriquegh

Copy link
Copy Markdown
Contributor

Updates the Updating Sourcegraph docs to match current behavior in sourcegraph/sourcegraph and the N-1 support policy (current and previous major version: 7.x and 8.x).

Upgrade types and release schedule

  • Version format: the patch number is time-based, not sequential (for example v8.1.1335), per cmd/releaseregistry.
  • Release cadence: minor releases ship about monthly, patch releases ship as needed, and major releases have no fixed schedule.
  • Standard and multiversion rules match IsValidUpgrade in internal/version/upgradestore/upgrade.go. The frontend service and migrator up refuse to start when an upgrade crosses more than one minor version.
  • Examples now use only 7.x and 8.x versions.

One call for reviewers: the code also allows up from any 7.x minor straight to v8.0. The docs keep the stricter, safer policy that a standard upgrade to a new major starts from the final minor release (v7.7 → v8.0).

Removed (sunset before 7.0)

Per changelog/20260120_7-0-removals-deprecations.md, AMI deployments and the AMI install script are sunset. sourcegraph/deploy has no 7.x or 8.x tags; the last is v6.12.5040.

  • Machine images: index, AWS AMI, AWS one-click, and GCE pages, plus AWS Instance Sizing
  • k3s install script page
  • Automatic multi-version upgrades (removed in 6.12)
  • Upgrading Early Versions

Every removed path has a redirect, and existing /admin/... redirects now point to the new destinations. Links, the sidebar entry, and the "use our machine image" banners on the Docker Compose pages are removed.

Pre-7.0 guidance removed

  • PostgreSQL 12 and 5.9 → 6.0 warnings in the updates, Docker Compose, Kubernetes, and Helm upgrade docs
  • The 4.5 "Using MVU to Migrate to Kustomize" section
  • 3.x, 4.x, 5.x, and 6.0 examples in the migrator operations, downgrading, and upgrade pages, replaced with 7.x and 8.x examples. Migrator image tags now use {CURRENT_VERSION_NO_V}.

The sample migrator log output was written to match the real log format; it was not captured from a run.

Checks

  • check links --check-anchors --check-self-links against the merge-base baseline: no new dead links
  • dev/check-redirects.mjs against the baseline: no redirects broken
  • cspell, filenames, images, and tsc --noEmit pass
  • The local dev server renders the pages and the deleted URLs redirect

Amp thread: https://ampcode.com/threads/T-01a16aa0-9b7d-7793-970e-c03fa931154e

@vercel

vercel Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

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

1 Skipped Deployment
Project Deployment Actions Updated
sourcegraph-docs Ignored Ignored Preview Oct 26, 2026 9:23pm UTC

Request Review

@github-actions

Copy link
Copy Markdown
Contributor

@github-actions

This comment has been minimized.

enriquegh and others added 5 commits October 26, 2026 14:21
Describe the current version format, where the patch number is based on
the time since the minor release, the monthly planned release, and the
N-1 support policy.

Define standard and multiversion upgrades as the frontend and migrator
enforce them, and replace the 3.x to 5.x examples with 7.x and 8.x ones.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16aa0-9b7d-7793-970e-c03fa931154e
Sourcegraph 7.0 sunset AMI deployments and the AMI install script, and no
machine image has been published for 7.x or 8.x. Remove the machine image
(AWS AMI, AWS one-click, GCE), k3s install script, and AWS instance sizing
pages, along with their sidebar entry, links, and the banners recommending
machine images. Redirect the removed paths to the deployment docs.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16aa0-9b7d-7793-970e-c03fa931154e
Co-authored-by: Amp <amp@ampcode.com>
Upgrading Early Versions covers upgrades from before 4.0, and the
automatic multi-version upgrade feature was removed in 6.12. Both predate
the supported 7.x and 8.x releases. Remove the pages and their links, and
redirect them to the updates page.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16aa0-9b7d-7793-970e-c03fa931154e
Co-authored-by: Amp <amp@ampcode.com>
Remove the PostgreSQL 12 and 5.9 to 6.0 upgrade warnings, the 4.5
section on using a multi-version upgrade to migrate to Kustomize, and the
single-container and PostgreSQL 12 entries on the updates page.

Update the migrator, downgrade, Docker Compose, Kubernetes, and Helm
examples from 3.x to 6.0 versions to 7.x and 8.x, and use the latest
release for migrator image tags.

Amp-Thread-ID: https://ampcode.com/threads/T-01a16aa0-9b7d-7793-970e-c03fa931154e
Co-authored-by: Amp <amp@ampcode.com>
@enriquegh
enriquegh force-pushed the enrique/update-upgrade-types branch from 3775c19 to 0cf05fa Compare October 26, 2026 21:23
> </Callout>

<Callout type="warning">
If you are upgrading to [Sourcegraph 7.0.0](https://sourcegraph.com/changelog/releases/7.0) or later and your databases are still on PostgreSQL 12, you must first upgrade to a 6.x release (such as 6.11.x) to allow the automatic PostgreSQL 12 to 16 upgrade to complete. The entrypoint script that performs this upgrade has been removed in 7.0.0.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@enriquegh this information is needed somewhere, not all customers are on v6+ yet, hopefully this isn't the last place we're deleting this info from?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This notice should still be in pre 8.0 versions of the docs. Those (example) would still show this. The alternative would be to leave it or put in some consolidated place and hope we remember once all customers are in 7.0+

$ helm upgrade --install -n sourcegraph --set "migrator.args={upgrade,--from=7.5.0,--to=8.1.0}" sourcegraph-migrator sourcegraph/sourcegraph-migrator --version {CURRENT_VERSION_NO_V}
Release "sourcegraph-migrator" has been upgraded. Happy Helming!
NAME: sourcegraph-migrator
LAST DEPLOYED: Tue Mar 7 18:23:56 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit: worth changing the year :p


```bash
$ ~/deploy-sourcegraph-docker/docker-compose/ v4.5.1* docker-compose up -d migrator
$ ~/deploy-sourcegraph-docker/docker-compose/ v8.1.1335* docker-compose up -d migrator

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't understand this line, is this real output?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

tis not :D let me try and run this to get real logs

This branch was successfully deployed

1 active (outdated) deployment
Preview — 3775c195 Deployed Oct 26, 2026 by vercel[bot]
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.

2 participants