mirror of https://github.com/lancedb/lancedb.git synced 2026-08-18 12:08:35 +00:00

Files

T

Will Jones bf15655c83 chore: unify SDK versions and release tags on a single line (#3714 )

Python was versioned and tagged separately from the Rust, Java, and
Node.js SDKs, and had drifted three minor versions ahead (0.36 vs 0.33).
Users had no way to tell which Python version corresponded to which Rust
or Node release, and the gap had no meaning behind it.

This unifies the two tracks so there is one version and one tag for all
four SDKs.

## Version

The shared version is set to `0.37.0-beta.0`. Python continues its own
sequence (highest published: 0.36 → 0.37) while Rust, Java, and Node.js
jump 0.33 → 0.37 to meet it. Picking Python's next minor means Python
users see no discontinuity at all, and only the other SDKs skip forward.

Note that `main` trails the `release/v0.32` branch on both lines (main
is at 0.32.0-beta.3 / 0.35.0-beta.3; the release branch carries
0.33.0-beta.0 / 0.36.0-beta.0), so 0.37 is chosen to clear the highest
tag on either branch. Every index stays monotonic:

| index | publishes | last published | next |
|---|---|---|---|
| PyPI | stable only | 0.34.0 | 0.37.0 |
| Fury | previews | 0.36.0b0 | 0.37.0-beta.1 |
| npm | both | 0.33.0-beta.0 | 0.37.0-beta.1 |
| crates.io | stable only | 0.31.0 | 0.37.0 |
| Maven | both | 0.33.0-beta.0 | 0.37.0-beta.1 |

A one-time jump for three SDKs, versus explaining the offset
indefinitely.

## Mechanism

* `python/.bumpversion.toml` is removed. `python/Cargo.toml` — the
source of the Python package version, since `pyproject.toml` declares
`dynamic = ["version"]` — becomes a tracked file of the root config. Its
`cargo update -p lancedb-python` pre-commit hook is dropped as
redundant: `ci/update_lockfiles.sh` already refreshes every workspace
member version in `Cargo.lock`.
* `pypi-publish.yml` triggers on `v*` instead of `python-v*`, so one tag
releases all four packages. `ci/bump_version.sh` and
`make-release-commit.yml` lose their now-dead tag-prefix and
per-language plumbing, including the `python` / `other` dispatch inputs.
* The two byte-identical GH release jobs in `npm-publish.yml` and
`pypi-publish.yml` are replaced by a single `gh-release.yml`. One
release per tag, named `LanceDB vX.Y.Z`, instead of separate "Python
LanceDB" and "Node/Rust LanceDB" releases for the same commit.

The trade-off: there is no longer a way to ship a Python-only patch
without also releasing crates.io, Maven, and npm. That is the cost of
making drift structurally impossible.

## Beta releases marked "Latest" (#3666)

Both GH release jobs used:

```yaml
prerelease: ${{ contains('beta', github.ref) }}
```

The arguments are reversed. `contains(search, item)` asks whether
*`search`* contains *`item`*, so this evaluated "does the literal string
`'beta'` contain `refs/tags/python-v0.35.0-beta.2`?" — always `false`.
Every beta was published as a full release, and GitHub awards "Latest"
to the newest non-prerelease.

The new workflow derives the flag from the parsed version rather than
the raw ref, and sets `make_latest` explicitly:

```yaml
prerelease: ${{ steps.extract_version.outputs.prerelease }}
make_latest: ${{ steps.extract_version.outputs.prerelease == 'false' }}
```

npm was never affected (`--tag preview` uses correct bash), and PyPI
already excludes pre-releases from resolution.

This only fixes releases published from here on. Already-published betas
need a one-time backfill:

```shell
gh api --paginate /repos/lancedb/lancedb/releases \
  --jq '.[] | select(.prerelease == false) | select(.tag_name | test("beta")) | .id' \
  | xargs -I{} gh api -X PATCH /repos/lancedb/lancedb/releases/{} -F prerelease=true
```

## Verification

Ran `ci/bump_version.sh` end-to-end against this branch with the release
tooling installed:

* `preview` → tags `v0.37.0-beta.1` (previous tag `v0.33.0-beta.0`
detected, `pre_n` bump)
* `stable` → tags `v0.37.0`
* Both paths update `.bumpversion.toml`, `rust/lancedb/Cargo.toml`,
`nodejs/Cargo.toml`, `python/Cargo.toml`, `nodejs/package.json`, the 7
`nodejs/npm/*/package.json` files, both Java poms, and
`docs/src/java/java.md` together
* `check_breaking_changes.py` resolves the last stable as `v0.31.0`, so
the minor-version gate passes

All five touched workflows parse as valid YAML and the pre-commit hooks
pass.

## Notes for review

* This targets `main` only, so it takes effect at the next
release-branch cut. The in-flight `release/v0.32` branch still carries
`v0.33.0-beta.0` / `python-v0.36.0-beta.0`; if we want the imminent
stable to be 0.37.0, this needs to be applied there too.
* Historical `python-v*` tags are left alone. The changelog builder
scans `^v`, which does not match them, so the first unified release's
notes will compute `fromTag` from the Rust/Node line only — a one-time
gap in the Python-side changelog.
* Pre-existing and not addressed here: `ci/update_lockfiles.sh --amend`
amends the commit that `bump-my-version` has already tagged, so the
lockfile update lands outside the tag on stable releases.

Fixes #3666

2026-07-25 09:22:35 -07:00

4.8 KiB

Raw Blame History

Release process

We release four lancedb packages: Python, Rust, Java, and Node.js.

All four 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.

Making releases

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

  ┌─────────────────────┐
  │Create Release Commit│
  └─┬───────────────────┘
    │                    ┌──────────────┐
    └──►(tag) vX.Y.Z ─┬─►│GitHub Release├───►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, set the release_type input to stable.

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.

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.

4.8 KiB Raw Blame History

Release process

Preview releases

Making releases

Breaking changes

4.8 KiB

Raw Blame History