Skip to content

Commit f8ebc5e

Browse files
luoyuxialuoyuxia
authored
doc: introduce how to verify a release document (#282)
1 parent 86e8e24 commit f8ebc5e

File tree

6 files changed

+265
-13
lines changed

6 files changed

+265
-13
lines changed

‎bindings/cpp/README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
-->
18+
19+
# Apache Fluss™ C++ Bindings (Incubating)
20+
21+
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.
22+
23+
## Requirements
24+
25+
- Rust (see [rust-toolchain.toml](../../rust-toolchain.toml) at repo root)
26+
- C++17-capable compiler
27+
- CMake 3.18+ and/or Bazel
28+
- Apache Arrow (for Arrow-based APIs)
29+
30+
## Build
31+
32+
From the repository root or from `bindings/cpp`:
33+
34+
**With CMake:**
35+
36+
```bash
37+
cd bindings/cpp
38+
mkdir build && cd build
39+
cmake ..
40+
cmake --build .
41+
```
42+
43+
**With Bazel:**
44+
45+
```bash
46+
cd bindings/cpp
47+
bazel build //...
48+
```
49+
See [ci.sh](ci.sh) for the CI build sequence.
50+
51+
52+
## TODO
53+
54+
- [] How to introduce fluss-cpp in your own project, https://github.com/apache/opendal/blob/main/bindings/cpp/README.md is a good reference
55+
- [ ] Add CMake/Bazel install and packaging instructions.
56+
- [ ] Document API usage and minimal example in this README.
57+
- [ ] Add more C++ examples (log scan, upsert, etc.).

‎bindings/python/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ Used for writing data to tables, supports PyArrow and Pandas
5353

5454
Used for scanning table log data
5555

56+
57+
# todo: we may move the following part to DEVELOPMENT.md
5658
## Development
5759

5860
## Requirements
@@ -143,6 +145,11 @@ bindings/python/
143145
└── example.py
144146
```
145147

148+
## TODO
149+
150+
- [ ] Add basic usage examples in API Overview (code snippets for Config, FlussConnection, FlussAdmin, FlussTable).
151+
- [ ] Add a "Verifying a release" subsection with install-from-TestPyPI/PyPI and smoke-test steps.
152+
146153
## License
147154

148155
Apache 2.0 License

‎crates/fluss/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
-->
18+
19+
# Apache Fluss™ Rust Client (Incubating)
20+
21+
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.
22+
23+
# 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
24+
# is a good reference
25+
26+
## Requirements
27+
28+
- Rust (see [rust-toolchain.toml](../../rust-toolchain.toml) at repo root)
29+
- protobuf (for build)
30+
31+
## Build
32+
33+
From the repository root:
34+
35+
```bash
36+
cargo build -p fluss-rs
37+
```
38+
39+
## Quick start and examples
40+
41+
## TODO
42+
- [ ] Expand API documentation and usage examples in this README.
43+
- [ ] Add more examples for table, log scan, and write flows.

‎docs/creating-a-release.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -217,11 +217,13 @@ just release $RELEASE_VERSION
217217

218218
This creates under `dist/`:
219219

220-
- `fluss-rust-${RELEASE_VERSION}.tar.gz`
221-
- `fluss-rust-${RELEASE_VERSION}.tar.gz.sha512`
222-
- `fluss-rust-${RELEASE_VERSION}.tar.gz.asc`
220+
- `fluss-rust-${RELEASE_VERSION}-incubating.tgz`
221+
- `fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512`
222+
- `fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc`
223223

224-
Verify with: `gpg --verify dist/fluss-rust-${RELEASE_VERSION}.tar.gz.asc dist/fluss-rust-${RELEASE_VERSION}.tar.gz`
224+
(Incubator policy requires the word "incubating" in release artifact names.)
225+
226+
Verify with: `gpg --verify dist/fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc dist/fluss-rust-${RELEASE_VERSION}-incubating.tgz`
225227

226228
### 4. Stage artifacts to SVN (dist.apache.org dev)
227229

@@ -231,7 +233,7 @@ From the **fluss-rust** repo root, check out the Fluss dev area and add the rele
231233
svn checkout https://dist.apache.org/repos/dist/dev/incubator/fluss fluss-dist-dev --depth=immediates
232234
cd fluss-dist-dev
233235
mkdir $SVN_RC_DIR
234-
cp ../dist/fluss-rust-${RELEASE_VERSION}.* $SVN_RC_DIR/
236+
cp ../dist/fluss-rust-${RELEASE_VERSION}-incubating.* $SVN_RC_DIR/
235237
svn add $SVN_RC_DIR
236238
svn status
237239
svn commit -m "Add fluss-rust ${RELEASE_VERSION} RC${RC_NUM}"
@@ -282,7 +284,7 @@ PyPI (release) / TestPyPI (RC):
282284
* https://pypi.org/project/pyfluss/
283285
* https://test.pypi.org/project/pyfluss/
284286
285-
Please download, verify, and test. Verification steps are in the project docs (todo: add how to verify release).
287+
Please download, verify, and test. Verification steps are in [How to Verify a Release Candidate](verifying-a-release-candidate.md).
286288
287289
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).
288290
@@ -449,5 +451,5 @@ After finishing the release, consider what could be improved (simplifications, c
449451
## See also
450452

451453
- [Release Manager Preparation](https://fluss.apache.org/community/how-to-release/release-manager-preparation/) — GPG and one-time setup
452-
- [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)
454+
- [How to Verify a Release Candidate](verifying-a-release-candidate.md) — Verify signatures, checksums, build, and tests for a release candidate
453455
- [ASF Release Policy](https://www.apache.org/legal/release-policy.html)

‎docs/verifying-a-release-candidate.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
-->
18+
19+
# How to Verify a Release Candidate
20+
21+
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++).
22+
23+
## Validating distributions
24+
25+
The release vote email includes links to:
26+
27+
- **Distribution archive:** source tarball (`fluss-rust-${RELEASE_VERSION}-incubating.tgz`) on [dist.apache.org dev](https://dist.apache.org/repos/dist/dev/incubator/fluss/)
28+
- **Signature file:** `fluss-rust-${RELEASE_VERSION}-incubating.tgz.asc`
29+
- **Checksum file:** `fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512`
30+
- **KEYS file:** [https://downloads.apache.org/incubator/fluss/KEYS](https://downloads.apache.org/incubator/fluss/KEYS)
31+
32+
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.
33+
34+
## Verifying signatures
35+
36+
First, import the keys into your local keyring:
37+
38+
```bash
39+
curl https://downloads.apache.org/incubator/fluss/KEYS -o KEYS
40+
gpg --import KEYS
41+
```
42+
43+
Next, verify all `.asc` files:
44+
45+
```bash
46+
for i in *.tgz; do echo $i; gpg --verify $i.asc $i; done
47+
```
48+
49+
If verification succeeds, you will see a message like:
50+
51+
```text
52+
gpg: Signature made ...
53+
gpg: using RSA key ...
54+
gpg: Good signature from "Release Manager Name (CODE SIGNING KEY) <...@apache.org>"
55+
```
56+
57+
## Verifying checksums
58+
59+
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.
60+
61+
**On macOS (shasum):**
62+
63+
```bash
64+
shasum -a 512 -c fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512
65+
```
66+
67+
**On Linux (sha512sum):**
68+
69+
```bash
70+
sha512sum -c fluss-rust-${RELEASE_VERSION}-incubating.tgz.sha512
71+
```
72+
73+
If you have multiple archives, run `-c` on each `.sha512` file (or use `shasum -a 512 -c *.sha512` / `sha512sum -c *.sha512`).
74+
75+
If the verification is successful, you will see a message like this:
76+
77+
```text
78+
fluss-rust-0.1.0-incubating.tgz: OK
79+
```
80+
81+
## Verifying build
82+
83+
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.
84+
85+
```bash
86+
tar -xzf fluss-rust-${RELEASE_VERSION}-incubating.tgz
87+
cd fluss-rust-${RELEASE_VERSION}-incubating
88+
```
89+
90+
Build the workspace:
91+
92+
```bash
93+
cargo build --workspace --release
94+
```
95+
96+
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/`.
97+
98+
## Verifying LICENSE and NOTICE
99+
100+
Unzip the source release archive and verify that:
101+
102+
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).
103+
2. All files that need it have ASF license headers.
104+
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)).
105+
4. Compatible non-ASL 2.0 licenses are documented (e.g. in NOTICE or in dependency audit files such as `DEPENDENCIES*.tsv`).
106+
107+
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.
108+
109+
## Testing features
110+
111+
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.
112+
113+
**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:
114+
115+
- **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).
116+
- **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.
117+
- **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.
118+
119+
## Incubator release checklist
120+
121+
If the project is in incubation, the ASF Incubator provides a release checklist. You can refer to it when verifying the release:
122+
123+
- [Incubator Release Checklist](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)
124+
125+
## Voting
126+
127+
Votes are cast by replying to the vote email on the dev mailing list with **+1**, **0**, or **-1**.
128+
129+
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).
130+
131+
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.
132+
133+
**Checklist you can reference in your vote:**
134+
135+
- [ ] [Validating distributions](#validating-distributions)
136+
- [ ] [Verifying signatures](#verifying-signatures)
137+
- [ ] [Verifying checksums](#verifying-checksums)
138+
- [ ] [Verifying build](#verifying-build)
139+
- [ ] [Verifying LICENSE and NOTICE](#verifying-license-and-notice)
140+
- [ ] [Testing features](#testing-features)
141+
- [ ] [Incubator release checklist](#incubator-release-checklist) (if applicable)
142+

‎scripts/release.sh‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,11 @@
1414
# See the License for the specific language governing permissions and
1515
# limitations under the License.
1616
#
17-
# Create ASF source release artifacts under dist/:
18-
# fluss-rust-{version}.tar.gz
19-
# fluss-rust-{version}.tar.gz.asc
20-
# fluss-rust-{version}.tar.gz.sha512
17+
# Create ASF source release artifacts under dist/ (aligned with Fluss release package format):
18+
# fluss-rust-{version}-incubating.tgz
19+
# fluss-rust-{version}-incubating.tgz.asc
20+
# fluss-rust-{version}-incubating.tgz.sha512
21+
# (Incubator policy requires "incubating" in the artifact name.)
2122
# Run from repo root. Check out the release tag first (e.g. git checkout v0.1.0-rc1).
2223
# Usage: ./scripts/release.sh [version]
2324
# If version is omitted, it is read from Cargo.toml (workspace.package.version).
@@ -37,9 +38,9 @@ else
3738
fi
3839
fi
3940

40-
PREFIX="fluss-rust-${VERSION}"
41+
PREFIX="fluss-rust-${VERSION}-incubating"
4142
DIST_DIR="${REPO_ROOT}/dist"
42-
TARBALL="${PREFIX}.tar.gz"
43+
TARBALL="${PREFIX}.tgz"
4344

4445
echo "Creating ASF source release for fluss-rust ${VERSION}"
4546
mkdir -p "$DIST_DIR"

0 commit comments

Comments
 (0)