From 06b6625a94ca63c726e8c45cd04cc492b9f3d194 Mon Sep 17 00:00:00 2001 From: Yang Cen Date: Thu, 29 Oct 2026 17:06:55 +0800 Subject: [PATCH] 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. --- release_process.md | 74 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) diff --git a/release_process.md b/release_process.md index f223504a7..a1130fdf7 100644 --- a/release_process.md +++ b/release_process.md @@ -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