lancedb/release_process.md

Release process

We release four lancedb SDK packages (Python, Rust, Java, and Node.js) and standalone lancedb command-line binaries.

All SDKs and the CLI share a single version number, defined by current_version in .bumpversion.toml. One vX.Y.Z tag releases all of them, so a breaking change in any SDK bumps the minor version for every SDK.

Note

Python used to be versioned separately, under python-vX.Y.Z tags. It ran three minor versions ahead of the other SDKs, which made the two numbers hard to reason about. Both tracks were merged at v0.37.0: the Python line went 0.36 → 0.37 as usual, while Rust, Java, and Node.js jumped 0.33 → 0.37 to catch up. Tags before v0.37.0 follow the old split scheme.

Preview releases

LanceDB has full releases about every 2 weeks, but in between we make frequent preview releases. These are released as 0.x.y.betaN versions. They receive the same level of testing as normal releases and let you get access to the latest features. However, we do not guarantee that preview releases will be available more than 6 months after they are released. We may delete the preview releases from the packaging index after a while. Once your application is stable, we recommend switching to full releases, which will never be removed from package indexes.

Prepare a stable release

Select the release baseline

Choose the SDK product commit for the planned release and record its SHA. Include all fixes required for that release, including security fixes. Create and push a release branch such as release/v0.41 from that commit before opening the Lance RC upgrade PR. For a patch to an existing stable line, reuse its release branch and backport the required fixes.

Keep the selected product baseline while main continues development. If main already tracks a newer Lance development version, retain that dependency on main and prepare the stable Lance dependency on the SDK release branch. Any additional fixes should arrive through reviewed PRs into the release branch and be validated.

Validate the Lance RC

1. Open a draft PR targeting the SDK release branch to consume the exact Lance RC. Check both the PR base and dependency references when using automation. Update the Rust declarations and lockfile, Python dependency declarations and lockfile, and Java Maven version consistently.
2. Wait for the RC artifacts needed by each SDK to be available, then run the relevant Rust, Python, Node.js, Java, and packaging checks. Resolve compatibility failures and rerun CI after changes to the PR or its release-branch base.
3. Complete code and compatibility review on the RC pin PR. If draft status skips Gatekeeper or another applicable review, mark the PR ready for review or explicitly run the review. Read the recommendation and inline findings even when GitHub records them as comments. Passing CI or a skipped review does not clear an unresolved blocking finding.
4. Before the Lance vote is closed and Lance stable is published, the pin PR must be ready to merge: all relevant CI and reviews are complete, with no unresolved blocking findings at its current head and release-branch base. Refresh reviews and comments immediately before reporting readiness.
5. Report the exact Lance tag and peeled SHA, SDK release-branch base and PR head SHAs (and tested merge commit, when applicable), full CI results and review outcomes to the release manager. Label local source checks separately from checks consuming the published RC artifacts.

Keep the RC validation PR unmerged until Lance is approved, while completing all substantive compatibility and review work before Lance stable publication. Once the official stable Lance artifacts are available, only the mechanical RC-to-stable dependency update and validation of those packages should remain. Update the PR, rerun the relevant checks and refresh reviews. In particular, verify that the Rust package resolves published dependencies: Cargo only reads [patch] settings at the workspace root, so package consumers do not inherit a dependency's workspace override. Merge the validated stable update into the SDK release branch.

Publish the validated candidate

Run Create Release Commit from the verified SDK release-branch head. Do not switch to a later main snapshot after validation. Start with a dry run, review the expected version and lockfile updates, and use the same branch and release inputs for the real run.

The workflow creates a new version commit and tag. Compare that tag with the validated candidate and check that only the expected mechanical version and lockfile updates were introduced. Code or dependency changes require renewed validation. Verify all four SDK publishing workflows and the exact registry artifacts, plus the three CLI archives and their SHA256SUMS on the GitHub release, before reporting the stable release as complete. Download the CLI archives, verify their checksums, and confirm their reported versions on the corresponding platforms.

Making releases

The release process uses a handful of GitHub actions to automate the process.

  ┌─────────────────────┐
  │Create Release Commit│
  └─┬───────────────────┘
    │                    ┌──────────────┐
    └──►(tag) vX.Y.Z ─┬─►│GitHub Release├───►CLI packages + GH Release
                      │  └──────────────┘
                      │  ┌────────────┐
                      ├─►│PyPI Publish├─────►Python Wheels
                      │  └────────────┘
                      │  ┌───────────┐
                      ├─►│NPM Publish├──────►NPM Packages
                      │  └───────────┘
                      │  ┌─────────────┐
                      ├─►│Cargo Publish├────►Cargo Release
                      │  └─────────────┘
                      │  ┌─────────────┐
                      └─►│Maven Publish├────►Java Maven Repo Release
                         └─────────────┘

To start a release, trigger a Create Release Commit action from the workflows page (Click on "Run workflow").

• For a preview release, leave the default parameters.
• For a stable release, select the verified release branch and set the type input to stable.

For example, dry-run a stable release from the selected branch:

gh workflow run make-release-commit.yml --repo lancedb/lancedb \
  --ref release/v0.41 -f type=stable -f dry_run=true -f bump-minor=false

After reviewing the dry run, use the same branch and inputs with dry_run=false. Select bump-minor according to the version and breaking-change check below.

Important

If there was a breaking change since the last stable release, and we haven't done so yet, we should increment the minor version. The CI will detect if this is needed and fail the Create Release Commit job. To fix, select the "bump minor version" option.

CLI release packages

The GitHub Release workflow calls CLI release packages before creating the release. Both stable and beta tags produce these archives:

• lancedb-v<VERSION>-x86_64-unknown-linux-gnu.tar.gz
• lancedb-v<VERSION>-aarch64-unknown-linux-gnu.tar.gz
• lancedb-v<VERSION>-aarch64-apple-darwin.tar.gz

Each archive contains a matching top-level directory with the lancedb executable, LICENSE, and RUST_THIRD_PARTY_LICENSES.html. Linux builds target glibc 2.28; x86_64 retains the repository's Haswell/AVX2 CPU requirements. macOS builds target Apple Silicon on macOS 14 or newer.

Packaging runs on relevant PRs without publishing. To dry-run packaging on a candidate branch before merging or tagging, run:

gh workflow run cli-release.yml --repo lancedb/lancedb --ref <candidate-branch>

Inspect the cli-release workflow artifact: it must contain all three archives and a matching SHA256SUMS. The workflow checks runtime library compatibility and runs the extracted executables; Linux also runs on a clean AlmaLinux 8 system. A tag must match both the CLI and SDK manifests before any build starts.

A CLI packaging failure blocks GitHub release creation. SDK registry workflows run independently. Fix the failure and rerun the failed GitHub Release jobs; the publishing job replaces assets with matching names on an existing release. Verify beta releases remain marked as prereleases and do not take the latest release designation.

Breaking changes

We try to avoid breaking changes, but sometimes they are necessary. When there are breaking changes, we will increment the minor version. (This is valid semantic versioning because we are still in 0.x versions.)

When a PR makes a breaking change, the PR author should mark the PR using the conventional commit markers: either exclamation mark after the type (such as feat!: change signature of func) or have BREAKING CHANGE in the body of the PR. A CI job will add a breaking-change label to the PR, which is what will ultimately be used to CI to determine if the minor version should be incremented.

Important

Reviewers should check that PRs with breaking changes receive the breaking-change label. If a PR is missing the label, please add it, even if after it was merged. This label is used in the release process.

Some things that are considered breaking changes:

• Upgrading lance to a new minor version. Minor version bumps in Lance are considered breaking changes during 0.x releases. This can change behavior in LanceDB.
• Upgrading a dependency pin that is in the Rust API. In particular, upgrading DataFusion and Arrow are breaking changes. Changing dependencies that are not exposed in our public API are not considered breaking changes.
• Changing the signature of a public function or method.
• Removing a public function or method.

We do make exceptions for APIs that are marked as experimental. These are APIs that are under active development and not in major use. These changes should not receive the breaking-change label.