docs(self-hosted): remove invalid mentions of copying .env.custom and various minor improvements

[aldy505]

DESCRIBE YOUR PR

Changing some copy, as I hope it will make first timers understand our release cadence & how often they should upgrade, better.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

• Urgent deadline (GA date, etc.): YYYY-MM-DD
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

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

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 4, 2026 1:51pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-docs	Ignored		Oct 4, 2026 1:51pm UTC

[cursor]

The change only edits copy on one upgrade guide. The new wording has no metric.
The plan watches server errors on that guide, client errors, and nearby self-hosted page traffic.
An issue escalates when server errors appear or client errors rise above the measured hourly band.

Services: develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

The self-hosted upgrade guide now tells readers to upgrade every month.
It no longer tells readers to copy new variables from .env into .env.custom before install.
Nightly builds now list Launchpad. They also warn that missing config can break a nightly.
The change is live after a develop-docs deploy to production.
The public URL is https://develop.sentry.dev/self-hosted/releases/.

Risk

Bad copy can send operators through a wrong upgrade path. Site metrics cannot show that harm.
A render failure on this MDX page can return a server error on the catch-all route.
Nearby self-hosted pages share that route. A route failure can hide those pages too.

Intended effect

This is a documentation copy edit. No metric shows the new sentences on the page.
Leave this axis unknown. confirmed and absent cannot be filled from telemetry.
Do not use a repository file check as a substitute.

Regression watch

A failed render shows first as a 5xx on self-hosted URLs or as a drop in those page loads.
Client errors can rise if a heading or link on the page throws in the browser.
Client traces use a 0.3 sample rate. Span counts below are sampled.
Hourly client errors already include known noise. Do not treat a single tagName, h6, Outlook rejection, Algolia Insights 401, or reCAPTCHA timeout as a new regression.

Signal	Baseline	Window	Rule	Source
Self-hosted 5xx rate	0% (0 of 180 sampled page spans)	2026-10-03T13:50:36Z to 2026-10-04T13:50:36Z	Hold at 0%. Any 5xx is a regression.	Sentry spans, project develop-docs. Query: environment:production http.status_code:>=500 http.url:*self-hosted*
Catch-all 5xx count	0	2026-10-03T13:50:36Z to 2026-10-04T13:50:36Z	Hold at 0. Any 5xx on /:path*? is a regression.	Sentry spans, project develop-docs. Query: environment:production transaction:/:path*? http.status_code:>=500
Production client errors	0-4 events per hour. 15 events in 24h. Peak 4 at 2026-10-04 09:00 UTC	2026-10-03T13:50:36Z to 2026-10-04T13:50:36Z	Hold in 0-4 events per hour. Escalate if several hours exceed 4.	Sentry errors, project develop-docs. Query: environment:production
Self-hosted family sampled page loads	180 spans per 24h	2026-10-03T13:50:36Z to 2026-10-04T13:50:36Z	Hold near 180. Escalate if volume falls toward 0 with 5xx. Weekend traffic may stay near this band.	Sentry spans, project develop-docs. Query: environment:production AND (span.op:pageload OR span.op:http.server) AND http.url:*develop.sentry.dev/self-hosted*

The changed page had 13 sampled loads in that window at https://develop.sentry.dev/self-hosted/releases/.
Transaction name is /:path*?, not the URL path.
Escalate if that page count falls to 0 while the family load count still holds.

Not observable

The live HTML of the new copy is not in Sentry.
Whether operators upgrade monthly is not in Sentry.
Whether dropping the .env.custom copy step is correct for installers is not in Sentry.
Page-load p95 on the changed URL was 3148.7ms on 13 sampled spans. That sample is too small for a hold band.

[sentry]

Bug: Removing the instruction to update .env.custom from the upgrade guide may cause users to miss new environment variables, leading to misconfiguration after an upgrade.
_{Severity: MEDIUM}

Suggested Fix

Restore the guidance in releases.mdx that instructs users with a .env.custom file to check for and copy new environment variables from the .env file during an upgrade. Alternatively, add a cross-reference link from the upgrade page to the configuration documentation that details this process.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: develop-docs/self-hosted/releases.mdx#L40-L41

Potential issue: The removal of guidance from `releases.mdx` regarding the `.env.custom`
file creates a risk of misconfiguration for users during an upgrade. When a
`.env.custom` file exists, the standard `.env` file is ignored. New versions of Sentry
may introduce new environment variables in the `.env` file. Without the explicit
instruction in the upgrade guide, users with a `.env.custom` setup are likely to miss
these new variables, which can lead to incorrect behavior or broken features after the
upgrade is complete.

_{Did we get this right? 👍 / 👎 to inform future reviews.}