diff --git a/bindings/cpp/README.md b/bindings/cpp/README.md new file mode 100644 index 00000000..2556a4b6 --- /dev/null +++ b/bindings/cpp/README.md @@ -0,0 +1,57 @@ + + +# 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 44d6099c..b0970397 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 00000000..bee8ce84 --- /dev/null +++ b/crates/fluss/README.md @@ -0,0 +1,43 @@ + + +# 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 95714d98..164b64b7 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 00000000..e67d4efc --- /dev/null +++ b/docs/verifying-a-release-candidate.md @@ -0,0 +1,142 @@ + + +# 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 (Rust, Python, C++). + +## 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) <...@apache.org>" +``` + +## 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 8187d1fd..e4e6b079 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"