From f6fba045a8e9e4954151e8124aa58b92900c87c9 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 18 Feb 2026 22:11:45 +0100 Subject: [PATCH 1/3] docs(sdk): migrate releases process to playbook and standard Move develop-docs/sdk/processes/releases.mdx into the new playbook/standard structure: - New standard: release-versioning (version format, pre-release identifiers, build identifiers, release tooling, merge target, CalVer, multiple configs) - New playbook: setting-up-release-infrastructure (step-by-step setup guide) - Add redirect from old path - Replace uwsgi-dogstatsd-plugin examples with sentry-python Co-Authored-By: Claude --- .../setting-up-release-infrastructure.mdx | 108 +++++++ .../standards/release-versioning.mdx | 181 +++++++++++ develop-docs/sdk/processes/releases.mdx | 297 ------------------ redirects.js | 4 + 4 files changed, 293 insertions(+), 297 deletions(-) create mode 100644 develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx create mode 100644 develop-docs/sdk/getting-started/standards/release-versioning.mdx delete mode 100644 develop-docs/sdk/processes/releases.mdx diff --git a/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx new file mode 100644 index 0000000000000..18735f458e50a --- /dev/null +++ b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx @@ -0,0 +1,108 @@ +--- +title: Setting Up Release Infrastructure +--- + +## Steps + +#### 1. Create the initial tag + +A tag must exist for the first commit of the repository due to a [craft limitation](https://github.com/getsentry/craft/issues/342). Tag the first commit before any meaningful history so the first changelog includes useful context. + +```bash +git tag 0.0.0 "$(git log -1 --reverse --format=%h)" +git push origin --tags +``` + +#### 2. Set up CI for release branches + +Ensure the repository's CI responds to `release/**` branches and produces a named artifact. See [sentry-python's build workflow](https://github.com/getsentry/sentry-python/blob/master/.github/workflows/build.yml) for an example. + +#### 3. Configure craft (`.craft.yml`) + +Create a `.craft.yml` with targets for your package registry and GitHub releases: + +```yaml +minVersion: 0.28.1 +targets: + - name: pypi + - name: github +``` + +See the [Craft configuration docs](https://craft.sentry.dev/configuration/) for all available targets and options. + +#### 4. Add version bump script (`scripts/bump-version.sh`) + +Craft invokes this script when bumping the version. The script receives the old version as `$1` and the new version as `$2`: + +```bash +#!/usr/bin/env bash +set -euxo pipefail + +sed -i "s/^version =.*/version = $2/" setup.cfg +``` + +For a real-world example with multiple version locations, see [sentry-python's bump-version.sh](https://github.com/getsentry/sentry-python/blob/master/scripts/bump-version.sh). + +#### 5. Add release workflow (`.github/workflows/release.yml`) + +This workflow triggers releases from the GitHub UI. It uses `vars.SENTRY_RELEASE_BOT_CLIENT_ID` and `secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY` which are available to repositories in the `getsentry` org automatically. These are needed because [GitHub prevents `GITHUB_TOKEN` from triggering downstream workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows). + +```yaml +name: Release + +on: + workflow_dispatch: + inputs: + version: + description: Version to release + required: false + force: + description: Force a release even when there are release-blockers (optional) + required: false + +jobs: + release: + runs-on: ubuntu-latest + name: "Release a new version" + steps: + - name: Get auth token + id: token + uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0 + with: + app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }} + private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }} + - uses: actions/checkout@v6 + with: + token: ${{ steps.token.outputs.token }} + fetch-depth: 0 + - name: Prepare release + uses: getsentry/craft@v2 + env: + GITHUB_TOKEN: ${{ steps.token.outputs.token }} + with: + version: ${{ github.event.inputs.version }} + force: ${{ github.event.inputs.force }} +``` + +For full details on all available options including auto-versioning, changelog preview, merge targets, and multiple craft configs, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/). Repositories outside the `getsentry` org can use the simpler [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) which handles token management automatically via `secrets: inherit`. + +#### 6. Set repository permissions + +Give the `engineering` team write access via your repository's settings page: `https://github.com/getsentry/REPONAME_HERE/settings/access` + +#### 7. Create branch ruleset + +Download the [default ruleset template](/json/Default_ruleset.json). Import it at `https://github.com/getsentry/REPONAME_HERE/settings/rules` via **New ruleset** > **Import a ruleset**. You can adjust settings but do not remove the App in the Bypass List. + +#### 8. Cut your first release + +Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) which requires an approver to add a label before artifacts are published. + +For the ongoing release process after setup, see [Cutting a release](cutting-a-release). + +## Referenced Standards + +- [Version format](/sdk/getting-started/standards/release-versioning#version-format) +- [Release tooling](/sdk/getting-started/standards/release-versioning#release-tooling) +- Release gating criteria (wip) +- Rollback procedures (wip) diff --git a/develop-docs/sdk/getting-started/standards/release-versioning.mdx b/develop-docs/sdk/getting-started/standards/release-versioning.mdx new file mode 100644 index 0000000000000..8c4a8ff1cc4bc --- /dev/null +++ b/develop-docs/sdk/getting-started/standards/release-versioning.mdx @@ -0,0 +1,181 @@ +--- +title: Release and Versioning +sidebar_order: 99 +--- + +## Version format + +#### Rule + +All SDK versions follow [semantic versioning](https://semver.org/): + +``` +..(-)?(-)? +``` + +Major, minor, and patch are required. Pre-release and build identifiers are optional and can be combined. + +#### Enforcement + +- [Craft](https://github.com/getsentry/craft) validates version format at release time. + +#### Per-SDK override + + Format is universal. Language-specific conventions around semver (if applicable) are allowed. + +--- + +## Pre-release identifiers + +#### Rule + +Pre-release identifiers must be one of: `preview`, `pre`, `rc`, `dev`, `alpha`, `beta`, `unstable`, `a`, `b`. Arbitrary strings are not accepted. + +Pre-releases: +- Do not receive a `latest` tag in package registries +- Are not inserted into the internal release-registry (used by Sentry product, docs, and tooling) + +Valid examples: + +``` +1.0.0-preview +1.0.0-alpha.0 +1.0.0-beta.1 +1.0.0-rc.20 +``` + +Invalid (treated as stable): + +``` +1.0.0-foo +1.0.0-canary.0 +``` + +**Python post-releases:** Python has the concept of post-releases indicated by a numeric-only suffix (e.g. `1.0.0-1`). Since this doesn't match any valid pre-release identifier, craft treats post-releases as stable releases. + +#### Enforcement + +- Craft rejects unrecognized identifiers or treats them as stable releases. + +#### Per-SDK override + + + +--- + +## Build identifiers + +#### Rule + +Build identifiers can be appended for platform or architecture variants. When combined with pre-release identifiers, the pre-release must come first. + +Valid examples: + +``` +1.0.0+x86_64 +1.0.0-rc.1+x86_64 +``` + +Invalid: + +``` +1.0.0+rc.1+x86_64 +1.0.0+x86_64-beta.0 +``` + +#### Enforcement + +- Craft validates format at release time. + +#### Per-SDK override + + Usage depends on whether the SDK publishes platform-specific artifacts. + +--- + +## Release tooling + +#### Rule + +SDKs use [craft](https://github.com/getsentry/craft) for release preparation and [publish](https://github.com/getsentry/publish) for release approval. Every SDK repository must have: + +- `.craft.yml` — release configuration +- `scripts/bump-version.sh` — version bump script invoked by craft +- `.github/workflows/release.yml` — GitHub Actions workflow to trigger releases + +See the [setting up release infrastructure](/sdk/getting-started/playbooks/setting-up-release-infrastructure) playbook for setup instructions. + +#### Enforcement + +- Craft enforces configuration at release time. +- Publish requires approval label before artifacts are published. + +#### Per-SDK override + + Craft targets and bump-version logic are SDK-specific. Toolchain is universal. + +--- + +## Merge target + +#### Rule + +By default, releases are merged to the repository's default branch (usually `main`). To override this, pass the `merge_target` input in the release workflow: + +```yaml +- name: Prepare release + uses: getsentry/craft@v2 + env: + GITHUB_TOKEN: ${{ steps.token.outputs.token }} + with: + version: ${{ github.event.inputs.version }} + merge_target: ${{ github.event.inputs.merge_target }} +``` + +Add a corresponding `merge_target` input to the workflow's `workflow_dispatch.inputs` block. The same input is available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended). + +#### Enforcement + +- Craft handles branch targeting at release time. + +#### Per-SDK override + + Depends on branching strategy. + +--- + +## Multiple craft configs per repository + +#### Rule + +When a repository maintains multiple major versions (e.g. v7 and v8) with diverging publishing targets, it can opt into using the `.craft.yml` from the merge target branch instead of the default branch. + +**Release preparation:** Add `craft_config_from_merge_target: true` when calling `getsentry/craft` in the release workflow: + +```yaml +- name: Prepare release + uses: getsentry/craft@v2 + with: + craft_config_from_merge_target: true +``` + +This input is also available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended). + +**Publish configuration:** Register the branch in the `publish.yml` workflow in `getsentry/publish`: + +```yaml +- name: Set target repo checkout branch + if: | + fromJSON(steps.inputs.outputs.result).repo == 'sentry-javascript' && fromJSON(steps.inputs.outputs.result).merge_target == 'v7' +``` + +The registered branches **must be** protected in the target repository — disable direct pushing and require PR approvals before merging. + +#### Enforcement + +- Craft validates config from the specified branch. +- Publish workflow enforces branch protection requirement. + +#### Per-SDK override + + Only needed for repos maintaining multiple major versions. diff --git a/develop-docs/sdk/processes/releases.mdx b/develop-docs/sdk/processes/releases.mdx deleted file mode 100644 index 5146274ec1898..0000000000000 --- a/develop-docs/sdk/processes/releases.mdx +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: Releases -description: Learn how to release a new SDK or new versions of an SDK. -sidebar_order: 3 ---- - -This guide goes over the minimal setup needed to publish something via -[`publish`] and [`craft`]. This example will use a PyPI package. - -[`publish`]: https://github.com/getsentry/publish -[`craft`]: https://github.com/getsentry/craft - -## The First Release - -This guide assumes this thing has never been released before and has no -existing tags. If that's not the case feel free to skip this section! - -A tag must exist for the "beginning" of the repository due to [a limitation] -- -it is recommended to tag the first commit of the repository before any -meaningful history such that the first changelog includes useful context. - -```bash -git tag 0.0.0 "$(git log -1 --reverse --format=%h)" -git push origin --tags -``` - -[a limitation]: https://github.com/getsentry/craft/issues/342 - -## CI Requirements - -First we need to ensure your repository responds to `release/**` branches -and produces an artifact with the right name. - -For our example repository that's done using [`push: branches`] and an -[artifact instruction]. - -[`push: branches`]: https://github.com/getsentry/uwsgi-dogstatsd-plugin/blob/5057cba0104827c226094f153ffba7ade1a4331d/.github/workflows/build.yml#L5 -[artifact instruction]: https://github.com/getsentry/uwsgi-dogstatsd-plugin/blob/5057cba0104827c226094f153ffba7ade1a4331d/.github/workflows/build.yml#L81-L84 - -## Setting Up Craft - -### `.craft.yml` - -We're just interested in making a GitHub release and a PyPI release so our -`craft` configuration looks like: - -```yaml -minVersion: 0.28.1 -targets: - - name: pypi - - name: github -``` - -### `scripts/bump-version.sh` - -This script will be invoked by `craft` by default when bumping the version. - -Since we're specifying version in `setup.cfg` this is pretty easy to do with -`sed` (we're ignoring `$1` which contains the old version): - -```bash -#!/usr/bin/env bash -set -euxo pipefail - -sed -i "s/^version =.*/version = $2/" setup.cfg -``` - -Try the script out (but don't commit the changes): - -```console -$ ./scripts/bump-version.sh 0.0.0 1.0.0 -+ sed -i 's/^version =.*/version = 1.0.0/' setup.cfg -$ git diff | grep '^[-+]' ---- a/setup.cfg -+++ b/setup.cfg --version = 0.0.0 -+version = 1.0.0 -$ git checkout -- . -``` - -Nice! - -### `.github/workflows/release.yml` - -This file is used to trigger the release from the GitHub UI. - -You'll notice it uses `vars.SENTRY_RELEASE_BOT_CLIENT_ID` and `secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY` -- these should be -available to your repository automatically! These are needed because -[GitHub prevents `GITHUB_TOKEN` from triggering downstream workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows), -which is required for creating publish request issues in `getsentry/publish`. - -```yaml -name: Release - -on: - workflow_dispatch: - inputs: - version: - description: Version to release - required: false - force: - description: Force a release even when there are release-blockers (optional) - required: false - -jobs: - release: - runs-on: ubuntu-latest - name: "Release a new version" - steps: - - name: Get auth token - id: token - uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0 - with: - app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }} - private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }} - - uses: actions/checkout@v6 - with: - token: ${{ steps.token.outputs.token }} - fetch-depth: 0 - - name: Prepare release - uses: getsentry/craft@v2 - env: - GITHUB_TOKEN: ${{ steps.token.outputs.token }} - with: - version: ${{ github.event.inputs.version }} - force: ${{ github.event.inputs.force }} -``` - -For full details on all available options including auto-versioning, changelog preview, -and more, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/). -If your repository is outside the `getsentry` organization, you can use the simpler -[reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) -which handles token management automatically via `secrets: inherit`. - -### Commit + PR - -**Commit those three files and make a pull request.** - -## Setting Up Permissions - -Give the following teams access to your repository: - -- `engineering` -> `write` - -You can do this self-service via the settings page of your repository: -`https://github.com/getsentry/REPONAME_HERE/settings/access` - -## Create Ruleset for the Repo - -Download and save the [default ruleset template](/json/Default_ruleset.json) as a JSON file. - -Visit the ruleset setting page of your repository: `https://github.com/getsentry/REPONAME_HERE/settings/rules`, click on the green **New ruleset** button, choose **Import a ruleset**, and select the JSON file you just downloaded. You can tweak the ruleset settings, but please don't remove the App in the Bypass List. - -## Making Your First Release! - -Navigate to the actions tab of your repository, locate the release workflow, -and create the first release! I used `1.0.0` as the first version. - -This will create an [issue in `publish`] which you'll need an approver to -add a label to. - -[issue in `publish`]: https://github.com/getsentry/publish/issues - -## Calendar Versioning (CalVer) - -To enable calendar versioning for your SDK, add the following to your `.craft.yml`: - -```yaml -versioning: - policy: calver - calver: - format: "%y.%-m" # e.g., 24.12 for December 2024 - offset: 14 # Days to look back for date calculation (optional) -``` - -See the [Craft CalVer documentation](https://craft.sentry.dev/configuration/#calendar-versioning-calver) for more details. - -## Merge Target - -By default, all releases are merged to the default branch of your repository (usually `main`). To override this, pass the `merge_target` input in your release workflow: - -```yaml -- name: Prepare release - uses: getsentry/craft@v2 - env: - GITHUB_TOKEN: ${{ steps.token.outputs.token }} - with: - version: ${{ github.event.inputs.version }} - merge_target: ${{ github.event.inputs.merge_target }} -``` - -Make sure to also add a `merge_target` input to your workflow's `workflow_dispatch.inputs` block. -The same input is available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) as well. - -## Version name conventions - -To keep versioning consistent across SDKs, we generally follow [semantic versioning (semver)](https://semver.org/), with language- or platform-specific conventions around semver (if applicable). -Craft has some precautionary checks to ensure we only publish valid, semver-like versions. -Specifically, craft expects versions following this format: - -```txt -..(-)?(-)? -``` - -While the major, minor and patch version numbers are required, pre-release and build properties are optional but can also be combined. - -### Pre-releases (``) - -If you want to create a preview or pre-release of your SDK, you can append a pre-release identifier, as well as an optional incremental pre-release number to your version. -This will ensure that various craft publishing targets will treat the release as a pre-release, meaning for example that it will not get assigned a `latest` tag in package repositories. -Likewise, pre-releases will not be inserted into our internal release-registry, which is used by the Sentry product as well as our docs and other tools to query the latest or specific releases of our packages. - -Importantly, we have strict rules around which identifiers we accept as a pre-release, meaning the `` part of your version has to be one of the following: `preview|pre|rc|dev|alpha|beta|unstable|a|b`. -Therefore, we **do not accept** arbitrary strings as pre-release identifiers. Using any other identifiers will result in a release being considered stable instead. This means, it will get assigned a `latest` tag in package repositories and inserted into our release-registry. - -Examples: - -```txt -// valid -1.0.0-preview -1.0.0-alpha.0 -1.0.0-beta.1 -1.0.0-rc.20 -1.0.0-a - -// invalid or incorrectly treated -1.0.0-foo -1.0.0-canary.0 -``` - -#### Special Case: Post Releases - -Python has the concept of post releases, which craft handles implicitly. A post release is indicated by a `-\d+` suffix to the semver version, for example: `1.0.0-1`. -Given that we only consider certain identifiers as [valid pre-release identifiers](#pre-releases-prerelease), post releases are considered stable releases. - -### Build identifiers (``) - -In some cases, you can append a build identifier to your version, for example if you release the same package version for different platforms or architectures. -You can also combine build and pre-release identifiers but in this case, the pre-release identifier has to come first. - -Examples: - -```txt -// valid -1.0.0+x86_64 -1.0.0-rc.1+x86_64 - -// invalid or incorrectly treated -1.0.0+rc.1+x86_64 -1.0.0+x86_64-beta.0 -``` - -## [Optional] Using Multiple Craft Configs in a Repo - -In some cases, we need to maintain multiple or diverging publishing configs in a repository. -For example, when we have to maintain multiple major versions of a package we release (e.g. Sentry JavaScript SDK v7 and v8), where we added or removed artifacts or publishing targets. - -By default, our publishing process is configured to take the `craft.yml` config from the repo's default branch as the single source of truth for publishing. - -You can opt your repo into using the config from a specific merge target branch (can be configured when triggering the Prepare Release Action) in two steps: - -### 1. Release Preparation: - -Add `craft_config_from_merge_target: true` when calling `getsentry/craft` in your repo's release workflow: - -```yml -# ... -jobs: - release: - runs-on: ubuntu-latest - name: "Release a new version" - steps: - # ... - - name: Prepare release - uses: getsentry/craft@v2 - with: - # ... - craft_config_from_merge_target: true -``` - -This input is also available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended). - -### 2. Publish Configuration - -Add the branch(es) you want to take the config from to the `publish.yml` workflow in `getsentry/publish`: - -```yml -# ... -- name: Set target repo checkout branch - if: | - fromJSON(steps.inputs.outputs.result).repo == 'sentry-javascript' && fromJSON(steps.inputs.outputs.result).merge_target == 'v7' -``` - -Note: The branch(es) registered in this step **MUST BE** protected in the target repository. -Disable direct pushing to the branch and require approvals for PRs before they can be merged. - -Good job! Now you can let your craft configs diverge across the different merge target branches and the publishing process will pick up the correct config based on the branch you're setting as a merge target. diff --git a/redirects.js b/redirects.js index 3cdbb29814e61..fb5ecc6603a7f 100644 --- a/redirects.js +++ b/redirects.js @@ -173,6 +173,10 @@ const developerDocsRedirects = [ source: '/sdk/development-process/:path*', destination: '/sdk/processes/:path*', }, + { + source: '/sdk/processes/releases/', + destination: '/sdk/getting-started/playbooks/setting-up-release-infrastructure/', + }, { source: '/application/ab-testing/', destination: '/backend/ab-testing/', From 638c13d1fc3efa8df09f764daaeaa934ebad8531 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Thu, 19 Feb 2026 11:34:28 +0100 Subject: [PATCH 2/3] Apply suggestions for title casing Co-authored-by: Alex Krawiec --- .../setting-up-release-infrastructure.mdx | 16 +++++------ .../standards/release-versioning.mdx | 28 +++++++++---------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx index 18735f458e50a..ac9f38e8744eb 100644 --- a/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx +++ b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx @@ -4,7 +4,7 @@ title: Setting Up Release Infrastructure ## Steps -#### 1. Create the initial tag +#### 1. Create the Initial Tag A tag must exist for the first commit of the repository due to a [craft limitation](https://github.com/getsentry/craft/issues/342). Tag the first commit before any meaningful history so the first changelog includes useful context. @@ -13,11 +13,11 @@ git tag 0.0.0 "$(git log -1 --reverse --format=%h)" git push origin --tags ``` -#### 2. Set up CI for release branches +#### 2. Set Up CI for Release Branches Ensure the repository's CI responds to `release/**` branches and produces a named artifact. See [sentry-python's build workflow](https://github.com/getsentry/sentry-python/blob/master/.github/workflows/build.yml) for an example. -#### 3. Configure craft (`.craft.yml`) +#### 3. Configure Craft (`.craft.yml`) Create a `.craft.yml` with targets for your package registry and GitHub releases: @@ -30,7 +30,7 @@ targets: See the [Craft configuration docs](https://craft.sentry.dev/configuration/) for all available targets and options. -#### 4. Add version bump script (`scripts/bump-version.sh`) +#### 4. Add Version Bump Script (`scripts/bump-version.sh`) Craft invokes this script when bumping the version. The script receives the old version as `$1` and the new version as `$2`: @@ -43,7 +43,7 @@ sed -i "s/^version =.*/version = $2/" setup.cfg For a real-world example with multiple version locations, see [sentry-python's bump-version.sh](https://github.com/getsentry/sentry-python/blob/master/scripts/bump-version.sh). -#### 5. Add release workflow (`.github/workflows/release.yml`) +#### 5. Add Release Workflow (`.github/workflows/release.yml`) This workflow triggers releases from the GitHub UI. It uses `vars.SENTRY_RELEASE_BOT_CLIENT_ID` and `secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY` which are available to repositories in the `getsentry` org automatically. These are needed because [GitHub prevents `GITHUB_TOKEN` from triggering downstream workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows). @@ -86,15 +86,15 @@ jobs: For full details on all available options including auto-versioning, changelog preview, merge targets, and multiple craft configs, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/). Repositories outside the `getsentry` org can use the simpler [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) which handles token management automatically via `secrets: inherit`. -#### 6. Set repository permissions +#### 6. Set Repository Permissions Give the `engineering` team write access via your repository's settings page: `https://github.com/getsentry/REPONAME_HERE/settings/access` -#### 7. Create branch ruleset +#### 7. Create Branch Ruleset Download the [default ruleset template](/json/Default_ruleset.json). Import it at `https://github.com/getsentry/REPONAME_HERE/settings/rules` via **New ruleset** > **Import a ruleset**. You can adjust settings but do not remove the App in the Bypass List. -#### 8. Cut your first release +#### 8. Cut Your First Release Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) which requires an approver to add a label before artifacts are published. diff --git a/develop-docs/sdk/getting-started/standards/release-versioning.mdx b/develop-docs/sdk/getting-started/standards/release-versioning.mdx index 8c4a8ff1cc4bc..5aa4f2c390026 100644 --- a/develop-docs/sdk/getting-started/standards/release-versioning.mdx +++ b/develop-docs/sdk/getting-started/standards/release-versioning.mdx @@ -3,11 +3,11 @@ title: Release and Versioning sidebar_order: 99 --- -## Version format +## Version Format #### Rule -All SDK versions follow [semantic versioning](https://semver.org/): +All SDK versions follow [semantic versioning (SemVer)](https://semver.org/): ``` ..(-)?(-)? @@ -19,13 +19,13 @@ Major, minor, and patch are required. Pre-release and build identifiers are opti - [Craft](https://github.com/getsentry/craft) validates version format at release time. -#### Per-SDK override +#### Per-SDK Override - Format is universal. Language-specific conventions around semver (if applicable) are allowed. + Format is universal. Language-specific conventions around SemVer (if applicable) are allowed. --- -## Pre-release identifiers +## Pre-Release Identifiers #### Rule @@ -57,13 +57,13 @@ Invalid (treated as stable): - Craft rejects unrecognized identifiers or treats them as stable releases. -#### Per-SDK override +#### Per-SDK Override --- -## Build identifiers +## Build Identifiers #### Rule @@ -87,13 +87,13 @@ Invalid: - Craft validates format at release time. -#### Per-SDK override +#### Per-SDK Override Usage depends on whether the SDK publishes platform-specific artifacts. --- -## Release tooling +## Release Tooling #### Rule @@ -110,13 +110,13 @@ See the [setting up release infrastructure](/sdk/getting-started/playbooks/setti - Craft enforces configuration at release time. - Publish requires approval label before artifacts are published. -#### Per-SDK override +#### Per-SDK Override Craft targets and bump-version logic are SDK-specific. Toolchain is universal. --- -## Merge target +## Merge Target #### Rule @@ -138,13 +138,13 @@ Add a corresponding `merge_target` input to the workflow's `workflow_dispatch.in - Craft handles branch targeting at release time. -#### Per-SDK override +#### Per-SDK Override Depends on branching strategy. --- -## Multiple craft configs per repository +## Multiple Craft Configs Per Repository #### Rule @@ -176,6 +176,6 @@ The registered branches **must be** protected in the target repository — disab - Craft validates config from the specified branch. - Publish workflow enforces branch protection requirement. -#### Per-SDK override +#### Per-SDK Override Only needed for repos maintaining multiple major versions. From dfc45ed4472fac1c33a0e200653d148d0fb1865d Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Thu, 19 Feb 2026 11:41:46 +0100 Subject: [PATCH 3/3] fix(sdk): replace broken link to cutting-a-release with wip marker The cutting-a-release page doesn't exist yet, so the link would 404. Co-Authored-By: Claude --- .../playbooks/setting-up-release-infrastructure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx index ac9f38e8744eb..8fc59630c245b 100644 --- a/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx +++ b/develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx @@ -98,7 +98,7 @@ Download the [default ruleset template](/json/Default_ruleset.json). Import it a Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) which requires an approver to add a label before artifacts are published. -For the ongoing release process after setup, see [Cutting a release](cutting-a-release). +For the ongoing release process after setup, see "Cutting a release" (wip). ## Referenced Standards