Copilot commented on code in PR #268: URL: https://github.com/apache/fluss-rust/pull/268#discussion_r2777598384
########## .github/workflows/release_python.yml: ########## @@ -0,0 +1,174 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +# Publish the fluss Python binding to PyPI. +# Trigger: push tag only (e.g. v0.1.0). +# Pre-release tags (containing '-') publish to TestPyPI; release tags publish to PyPI. +# +# Token auth: set repo variable PYPI_USE_TOKEN_AUTH = 'true' and add secrets PYPI_API_TOKEN / TEST_PYPI_API_TOKEN. +# Trusted Publishing (OIDC): leave PYPI_USE_TOKEN_AUTH unset; do not pass password so the action uses OIDC. + +name: Release Python + +on: + push: + tags: + - "v*" # Only version-like tags (e.g. v0.1.0, v0.1.0-rc1); avoids running on arbitrary tags + Review Comment: The tag trigger pattern `v*` matches any tag starting with `v` (including non-version tags), so this workflow may run unexpectedly. Consider narrowing it (e.g., `v[0-9]*`) so only version-like tags trigger the release jobs. ########## scripts/bump-version.sh: ########## @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to you under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# Bump version in root Cargo.toml ([workspace.package] and [workspace.dependencies] fluss-rs). +# Run from repo root. Use after cutting a release branch so main is set to the next version. +# +# Usage: ./scripts/bump-version.sh <current_version> <next_version> +# e.g. ./scripts/bump-version.sh 0.1.0 0.1.1 +# Or with env vars: ./scripts/bump-version.sh $RELEASE_VERSION $NEXT_VERSION + +set -e + +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 <current_version> <next_version>" + echo " e.g. $0 0.1.0 0.1.1" + exit 1 +fi + +FROM_VERSION="$1" +TO_VERSION="$2" + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$REPO_ROOT" + +if [ ! -f Cargo.toml ]; then + echo "Cargo.toml not found. Run from repo root." + exit 1 +fi + +# Replace version = "X.Y.Z" with version = "TO_VERSION" (all occurrences in root Cargo.toml) +case "$(uname -s)" in + Darwin) + sed -i '' "s/version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/g" Cargo.toml + ;; + *) + sed -i "s/version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/g" Cargo.toml Review Comment: This `sed` replacement updates every `version = "<from>"` occurrence in the root Cargo.toml. That works today, but it can accidentally bump unrelated dependency versions if they happen to match `FROM_VERSION`. Consider restricting the edit to the `[workspace.package]` section and the `workspace.dependencies.fluss` entry (or using a small TOML-aware update) to avoid unintended replacements. ```suggestion # Replace version only in [workspace.package] and workspace.dependencies.fluss in root Cargo.toml case "$(uname -s)" in Darwin) sed -i '' \ -e "/\[workspace.package\]/,/^\[/{s/^version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/}" \ -e "/\[workspace.dependencies\]/,/^\[/{/fluss/{s/version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/}}" \ Cargo.toml ;; *) sed -i \ -e "/\[workspace.package\]/,/^\[/{s/^version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/}" \ -e "/\[workspace.dependencies\]/,/^\[/{/fluss/{s/version = \"${FROM_VERSION}\"/version = \"${TO_VERSION}\"/}}" \ Cargo.toml ``` ########## docs/creating-a-release.md: ########## @@ -0,0 +1,453 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +# Creating a Fluss Rust Client Release + +This document describes in detail how to create a release of the **Fluss clients** (fluss-rust, fluss-python, fluss-cpp) from the [fluss-rust](https://github.com/apache/fluss-rust) repository. It is based on the [Creating a Fluss Release](https://fluss.apache.org/community/how-to-release/creating-a-fluss-release/) guide of the Apache Fluss project and the [release guide of Apache OpenDAL](https://nightlies.apache.org/opendal/opendal-docs-stable/community/release/); releases are source archives plus CI-published crates.io and PyPI. + +Publishing software has legal consequences. This guide complements the foundation-wide [Product Release Policy](https://www.apache.org/legal/release-policy.html) and [Release Distribution Policy](https://infra.apache.org/release-distribution.html). + +## Overview + + + +The release process consists of: + +1. [Decide to release](#decide-to-release) +2. [Prepare for the release](#prepare-for-the-release) +3. [Build a release candidate](#build-a-release-candidate) +4. [Vote on the release candidate](#vote-on-the-release-candidate) +5. [If necessary, fix any issues and go back to step 3](#fix-any-issues) +6. [Finalize the release](#finalize-the-release) +7. [Promote the release](#promote-the-release) + +## Decide to release + +Deciding to release and selecting a Release Manager is the first step. This is a consensus-based decision of the community. + +Anybody can propose a release (e.g. on the dev mailing list), giving a short rationale and nominating a committer as Release Manager (including themselves). Any objections should be resolved by consensus before starting. + +**Checklist to proceed** + +- [ ] Community agrees to release +- [ ] A Release Manager is selected + +## Prepare for the release + +### 0. One-time Release Manager setup + +Before your first release, perform one-time configuration. See **[Release Manager Preparation](https://fluss.apache.org/community/how-to-release/release-manager-preparation/)** (GPG key, etc.). For fluss-rust you do **not** need Nexus/Maven; you only need GPG for signing the source archive and (optionally) git signing. + +**Checklist (one-time)** + +- [ ] GPG key set up and published to [KEYS](https://downloads.apache.org/incubator/fluss/KEYS) or Apache account +- [ ] Git configured to use your GPG key for signing tags + +### 1. Install Rust (and optional: just) + +The release script (`just release` or `./scripts/release.sh`) uses `git archive` and `gpg`; building or verifying the project locally requires **Rust**. Install the [Rust toolchain](https://rustup.rs/) (the version should match [rust-toolchain.toml](https://github.com/apache/fluss-rust/blob/main/rust-toolchain.toml) in the repo). The dependency list script (`scripts/dependencies.py`) requires **Python 3.11+**. + +```bash +rustc --version +cargo --version +``` + +To use `just release`, install [just](https://github.com/casey/just) (e.g. `cargo install just` or your system package manager). If you prefer not to use just, run `./scripts/release.sh $RELEASE_VERSION` instead. + +### 2. Optional: Create a new Milestone in GitHub + +If the project uses GitHub milestones for release tracking, create a new milestone for the **next** version (e.g. `v0.2` if you are releasing `0.1.x`). This helps contributors target issues to the correct release. + +### 3. Optional: Triage release-blocking issues + +Check open issues that might block the release. Resolve, defer to the next milestone, or mark as blocker and do not proceed until they are fixed. + +### 4. Clone fluss-rust into a fresh workspace + +Use a clean clone to avoid local changes affecting the release. + +```bash +git clone https://github.com/apache/fluss-rust.git +cd fluss-rust +``` + +### 5. Set up environment variables + +Set these once and use them in all following commands. (Bash syntax.) + +```bash +export RELEASE_VERSION="0.1.0" +export RELEASE_TAG="v${RELEASE_VERSION}" +export SVN_RELEASE_DIR="fluss-rust-${RELEASE_VERSION}" +# Only set if there is a previous release (for compare link in DISCUSS / release notes) +export LAST_VERSION="0.0.9" +export NEXT_VERSION="0.2.0" +``` + +For the **first release** there is no previous version; leave `LAST_VERSION` unset or omit it when using the compare link in the DISCUSS thread and release notes. + +### 6. Generate dependencies list + +[ASF release policy](https://www.apache.org/legal/release-policy.html) requires that every release comply with [ASF licensing policy](https://www.apache.org/legal/resolved.html) and that an **audit be performed before a full release**. Generating and committing a dependency list (and using cargo-deny) documents third-party components and supports this requirement. + +Do this on `main` **before** creating the release branch. Then both the release branch (when created from `main`) and `main` will have the same dependency list. + +1. Download and set up [cargo-deny](https://embarkstudios.github.io/cargo-deny/cli/index.html) (see cargo-deny docs). +2. Run the script to update the dependency list (requires **Python 3.11+** for the release tooling), then commit on `main`: + +```bash +git checkout main +git pull +python3 scripts/dependencies.py generate +git add **/DEPENDENCIES*.tsv +# Bash: run shopt -s globstar first so ** matches subdirs +git commit -m "chore: update dependency list for release ${RELEASE_VERSION}" +git push origin main +``` + +To only check licenses (no file update): `python3 scripts/dependencies.py check`. + +### 7. Optional: Start a [DISCUSS] thread + +On [Fluss Discussions](https://github.com/apache/fluss-rust/discussions) or the dev list: + +- **Subject:** `[DISCUSS] Release Apache Fluss clients (fluss-rust, fluss-python, fluss-cpp) $RELEASE_VERSION` +- **Body:** Short rationale; if there is a previous release, add compare link: `https://github.com/apache/fluss-rust/compare/v${LAST_VERSION}...main`. Ask for comments. + +### 8. Create a release branch + +From `main`, create a release branch. All release artifacts will be built from this branch. The tag (RC or release) is created later when building the release candidate. + +```bash +git checkout main +git pull +git checkout -b release-${RELEASE_VERSION} +git push origin release-${RELEASE_VERSION} +``` + +Do **not** create or push the release/RC tag yet; that happens in [Build a release candidate](#build-a-release-candidate) after the source artifacts are staged. + +### 9. Bump version on main for the next development cycle + +So that `main` moves to the next version immediately after the release branch is cut, run the bump script and commit: + +```bash +git checkout main +git pull + +./scripts/bump-version.sh $RELEASE_VERSION $NEXT_VERSION + +git add Cargo.toml +git commit -m "Bump version to ${NEXT_VERSION}" +git push origin main +``` + +The script updates the root `Cargo.toml` ([workspace.package] and [workspace.dependencies] fluss-rs). crates/fluss and bindings inherit `version` from the workspace. + +### 10. Optional: Create PRs for release blog and download page + +You can open a pull request in the **Apache Fluss** repository for the release blog (announcement). If the project website has a download page, also create a PR to add the new version there. **Do not merge these PRs until the release is finalized.** + +--- + +**Checklist to proceed to the next step** + +- [ ] Rust (and optionally just) installed and on PATH +- [ ] Python 3.11+ for dependency list script +- [ ] No release-blocking issues (or triaged) +- [ ] Environment variables set +- [ ] Release branch created and pushed +- [ ] Main branch bumped to `NEXT_VERSION` and pushed +- [ ] Dependencies list generated and committed on main +- [ ] (Optional) DISCUSS thread and/or tracking issue created +- [ ] (Optional) PRs for blog and download page created but not merged + +## Build a release candidate + +Each release candidate is built from the release branch, signed, and staged to the dev area of dist.apache.org. If an RC fails the vote, fix issues and repeat this section with an incremented `RC_NUM` (see [Fix any issues](#fix-any-issues)). + +### 1. Set RC environment variables + +Set these when building a **release candidate**. Start with `RC_NUM=1`; if the vote fails and you build a new candidate, increment to `2`, then `3`, etc. + +```bash +export RC_NUM="1" +export RC_TAG="v${RELEASE_VERSION}-rc${RC_NUM}" +export SVN_RC_DIR="fluss-rust-${RELEASE_VERSION}-rc${RC_NUM}" +``` + +For a **direct release** (no RC), skip these and use `RELEASE_TAG` and `SVN_RELEASE_DIR` from the Prepare step instead. + +### 2. Check out the release branch and create the tag + +Check out the release branch at the commit you want to release, create the signed tag, then push it. Use `RC_TAG` for a release candidate or `RELEASE_TAG` for a direct release. Pushing the tag triggers GitHub Actions (for an RC tag, fluss-python is published to TestPyPI). + +```bash +git checkout release-${RELEASE_VERSION} +git pull +git tag -s $RC_TAG -m "${RC_TAG}" +git push origin $RC_TAG +``` + +Check CI: [Actions](https://github.com/apache/fluss-rust/actions) (Release Rust, Release Python). + +### 3. Create source release artifacts + +From the repository root (on the release branch, at the commit you tagged): + +```bash +just release $RELEASE_VERSION +# Or: ./scripts/release.sh $RELEASE_VERSION +``` + +This creates under `dist/`: + +- `fluss-rust-${RELEASE_VERSION}.tar.gz` +- `fluss-rust-${RELEASE_VERSION}.tar.gz.sha512` +- `fluss-rust-${RELEASE_VERSION}.tar.gz.asc` + +Verify with: `gpg --verify dist/fluss-rust-${RELEASE_VERSION}.tar.gz.asc dist/fluss-rust-${RELEASE_VERSION}.tar.gz` + +### 4. Stage artifacts to SVN (dist.apache.org dev) + +From the **fluss-rust** repo root, check out the Fluss dev area and add the release artifacts. + +```bash +svn checkout https://dist.apache.org/repos/dist/dev/incubator/fluss fluss-dist-dev --depth=immediates +cd fluss-dist-dev +mkdir $SVN_RC_DIR +cp ../dist/fluss-rust-${RELEASE_VERSION}.* $SVN_RC_DIR/ +svn add $SVN_RC_DIR +svn status +svn commit -m "Add fluss-rust ${RELEASE_VERSION} RC${RC_NUM}" +``` + +Verify: [https://dist.apache.org/repos/dist/dev/incubator/fluss/](https://dist.apache.org/repos/dist/dev/incubator/fluss/) + +--- + +**Checklist to proceed to the next step** + +- [ ] Source distribution built and signed under `dist/` +- [ ] Artifacts staged to [dist.apache.org dev](https://dist.apache.org/repos/dist/dev/incubator/fluss/) under `$SVN_RC_DIR` +- [ ] RC (or release) tag pushed to GitHub +- [ ] CI for Release Rust / Release Python succeeded + +## Vote on the release candidate + +Share the release candidate for community review. If the project is in incubation, a [two-phase vote](https://incubator.apache.org/cookbook/#two_phase_vote_on_podling_releases) (Fluss community then Incubator PMC) may be required; otherwise one community vote is enough. + +### Fluss community vote + +Start the vote on the dev@ mailing list. + +**Subject:** `[VOTE] Release Apache Fluss clients (fluss-rust, fluss-python, fluss-cpp) ${RELEASE_VERSION} (RC${RC_NUM})` + +**Body template:** + +``` +Hi everyone, + +Please review and vote on release candidate #${RC_NUM} for Apache Fluss clients (fluss-rust, fluss-python, fluss-cpp) ${RELEASE_VERSION}. + +[ ] +1 Approve the release +[ ] +0 No opinion +[ ] -1 Do not approve (please provide specific comments) + +The release candidate (source distribution) is available at: +* https://dist.apache.org/repos/dist/dev/incubator/fluss/$SVN_RC_DIR/ + +KEYS for signature verification: +* https://downloads.apache.org/incubator/fluss/KEYS + +Git tag: +* https://github.com/apache/fluss-rust/releases/tag/$RC_TAG + +PyPI (release) / TestPyPI (RC): +* https://pypi.org/project/pyfluss/ +* https://test.pypi.org/project/pyfluss/ + +Please download, verify, and test. Verification steps are in the project docs (todo: add how to verify release). + Review Comment: The vote email template still contains a TODO for verification steps. This is likely to be copy/pasted into a real vote thread, so it should link to concrete verification instructions (even if minimal: sha512 + GPG verify commands) rather than a placeholder. ```suggestion Please download, verify, and test the release candidate. For example, on a Unix-like system: * Verify the SHA-512 checksum of the source tarball: sha512sum apache-fluss-*.tar.gz * Verify the GPG signature using the KEYS file: gpg --import KEYS gpg --verify apache-fluss-*.tar.gz.asc apache-fluss-*.tar.gz ``` ########## .github/workflows/release_rust.yml: ########## @@ -0,0 +1,60 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +# Publish the fluss Rust crate to crates.io. +# Trigger: push tag only (e.g. v0.1.0). +# Pre-release tags (containing '-') do not publish; release tags publish to crates.io. +# +# Token auth: set repo variable CARGO_USE_TOKEN_AUTH = 'true' and add secret CARGO_REGISTRY_TOKEN. +# Trusted Publishing (OIDC): leave CARGO_USE_TOKEN_AUTH unset; token is obtained via OIDC (no secret). + +name: Release Rust + +on: + push: + tags: + - "v*" # Only version-like tags (e.g. v0.1.0, v0.1.0-rc1); avoids running on arbitrary tags + Review Comment: The tag trigger pattern `v*` will also match non-version tags like `vfoo`, which contradicts the comment and can cause the release workflow to run unexpectedly. Consider tightening the pattern (e.g., `v[0-9]*`) and relying on `verify-tag-version` as a secondary guard. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
