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