docs(releases): De-duplicate release naming docs, and centralize in /product/releases/naming-releases/ #14748

ryan953 · 2025-08-27T22:13:32Z

I noticed we had a lot of duplicate pages with the same docs related to release names.

The goal of this PR is to:

Move Release Name related content out of platform docs, and into a central place. It's not platform specific knowledge really
De-duplicate whatever is left over in the platform docs, so it's easier to maintain links to the central docs going forward.

The new central page is available at: /product/releases/naming-releases/

this content was taken from other places and re-worked a little.

Some existing pages are now more streamlined and will link to the new central location:

/cli/releases/
/platforms/javascript/configuration/releases/ (19 platform pages with the exact same content)

New page	CLI Releases	Platform pages

…product/releases/naming-releases/

vercel · 2025-08-27T22:13:39Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
sentry-docs	Ready	Preview	Comment	Sep 26, 2025 5:57pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Ignored	Preview		Sep 26, 2025 5:57pm

codecov · 2025-08-27T22:15:09Z

Bundle Report

Changes will increase total bundle size by 17.05kB (0.07%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-client-array-push	9.9MB	-290 bytes (-0.0%) ⬇️
sentry-docs-server-cjs	12.51MB	17.34kB (0.14%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.78MB	-0.0%
`../instrumentation.js`	-3 bytes	1.1MB	-0.0%
`9523.js`	-3 bytes	1.08MB	-0.0%
`../app/[[...path]]/page.js.nft.json`	5.78kB	772.65kB	0.75%
`../app/platform-redirect/page.js.nft.json`	5.78kB	772.56kB	0.75%
`../app/sitemap.xml/route.js.nft.json`	5.78kB	770.04kB	0.76%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`static/chunks/pages/_app-*.js`	-3 bytes	882.71kB	-0.0%
`static/chunks/8321-*.js`	-3 bytes	425.87kB	-0.0%
*`static/media/7c239973d8aef789-.woff2`** (New)	32.56kB	32.56kB	100.0% 🚀
*`static/media/32c80fb7588b7a2e-.woff2`** (New)	32.48kB	32.48kB	100.0% 🚀
*`static/media/a5d9f2ead0568494-.woff2`** (New)	21.08kB	21.08kB	100.0% 🚀
*`static/media/5b25d60b4670300e-.woff2`** (New)	19.29kB	19.29kB	100.0% 🚀
*`static/media/fc5b975a09123a00-.woff2`** (New)	9.75kB	9.75kB	100.0% 🚀
*`static/media/99e31c27a1524300-.woff2`** (New)	9.35kB	9.35kB	100.0% 🚀
`server/middleware-*.js`	5.55kB	6.55kB	555.3% ⚠️
`server/middleware-*.js`	-5.55kB	1.0kB	-84.74%
`static/DRwa1MOLQsvgm6_P9yx1H/_buildManifest.js` (New)	684 bytes	684 bytes	100.0% 🚀
`static/DRwa1MOLQsvgm6_P9yx1H/_ssgManifest.js` (New)	77 bytes	77 bytes	100.0% 🚀
~~*`static/media/4fca85807f6c09f6-.woff2`*~~ (Deleted)*	-32.6kB	0 bytes	-100.0% 🗑️
~~*`static/media/d695df15e3ff125c-.woff2`*~~ (Deleted)*	-32.58kB	0 bytes	-100.0% 🗑️
~~*`static/media/acdf4f392b58827a-.woff2`*~~ (Deleted)*	-21.13kB	0 bytes	-100.0% 🗑️
~~*`static/media/501d9eeee6e2b0cc-.woff2`*~~ (Deleted)*	-19.41kB	0 bytes	-100.0% 🗑️
~~*`static/media/a72efd2c2476ebb2-.woff2`*~~ (Deleted)*	-9.7kB	0 bytes	-100.0% 🗑️
~~*`static/media/9d7436bc73437f75-.woff2`*~~ (Deleted)*	-9.36kB	0 bytes	-100.0% 🗑️
~~*`static/qFp-.js`*~~ (Deleted)*	-684 bytes	0 bytes	-100.0% 🗑️
~~*`static/qFp-.js`*~~ (Deleted)*	-77 bytes	0 bytes	-100.0% 🗑️

michellewzhang · 2025-09-02T17:29:46Z

docs/cli/releases.mdx

-The value can be arbitrary, but for certain platforms, recommendations exist:
-
- for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error.
- if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`.


this part is not included in the new snippet. is it important to include there?

i was thinking that it's ok to bury it under "There are some release name restrictions and conventions to be aware of. Learn more about Naming Releases." but i can add it back if that link's easy to miss and the content is more useful to be here up-front.

I think it's okay to shorten this section, but I would suggest adding a little bit more info in the linked area. I'll add a comment with a suggestion there.

michellewzhang · 2025-09-02T17:29:55Z

docs/cli/releases.mdx

-
- for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error.
- if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`.
- if you tag releases we recommend using the release tag prefixed with a product or package name (for example, `my-project-name@2.3.12`).


same with this

docs/cli/releases.mdx

docs/product/releases/naming-releases.mdx

includes/bind-release-version.mdx

Co-authored-by: Michelle Zhang <56095982+michellewzhang@users.noreply.github.com>

jas-kas

Nice clean up! A lot less repeated content now 😅

Since we're auditing all these release doc files, the platform docs all being named "Releases & Health" is odd. Shouldn't it be "Release Health"? Or if anything, I'd make it "Releases".

Since this is under the "Configuration" nav item, "Releases" make sense as that is the entity you're configuring. Maybe you can add this bulk change to the PR 👼

docs/product/releases/naming-releases.mdx

includes/bind-release-version.mdx

jas-kas · 2025-09-08T15:09:27Z

includes/bind-release-version.mdx

+
+There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/).
+
+Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.


This releases link just brings users back to the same exact page they are already on, with the added step of having to select a platform. 🤔 What information do you want to point to here?

these links go out to different pages

the platform specific page talks about sessions and has platform specific snippets.

jas-kas · 2025-09-08T15:09:51Z

includes/bind-release-version.mdx

+
+There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/).
+
+Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.


Suggested change

Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.

Releases can also be auto-created by different systems—for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.

docs/cli/releases.mdx

docs/platforms/android/configuration/releases.mdx

includes/bind-release-version.mdx

sfanahata

Love this change! Thanks for giving the docs some includes goodness. I noted that I think it's still valuable to add the top level info about naming restrictions to the includes file, but otherwise, just added a couple of nits. Looks great. <3

Co-authored-by: Jasmin <77064737+jas-kas@users.noreply.github.com> Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

docs(releases): De-duplicate release naming docs, and centralize in /…

15b6cf1

…product/releases/naming-releases/

codeowner-assignment bot requested a review from a team August 27, 2025 22:13

ryan953 requested review from a team and removed request for a team August 27, 2025 22:13

codeowner-assignment bot requested review from a team and removed request for a team August 27, 2025 22:13

ryan953 requested review from a team and chargome August 27, 2025 22:14

codeowner-assignment bot requested review from a team and removed request for a team and chargome August 27, 2025 22:14

vercel bot deployed to Preview – sentry-docs August 27, 2025 22:29 View deployment

michellewzhang reviewed Sep 2, 2025

View reviewed changes

ryan953 and others added 2 commits September 2, 2025 13:09

Apply suggestions from code review

4178efd

Co-authored-by: Michelle Zhang <56095982+michellewzhang@users.noreply.github.com>

Apply suggestions from code review

3831ccb

Co-authored-by: Michelle Zhang <56095982+michellewzhang@users.noreply.github.com>

vercel bot deployed to Preview – sentry-docs September 2, 2025 20:59 View deployment

jas-kas approved these changes Sep 8, 2025

View reviewed changes

sfanahata self-requested a review September 9, 2025 21:30

sfanahata reviewed Sep 9, 2025

View reviewed changes

docs/platforms/android/configuration/releases.mdx Show resolved Hide resolved

sfanahata reviewed Sep 9, 2025

View reviewed changes

includes/bind-release-version.mdx Outdated Show resolved Hide resolved

sfanahata approved these changes Sep 9, 2025

View reviewed changes

Apply suggestions from code review

e5874e9

Co-authored-by: Jasmin <77064737+jas-kas@users.noreply.github.com> Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

ryan953 enabled auto-merge (squash) September 26, 2025 17:52

vercel bot deployed to Preview – sentry-docs September 26, 2025 17:57 View deployment

ryan953 merged commit dee6ac5 into master Sep 26, 2025
13 checks passed

ryan953 deleted the ryan953/release-naming-docs branch September 26, 2025 17:57

github-actions bot locked and limited conversation to collaborators Oct 12, 2025


		There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/).

		Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation.

Uh oh!

docs(releases): De-duplicate release naming docs, and centralize in /product/releases/naming-releases/ #14748

docs(releases): De-duplicate release naming docs, and centralize in /product/releases/naming-releases/ #14748

Uh oh!

Conversation

ryan953 commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Uh oh!

michellewzhang Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

ryan953 Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

sfanahata Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

michellewzhang Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jas-kas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jas-kas Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

ryan953 Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

jas-kas Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sfanahata left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ryan953 commented Aug 27, 2025 •

edited

Loading

vercel bot commented Aug 27, 2025 •

edited

Loading

codecov bot commented Aug 27, 2025 •

edited

Loading