docs: validate release branches before Lance stable approval (#4711)

Freeze the SDK product baseline on a release branch before validating a
Lance RC, so later main commits do not change the candidate. Require the
RC pin PR's CI and applicable reviews to complete with no blocking
findings before Lance stable publication. Draft-skipped reviews are
missing evidence, and green CI does not clear a request-changes
recommendation.

After the upstream release, update only the validated dependency
references, rerun checks and refresh review, then publish from the
verified release branch. Document Cargo override boundaries, exact
commit/artifact evidence, and the workflow's actual stable input
(`type=stable`).

Validation: Markdown fences, public-scope and diff checks passed; the
documented workflow inputs were checked against the repository workflow.
This commit is contained in:
Yang Cen
2026-10-29 17:06:55 +08:00
committed by GitHub
parent 280ca41061
commit 06b6625a94
+73 -1
View File
@@ -24,6 +24,68 @@ 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](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section),
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 before reporting the stable release as complete.
## Making releases
The release process uses a handful of GitHub actions to automate the process.
@@ -54,7 +116,17 @@ To start a release, trigger a `Create Release Commit` action from
(Click on "Run workflow").
* **For a preview release**, leave the default parameters.
* **For a stable release**, set the `release_type` input to `stable`.
* **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:
```bash
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