Skip to content

Releasing

Jump to bottom
Fran Aguilera edited this page Nov 5, 2025 · 16 revisions

This document explains the process of releasing new versions of Bitdrift SDK.

Pre-requisites for Including Recent Changes in shared-core

If you need to include recents changes added on shared-core, please follow this process:

  1. Find the related dep sha for the change and update it on Cargo.toml. (Sample PR for reference)
  2. Within the capture-sdk directory, run make repin.
  3. Open PR and merge it.

NOTE: If you have build issues on the gradle test app after update, make sure to run locally rustup update before re-building

Verification prior to trigger release

  1. Pull latest main locally and build bazel Android/iOS sample apps
  2. Verify that exploration/timeline sessions is working as expected
  3. Verify fatal issue reporting by triggering artificial JVM crash/Native Crash/ANR

Release process

  1. Open a PR to add a new version entry in https://github.com/bitdriftlabs/capture-sdk/blob/main/CHANGELOG.md. Make sure it's added as a H2 header under the ## [Unreleased] section following our version formatting e.g. ## [0.1.2]. For ref, see the original PR that will trigger the release action
  2. After merging CHANGELOG.md to main, the Auto Release on Changelog Update workflow action will be automatically triggered and perform a release if it detects a new version entry has been added to the list: https://github.com/bitdriftlabs/capture-sdk/actions/workflows/changelog_release.yaml
  3. The entire process should create both a release in github: https://github.com/bitdriftlabs/capture-sdk/releases. For Android the job above also publicly publishes the sdk artifacts in Maven Central: https://central.sonatype.com/namespace/io.bitdrift
  4. [Optional - Android Only] Now that android artifacts are ready, make sure to validate again with latest version on the Gradle Integration example app
  5. At the end of the job another PR will be automatically opened in https://github.com/bitdriftlabs/capture-ios and https://github.com/bitdriftlabs/capture-es (see for ios and react native)

capture-ios

This repo handles the hosting and releases of publicly facing publishing mechanisms for iOS: Swift Package Manager and CocoaPods

  1. Once the release job completes in capture-sdk, look for a PR being created in capture-ios with the new version number and approve it. In order for checks to run you'll have to manually close it and re-open it.
  2. Once the PR merges, follow the Release workflow and approve public releases as needed. Note that this step can take a long time to complete.

capture-es (react-native)

This repo handles the source code and releases of publicly facing publishing mechanisms for JS: NPM

  1. Once the release job completes in capture-sdk, look for a PR being created in capture-es with the title Update Capture SDK to **** with the new version number and approve it. In order for checks to run you'll have to manually close it and re-open it.
  2. After merge of Update Capture SDK to **** PR, a new release job will automatically open a new chore: release react-native * PR that will automatically publish new release React Version. After successful release, merge the PR (you can verify release is published here ).

NOTE: If the PR wasn't auto-generated you can still trigger it manually via react-native-release action by adding the expected release version.

bitdrift-docs

This process is not automated yet so you'll need to manually open a PR in https://github.com/bitdriftlabs/bitdrift-docs for the public release notes. Use the published CHANGELOG.md to power the docs notes.

Version Formatting

Public bitdrift SDK versions should follow the following format:

0.{x}.{y}(-rc.{z})?

Example 0.1.0.

Please note that while officially our releases follow 0.x.y format GitHub Releases use their "v" prefixed version (i.e., v0.x.y). That's because some tooling expects this to differentiate other git tags from versioned releases.

Examples of correctly formatted versions:

  • 0.1.0
  • 0.1.12
  • 0.1.12-rc.1

Examples of incorrectly formatted versions:

  • v0.1.0
  • v0.1.1.0
  • 0.1.12-rc.0
  • 0.1.12test

Release Candidates

For increased development velocity and higher quality of stable SDK releases, we allow for the release of RC ("release candidate") versions of the SDK.

The way it works is that for small iterative changes to the SDK (changes we don't want to communicate to our customers as they are too small or not ready) or changes that we want to test more thoroughly before releasing them to a wider audience, we release 0.x.y-rcx versions of the SDK. Such releases should not be automatically picked up by dependency managers, but their existence will allow us to integrate, test, and monitor them internally.

Multiple release candidates can be released for a given SDK version, for example, 0.1.3-rc.1, followed by 0.1.3-rc.2, and so on. Once we reach a point where we want to share a given version with a wider audience, we cut a stable release, for instance, 0.1.3.

Test Releases

For increased developer velocity, the regex that CI uses to verify versions is more permissive compared to what we recommend the version string to look like for public releases. For example, a version such as 0.1.3-test.1 is allowed.

Clone this wiki locally