diff --git a/src/components/sidebar.tsx b/src/components/sidebar.tsx
index 2787746f2b..02bddf9ff0 100644
--- a/src/components/sidebar.tsx
+++ b/src/components/sidebar.tsx
@@ -197,6 +197,7 @@ export default () => {
Exception Interface
Message Interface
+ Release Detection
Request Interface
SDK Interface
diff --git a/src/docs/sdk/event-payloads/index.mdx b/src/docs/sdk/event-payloads/index.mdx
index c6efe72121..c07625c2fc 100644
--- a/src/docs/sdk/event-payloads/index.mdx
+++ b/src/docs/sdk/event-payloads/index.mdx
@@ -159,6 +159,10 @@ For example, in a web app, this might be the route name.
This value can be the git SHA for the given project, or a product identifier
with a semantic version (suggested format `my-project-name@1.0.0`).
+It is suggested to attempt to automatically detect the release environment,
+and set it automatically for the user.
+Further information about platform specific attempts here.
+
```json
{
"release": "my-project-name@1.0.0"
diff --git a/src/docs/sdk/event-payloads/release.mdx b/src/docs/sdk/event-payloads/release.mdx
new file mode 100644
index 0000000000..ce9880ab4c
--- /dev/null
+++ b/src/docs/sdk/event-payloads/release.mdx
@@ -0,0 +1,45 @@
+---
+title: Detect Release Automatically
+---
+
+
+ Should we call special attention to something to encourage best practices and prevent and bad DX?
+
+
+
+## Release
+
+
+```json
+{
+ "release": "my-project-name@1.0.0"
+}
+```
+
+```json
+{
+ "release": "721e41770371db95eee98ca2707686226b993eda"
+}
+```
+
+## SDK Examples
+
+| Source | Description |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Python SDK | -`SENTRY_RELEASE` env variable
- Output of git rev-parse HEAD |
+| Rust SDK | -`SENTRY_RELEASE` env if nothing was explicitly sent. & example snippets include release: sentry::release_name!() |
+| Browser SDK | 1. the `SENTRY_RELEASE` global var injected by bundlers (like webpack plugin): link
2. and then falls back to undefined |
+| Node SDK | 1. release parameter
2. SENTRY_RELEASE env var
3. SENTRY_RELEASE.id global var
- variety of `env variables`
4. and then falls back to undefined |
+| Dart/Flutter | - `SENTRY_RELEASE` environment variable- `-dart-define=SENTRY_RELEASE` dart define variable
- SDK init `options.release`
By default, it uses the `appId@appVersion+buildNumber` whenever possible/available. |
+| Java | - SDK init options
- sentry.properties file
- defaults to git `commit_id` for spring-boot |
+| Android(Java) | - SDK init options
- AndroidManifest.xml `io.sentry.release` metadata
- By default, it uses the `appId@appVersion+buildNumber` |
+| Cocoa/Apple | The SDK sets the default, which is `CFBundleIdentifier@CFBundleShortVersionString+CFBundleVersion`, on the init of the Options. An example is `io.sentry.sample.iOS-Swift@7.31.2+1`|
+| React Native | - SDK init options (overrides platform defaults)
iOS:
- platform default
Android:
- platform default
- `SENTRY_RELEASE` environment variable only source maps upload |
+| Unity | SDK defaults to `$"{productName}@{application.Version}"+{application.BuildGUID}"` on initializing `SentryUnityOptions` |
+| Capacitor | Same rules as Browser, otherwise fetch from the native SDK
iOS
- id as `CFBundleIdentifier`
- version as `CFBundleShortVersionString`
- build as `CFBundleVersion`
Android:
- id as `packageName`
- version as `versionName`
- build as `versionCode` |
+| Cordova | gets from `SENTRY_RELEASE`, or it's set by Sentry CLI from the command `sentry-cli releases propose-version` during build (the hash from the last commit) |
+| Xamarin | `PackageName@VersionString+BuildString`
`PackageName`: the application package name for Android/iOS and the application GUID for UWP.
`VersionString`: `versionName` on Android, `CFBundleVersion` on iOS, Assembly version on UWP.
`BuildString`: `versionCode` on Android, `CFBundleShortVersionString` on iOS. |
+| PHP | in order of precedence:
PHP/Laravel/Symfony
- `options.release`
- `SENTRY_RELEASE` |
+| Ruby | in order of precedence:
- `config.release`
- `ENV[’SENTRY_RELEASE’]`
- `git rev-parse —short HEAD` if .git present
- capistrano `REVISION` file or from `revisions.log`
- `ENV['HEROKU_SLUG_COMMIT']` if on heroku
- nil otherwise |
+| Golang | in order of precedence:
- `options.Release`
- various env vars
`"SENTRY_RELEASE"`
`"HEROKU_SLUG_COMMIT"`
`"SOURCE_VERSION"`
`"CODEBUILD_RESOLVED_SOURCE_VERSION"`
`"CIRCLE_SHA1"`
`"GAE_DEPLOYMENT_ID"`
`"GITHUB_SHA"`
`"COMMIT_REF"`
`"VERCEL_GIT_COMMIT_SHA"`
`"ZEIT_GITHUB_COMMIT_SHA"`
`"ZEIT_GITLAB_COMMIT_SHA"`
`"ZEIT_BITBUCKET_COMMIT_SHA"`
- `git describe --long --always --dirty` |
+| .NET | In order of precedence:
- The `release` configuration option if set
- The `SENTRY_RELEASE` env var if set
- `"{AssemblyName}@{AssemblyInformationalVersion}"` based on the entry assembly, when an informational version attribute is present (commonly set by csproj `` tag in modern .NET)
- `"{AssemblyName}@{AssemblyVersion}"` based on the entry assembly, using the full assembly version (usually in older .NET Framework)
Varies slightly for mobile.
On .NET Android:
- The `release` configuration option if set
- `"{PackageName}@{PackageVersion}+{PackageVersionCode}"` from the Android package. (Should matche `appId@appVersion+buildNumber` from the Android SDK.)
On .NET for iOS/MacCatalyst:
- The Release configuration option if set
- `"{CFBundleIdentifier}@{CFBundleShortVersionString}+{CFBundleVersion}"` which matches the iOS SDK. |