This is an automated email from the ASF dual-hosted git repository.
yuxia pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fluss-rust.git
The following commit(s) were added to refs/heads/main by this push:
new f8ebc5e doc: introduce how to verify a release document (#282)
f8ebc5e is described below
commit f8ebc5ee83af5243ece863e3896a35d9afe2bc36
Author: yuxia Luo <[email protected]>
AuthorDate: Sun Feb 8 20:51:53 2026 +0800
doc: introduce how to verify a release document (#282)
---
bindings/cpp/README.md | 57 ++++++++++++++
bindings/python/README.md | 7 ++
crates/fluss/README.md | 43 ++++++++++
docs/creating-a-release.md | 16 ++--
docs/verifying-a-release-candidate.md | 142 ++++++++++++++++++++++++++++++++++
scripts/release.sh | 13 ++--
6 files changed, 265 insertions(+), 13 deletions(-)
diff --git a/bindings/cpp/README.md b/bindings/cpp/README.md
new file mode 100644
index 0000000..2556a4b
--- /dev/null
+++ b/bindings/cpp/README.md
@@ -0,0 +1,57 @@
+<!--
+ 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.
+-->
+
+# Apache Fluss™ C++ Bindings (Incubating)
+
+C++ bindings for Fluss, built on top of the [fluss-rust](../../crates/fluss)
client. The API is exposed via a C++ header
([include/fluss.hpp](include/fluss.hpp)) and implemented with Rust FFI.
+
+## Requirements
+
+- Rust (see [rust-toolchain.toml](../../rust-toolchain.toml) at repo root)
+- C++17-capable compiler
+- CMake 3.18+ and/or Bazel
+- Apache Arrow (for Arrow-based APIs)
+
+## Build
+
+From the repository root or from `bindings/cpp`:
+
+**With CMake:**
+
+```bash
+cd bindings/cpp
+mkdir build && cd build
+cmake ..
+cmake --build .
+```
+
+**With Bazel:**
+
+```bash
+cd bindings/cpp
+bazel build //...
+```
+See [ci.sh](ci.sh) for the CI build sequence.
+
+
+## TODO
+
+- [] How to introduce fluss-cpp in your own project,
https://github.com/apache/opendal/blob/main/bindings/cpp/README.md is a good
reference
+- [ ] Add CMake/Bazel install and packaging instructions.
+- [ ] Document API usage and minimal example in this README.
+- [ ] Add more C++ examples (log scan, upsert, etc.).
diff --git a/bindings/python/README.md b/bindings/python/README.md
index 44d6099..b097039 100644
--- a/bindings/python/README.md
+++ b/bindings/python/README.md
@@ -53,6 +53,8 @@ Used for writing data to tables, supports PyArrow and Pandas
Used for scanning table log data
+
+# todo: we may move the following part to DEVELOPMENT.md
## Development
## Requirements
@@ -143,6 +145,11 @@ bindings/python/
└── example.py
```
+## TODO
+
+- [ ] Add basic usage examples in API Overview (code snippets for Config,
FlussConnection, FlussAdmin, FlussTable).
+- [ ] Add a "Verifying a release" subsection with install-from-TestPyPI/PyPI
and smoke-test steps.
+
## License
Apache 2.0 License
diff --git a/crates/fluss/README.md b/crates/fluss/README.md
new file mode 100644
index 0000000..bee8ce8
--- /dev/null
+++ b/crates/fluss/README.md
@@ -0,0 +1,43 @@
+<!--
+ 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.
+-->
+
+# Apache Fluss™ Rust Client (Incubating)
+
+Rust client library for [Apache Fluss™](https://fluss.apache.org/). This crate
provides the core client used by the fluss-rust workspace and by the Python and
C++ bindings.
+
+# Todo: move how to use to the first, and how to build to the last,
https://github.com/apache/opendal/blob/main/core/README.md
+# is a good reference
+
+## Requirements
+
+- Rust (see [rust-toolchain.toml](../../rust-toolchain.toml) at repo root)
+- protobuf (for build)
+
+## Build
+
+From the repository root:
+
+```bash
+cargo build -p fluss-rs
+```
+
+## Quick start and examples
+
+## TODO
+- [ ] Expand API documentation and usage examples in this README.
+- [ ] Add more examples for table, log scan, and write flows.
diff --git a/docs/creating-a-release.md b/docs/creating-a-release.md
index 95714d9..164b64b 100644
--- a/docs/creating-a-release.md
+++ b/docs/creating-a-release.md
@@ -217,11 +217,13 @@ just release $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`
+- `fluss-rust-${RELEASE_VERSION}-incubating.tgz`
+- `fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512`
+- `fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc`
-Verify with: `gpg --verify dist/fluss-rust-${RELEASE_VERSION}.tar.gz.asc
dist/fluss-rust-${RELEASE_VERSION}.tar.gz`
+(Incubator policy requires the word "incubating" in release artifact names.)
+
+Verify with: `gpg --verify
dist/fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc
dist/fluss-rust-${RELEASE_VERSION}-incubating.tgz`
### 4. Stage artifacts to SVN (dist.apache.org dev)
@@ -231,7 +233,7 @@ From the **fluss-rust** repo root, check out the Fluss dev
area and add the rele
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/
+cp ../dist/fluss-rust-${RELEASE_VERSION}-incubating.* $SVN_RC_DIR/
svn add $SVN_RC_DIR
svn status
svn commit -m "Add fluss-rust ${RELEASE_VERSION} RC${RC_NUM}"
@@ -282,7 +284,7 @@ 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).
+Please download, verify, and test. Verification steps are in [How to Verify a
Release Candidate](verifying-a-release-candidate.md).
The vote will be open for at least 72 hours. It is adopted by majority
approval with at least 3 PPMC affirmative votes (or as per project policy).
@@ -449,5 +451,5 @@ After finishing the release, consider what could be
improved (simplifications, c
## See also
- [Release Manager
Preparation](https://fluss.apache.org/community/how-to-release/release-manager-preparation/)
— GPG and one-time setup
-- [Verifying a Fluss
Release](https://fluss.apache.org/community/how-to-release/verifying-a-fluss-release/)
— How to verify artifacts (adapt for fluss-rust source tarball)
+- [How to Verify a Release Candidate](verifying-a-release-candidate.md) —
Verify signatures, checksums, build, and tests for a release candidate
- [ASF Release Policy](https://www.apache.org/legal/release-policy.html)
diff --git a/docs/verifying-a-release-candidate.md
b/docs/verifying-a-release-candidate.md
new file mode 100644
index 0000000..e67d4ef
--- /dev/null
+++ b/docs/verifying-a-release-candidate.md
@@ -0,0 +1,142 @@
+<!--
+ 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.
+-->
+
+# How to Verify a Release Candidate
+
+This document describes how to verify a release candidate (RC) of the **Fluss
clients** (fluss-rust, fluss-python, fluss-cpp) from the
[fluss-rust](https://github.com/apache/fluss-rust) repository. It is intended
for anyone participating in the release vote (binding or non-binding) and is
based on [Verifying a Fluss
Release](https://fluss.apache.org/community/how-to-release/verifying-a-fluss-release/)
of the Apache Fluss project, adapted for the fluss-rust source distribution
and tooling [...]
+
+## Validating distributions
+
+The release vote email includes links to:
+
+- **Distribution archive:** source tarball
(`fluss-rust-${RELEASE_VERSION}-incubating.tgz`) on [dist.apache.org
dev](https://dist.apache.org/repos/dist/dev/incubator/fluss/)
+- **Signature file:** `fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc`
+- **Checksum file:** `fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512`
+- **KEYS file:**
[https://downloads.apache.org/incubator/fluss/KEYS](https://downloads.apache.org/incubator/fluss/KEYS)
+
+Download the archive (`.tgz`), `.asc`, and `.sha512` from the RC directory
(e.g. `fluss-rust-0.1.0-rc1/`) and the KEYS file. Then follow the steps below
to verify signatures and checksums.
+
+## Verifying signatures
+
+First, import the keys into your local keyring:
+
+```bash
+curl https://downloads.apache.org/incubator/fluss/KEYS -o KEYS
+gpg --import KEYS
+```
+
+Next, verify all `.asc` files:
+
+```bash
+for i in *.tgz; do echo $i; gpg --verify $i.asc $i; done
+```
+
+If verification succeeds, you will see a message like:
+
+```text
+gpg: Signature made ...
+gpg: using RSA key ...
+gpg: Good signature from "Release Manager Name (CODE SIGNING KEY)
<[email protected]>"
+```
+
+## Verifying checksums
+
+Next, verify the tarball(s) using the provided `.sha512` file(s). Each
`.sha512` file lists the expected SHA-512 hash for the corresponding archive;
`-c` reads that file and checks the archive.
+
+**On macOS (shasum):**
+
+```bash
+shasum -a 512 -c fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512
+```
+
+**On Linux (sha512sum):**
+
+```bash
+sha512sum -c fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512
+```
+
+If you have multiple archives, run `-c` on each `.sha512` file (or use `shasum
-a 512 -c *.sha512` / `sha512sum -c *.sha512`).
+
+If the verification is successful, you will see a message like this:
+
+```text
+fluss-rust-0.1.0-incubating.tgz: OK
+```
+
+## Verifying build
+
+Extract the source release archive and verify that it builds (and optionally
that tests pass). You need **Rust** (see
[rust-toolchain.toml](https://github.com/apache/fluss-rust/blob/main/rust-toolchain.toml)
for the expected version) and, for full builds, **protobuf** and **Python
3.9+** for bindings.
+
+```bash
+tar -xzf fluss-rust-${RELEASE_VERSION}-incubating.tgz
+cd fluss-rust-${RELEASE_VERSION}-incubating
+```
+
+Build the workspace:
+
+```bash
+cargo build --workspace --release
+```
+
+For Python bindings, see the project
[README](https://github.com/apache/fluss-rust#readme) and [Development
Guide](https://github.com/apache/fluss-rust/blob/main/DEVELOPMENT.md). For C++
bindings, see `bindings/cpp/`.
+
+## Verifying LICENSE and NOTICE
+
+Unzip the source release archive and verify that:
+
+1. The **LICENSE** and **NOTICE** files in the root directory are correct and
refer to dependencies in the source release (e.g. files in the repository such
as fonts, CSS, JavaScript, images).
+2. All files that need it have ASF license headers.
+3. All dependencies have been checked for their license and the license is ASL
2.0 compatible ([ASF third-party license
policy](http://www.apache.org/legal/resolved.html#category-x)).
+4. Compatible non-ASL 2.0 licenses are documented (e.g. in NOTICE or in
dependency audit files such as `DEPENDENCIES*.tsv`).
+
+The project uses [cargo-deny](https://embarkstudios.github.io/cargo-deny/) for
license checks; see [Creating a Fluss Rust Client
Release](creating-a-release.md) for how the dependency list is generated before
a release.
+
+## Testing features
+
+For any user-facing feature included in a release, we aim to ensure it is
functional, usable, and well-documented. Release managers may create testing
issues that outline key scenarios to validate; these are open to all community
members.
+
+**Per-language verification:** For **Rust** and **C++**, build from the source
release and write your own test cases to verify. For **Python**, the RC is
published to **TestPyPI**; install the client from TestPyPI and write your own
test cases (e.g. connect, create table, read/write) to verify. Use the README
in each component as the entry point:
+
+- **Rust client:** You can depend on the RC via its git tag (e.g. in your
`Cargo.toml`: `fluss-rs = { git = "https://github.com/apache/fluss-rust";, tag =
"v${RELEASE_VERSION}-rc${RC_NUM}" }`) and build your own test project to
verify. Alternatively, build from the source release; see
[crates/fluss/README.md](../crates/fluss/README.md).
+- **Python bindings:** See
[bindings/python/README.md](../bindings/python/README.md) for how to add the
Python client (for an RC, install from **TestPyPI**: `pip install -i
https://test.pypi.org/simple/ pyfluss==${RELEASE_VERSION}`); then write test
cases to verify.
+- **C++ bindings:** See [bindings/cpp/README.md](../bindings/cpp/README.md)
for how to build and link the C++ client; then write test cases to verify.
+
+## Incubator release checklist
+
+If the project is in incubation, the ASF Incubator provides a release
checklist. You can refer to it when verifying the release:
+
+- [Incubator Release
Checklist](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)
+
+## Voting
+
+Votes are cast by replying to the vote email on the dev mailing list with
**+1**, **0**, or **-1**.
+
+In addition to your vote, it is customary to state whether your vote is
**binding** or **non-binding**. Only members of the PPMC and mentors have
formally binding votes (and the IPMC on the Incubator general list). If unsure,
you can state that your vote is non-binding. See [Apache Foundation
Voting](https://www.apache.org/foundation/voting.html).
+
+It is recommended to include a short list of what you verified (e.g.
signatures, checksums, build, tests, LICENSE/NOTICE). This helps the community
see what has been checked and what might still be missing.
+
+**Checklist you can reference in your vote:**
+
+- [ ] [Validating distributions](#validating-distributions)
+- [ ] [Verifying signatures](#verifying-signatures)
+- [ ] [Verifying checksums](#verifying-checksums)
+- [ ] [Verifying build](#verifying-build)
+- [ ] [Verifying LICENSE and NOTICE](#verifying-license-and-notice)
+- [ ] [Testing features](#testing-features)
+- [ ] [Incubator release checklist](#incubator-release-checklist) (if
applicable)
+
diff --git a/scripts/release.sh b/scripts/release.sh
index 8187d1f..e4e6b07 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -14,10 +14,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-# Create ASF source release artifacts under dist/:
-# fluss-rust-{version}.tar.gz
-# fluss-rust-{version}.tar.gz.asc
-# fluss-rust-{version}.tar.gz.sha512
+# Create ASF source release artifacts under dist/ (aligned with Fluss release
package format):
+# fluss-rust-{version}-incubating.tgz
+# fluss-rust-{version}-incubating.tgz.asc
+# fluss-rust-{version}-incubating.tgz.sha512
+# (Incubator policy requires "incubating" in the artifact name.)
# Run from repo root. Check out the release tag first (e.g. git checkout
v0.1.0-rc1).
# Usage: ./scripts/release.sh [version]
# If version is omitted, it is read from Cargo.toml
(workspace.package.version).
@@ -37,9 +38,9 @@ else
fi
fi
-PREFIX="fluss-rust-${VERSION}"
+PREFIX="fluss-rust-${VERSION}-incubating"
DIST_DIR="${REPO_ROOT}/dist"
-TARBALL="${PREFIX}.tar.gz"
+TARBALL="${PREFIX}.tgz"
echo "Creating ASF source release for fluss-rust ${VERSION}"
mkdir -p "$DIST_DIR"
