leaves12138 commented on code in PR #26: URL: https://github.com/apache/paimon-mosaic/pull/26#discussion_r3278829913
########## docs/verifying-a-release-candidate.html: ########## @@ -0,0 +1,196 @@ +<!-- + 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. +--> + +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>Verifying a Release Candidate - Paimon Mosaic</title> + <link rel="stylesheet" href="css/style.css"> + <script src="js/main.js"></script> +</head> +<body> + <button class="menu-toggle" aria-label="Menu">☰</button> + <div class="overlay"></div> + + <aside class="sidebar"> + <div class="sidebar-header"> + <h2>Paimon Mosaic</h2> + <p>Columnar-bucket hybrid format</p> + </div> + <nav> + <ul> + <li><a href="index.html">Home</a></li> + <li><a href="design.html">Design</a></li> + <li><a href="java-api.html">Java API</a></li> + <li><a href="python-api.html">Python API</a></li> + <li><a href="cpp-api.html">C++ API</a></li> + <li><a href="releases.html">Releases</a></li> + </ul> + </nav> + <div class="sidebar-footer"> + <button class="theme-toggle">Dark Mode</button> + </div> + </aside> + + <main class="main"> + <div class="content"> + <h1>Verifying a Release Candidate</h1> + <p class="subtitle">Guide for anyone participating in the release vote, based on <a href="https://www.apache.org/legal/release-policy.html";>ASF Release Policy</a>.</p> + + <!-- ============================================================ --> + <h2>Validating Distributions</h2> + <p>The release vote email includes links to:</p> + <ul> + <li><strong>Distribution archive:</strong> source tarball (<code>apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz</code>) on <a href="https://dist.apache.org/repos/dist/dev/paimon/";>dist.apache.org dev</a></li> + <li><strong>Signature file:</strong> <code>apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz.asc</code></li> + <li><strong>Checksum file:</strong> <code>apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz.sha512</code></li> + <li><strong>KEYS file:</strong> <a href="https://downloads.apache.org/paimon/KEYS";>https://downloads.apache.org/paimon/KEYS</a></li> + </ul> + <p>Download the archive (<code>.tgz</code>), <code>.asc</code>, and <code>.sha512</code> from the RC directory (e.g. <code>paimon-mosaic-${RELEASE_VERSION}-rc${RC_NUM}/</code>) and the KEYS file.</p> + + <!-- ============================================================ --> + <h2>Verifying Signatures</h2> + <p>Import the keys into your local keyring:</p> +<pre><code>curl https://downloads.apache.org/paimon/KEYS -o KEYS +gpg --import KEYS</code></pre> + <p>Verify the <code>.asc</code> file:</p> +<pre><code>gpg --verify apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz.asc \ + apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz</code></pre> + <p>If verification succeeds, you will see:</p> +<pre><code>gpg: Signature made ... +gpg: using RSA key ... +gpg: Good signature from "Release Manager Name (CODE SIGNING KEY) <[email protected]>"</code></pre> + + <!-- ============================================================ --> + <h2>Verifying Checksums</h2> + <p><strong>On macOS (shasum):</strong></p> +<pre><code>shasum -a 512 -c apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz.sha512</code></pre> + <p><strong>On Linux (sha512sum):</strong></p> +<pre><code>sha512sum -c apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz.sha512</code></pre> + <p>If successful:</p> +<pre><code>apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz: OK</code></pre> + + <!-- ============================================================ --> + <h2>Verifying Build</h2> + <p>Extract the source release and verify it builds. You need <strong>Rust</strong> (stable toolchain).</p> +<pre><code>tar -xzf apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz +cd paimon-mosaic-${RELEASE_VERSION}</code></pre> + + <h3>Rust</h3> + <p>Build and test all workspace crates:</p> +<pre><code>cargo build --workspace --release +cargo test --workspace</code></pre> + + <h3>Java</h3> + <p>Build the Java binding (requires JDK 8+ and Maven):</p> +<pre><code>cargo build --release -p paimon-mosaic-jni +cp target/release/libpaimon_mosaic_jni.* java/src/main/resources/native/ +cd java +mvn clean package</code></pre> + + <h3>Python</h3> + <p>Build and test the Python binding (requires Python 3.9+):</p> +<pre><code>cargo build --release -p paimon-mosaic-ffi +cp target/release/libpaimon_mosaic_ffi.* python/mosaic/ +cd python +pip install -e . +python -c "import mosaic"</code></pre> + + <h3>C++</h3> + <p>Build the C++ tests (requires CMake):</p> +<pre><code>cargo build --release -p paimon-mosaic-ffi +cd cpp +mkdir build && cd build +cmake .. +make</code></pre> + + <!-- ============================================================ --> + <h2>Verifying LICENSE and NOTICE</h2> + <p>Verify that:</p> + <ol> + <li>The <strong>LICENSE</strong> and <strong>NOTICE</strong> files exist in the root directory and are correct.</li> + <li>All source files have ASF license headers.</li> + <li>All dependencies have licenses compatible with ASL 2.0 (<a href="http://www.apache.org/legal/resolved.html#category-x";>ASF third-party license policy</a>).</li> + <li>No unexpected files are included (<code>.git</code>, <code>.github</code>, <code>.asf.yaml</code>, <code>.gitignore</code>, <code>.idea</code>, <code>target/</code> should all be excluded).</li> + </ol> + + <!-- ============================================================ --> + <h2>Testing Published Artifacts</h2> + + <h3>Rust (crates.io)</h3> + <p>RC tags do <strong>not</strong> publish to crates.io (dry-run only). You can test the Rust crate from the source tarball or via git tag dependency:</p> +<pre><code>[dependencies] +paimon-mosaic-core = { git = "https://github.com/apache/paimon-mosaic";, tag = "v${RELEASE_VERSION}-rc${RC_NUM}" }</code></pre> + + <h3>Java (Apache Nexus Staging)</h3> + <p>The RC tag deploys to Apache Nexus staging. To test:</p> + <ol> + <li>Find the staging repository at <a href="https://repository.apache.org/#stagingRepositories";>repository.apache.org</a>.</li> + <li>Add the staging repository URL to your <code>pom.xml</code>: +<pre><code><repositories> + <repository> + <id>apache-staging</id> + <url>https://repository.apache.org/content/repositories/orgapachepaimon-XXXX/</url> + </repository> +</repositories></code></pre> + </li> + <li>Add the dependency: +<pre><code><dependency> + <groupId>org.apache.paimon</groupId> + <artifactId>mosaic</artifactId> + <version>${RELEASE_VERSION}</version> +</dependency></code></pre> + </li> + <li>Verify the JAR contains native libraries for all 4 platforms: + <ul> + <li><code>native/linux/x86_64/libpaimon_mosaic_jni.so</code></li> + <li><code>native/linux/aarch64/libpaimon_mosaic_jni.so</code></li> + <li><code>native/macos/aarch64/libpaimon_mosaic_jni.dylib</code></li> + <li><code>native/windows/x86_64/paimon_mosaic_jni.dll</code></li> + </ul> + </li> + </ol> + + <h3>Python (TestPyPI)</h3> + <p>The RC tag publishes wheels to TestPyPI. Install and verify:</p> +<pre><code>pip install -i https://test.pypi.org/simple/ paimon-mosaic==${RELEASE_VERSION} Review Comment: This installs the final package version from TestPyPI for every RC. Since contains , both and would build the same files; with , later RCs can silently leave/install stale wheels. Please publish RC wheels with a unique PEP 440 prerelease version, such as , or avoid TestPyPI publication until the final tag. ########## tools/releasing/create_source_release.sh: ########## @@ -72,6 +79,18 @@ tar czf apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz paimon-mosaic-$RELEASE_V gpg --armor --detach-sig apache-paimon-mosaic-$RELEASE_VERSION-src.tgz $SHASUM apache-paimon-mosaic-$RELEASE_VERSION-src.tgz > apache-paimon-mosaic-$RELEASE_VERSION-src.tgz.sha512 +echo "Verifying GPG signature" +gpg --verify apache-paimon-mosaic-$RELEASE_VERSION-src.tgz.asc apache-paimon-mosaic-$RELEASE_VERSION-src.tgz + +echo "Verifying tarball integrity" +tar tzf apache-paimon-mosaic-${RELEASE_VERSION}-src.tgz > /dev/null + mv apache-paimon-mosaic-$RELEASE_VERSION-src.* ../ cd .. rm -rf paimon-mosaic-tmp-clone + +echo "" +echo "Source release created successfully. Artifacts in tools/release/:" +ls -la ${CURR_DIR}/release/apache-paimon-mosaic-* +echo "" +echo "Next: upload contents to SVN (see docs/release/creating-a-release.md)." Review Comment: Nit: this path seems stale. The new release guide is , not . ########## docs/creating-a-release.html: ########## @@ -0,0 +1,344 @@ +<!-- + 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. +--> + +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>Creating a Release - Paimon Mosaic</title> + <link rel="stylesheet" href="css/style.css"> + <script src="js/main.js"></script> +</head> +<body> + <button class="menu-toggle" aria-label="Menu">☰</button> + <div class="overlay"></div> + + <aside class="sidebar"> + <div class="sidebar-header"> + <h2>Paimon Mosaic</h2> + <p>Columnar-bucket hybrid format</p> + </div> + <nav> + <ul> + <li><a href="index.html">Home</a></li> + <li><a href="design.html">Design</a></li> + <li><a href="java-api.html">Java API</a></li> + <li><a href="python-api.html">Python API</a></li> + <li><a href="cpp-api.html">C++ API</a></li> + <li><a href="releases.html">Releases</a></li> + </ul> + </nav> + <div class="sidebar-footer"> + <button class="theme-toggle">Dark Mode</button> + </div> + </aside> + + <main class="main"> + <div class="content"> + <h1>Creating a Release</h1> + <p class="subtitle">Guide for Release Managers of Apache Paimon Mosaic, following <a href="https://www.apache.org/legal/release-policy.html";>ASF Release Policy</a>.</p> + + <!-- ============================================================ --> + <h2>Overview</h2> + <p>The release process consists of:</p> + <ol> + <li><a href="#decide-to-release">Decide to release</a></li> + <li><a href="#prepare-for-the-release">Prepare for the release</a></li> + <li><a href="#build-a-release-candidate">Build a release candidate</a></li> + <li><a href="#vote-on-the-release-candidate">Vote on the release candidate</a></li> + <li><a href="#fix-any-issues">If necessary, fix any issues and go back to step 3</a></li> + <li><a href="#finalize-the-release">Finalize the release</a></li> + <li><a href="#promote-the-release">Promote the release</a></li> + </ol> + + <h3>Automated Publishing</h3> + <p>When a version tag is pushed, GitHub Actions automatically publishes language-specific artifacts:</p> + <table> + <thead> + <tr><th>Component</th><th>Tag Pattern</th><th>Published To</th><th>Pre-release (<code>-rc</code>) Behavior</th></tr> + </thead> + <tbody> + <tr><td>Rust crate</td><td><code>v0.1.0</code></td><td>crates.io</td><td>Dry-run only</td></tr> + <tr><td>Java binding</td><td><code>v0.1.0</code></td><td>Apache Nexus staging</td><td>Deploys to staging</td></tr> + <tr><td>Python binding</td><td><code>v0.1.0</code></td><td>PyPI</td><td>Publishes to TestPyPI</td></tr> + </tbody> + </table> + <p>The Release Manager's primary responsibility is managing the <strong>source release</strong> (tarball + signature) and coordinating the community vote. Language artifact publishing is handled by CI once the tag is pushed.</p> + + <!-- ============================================================ --> + <h2 id="decide-to-release">Decide to Release</h2> + <p>Anybody can propose a release on the dev <a href="https://lists.apache.org/[email protected]";>mailing list</a>, giving a short rationale and nominating a committer as Release Manager (including themselves).</p> + <p><strong>Checklist:</strong></p> + <ul> + <li>Community agrees to release</li> + <li>A Release Manager is selected</li> + </ul> + + <!-- ============================================================ --> + <h2 id="prepare-for-the-release">Prepare for the Release</h2> + + <h3>One-time Release Manager Setup</h3> + + <h4>GPG Key</h4> + <ol> + <li> + <p>Install GnuPG:</p> +<pre><code># macOS +brew install gnupg + +# Ubuntu / Debian +sudo apt install gnupg2</code></pre> + </li> + <li> + <p>Generate a key pair (RSA 4096, does not expire, use your <code>@apache.org</code> email):</p> +<pre><code>gpg --full-gen-key</code></pre> + </li> + <li> + <p>Find your key ID:</p> +<pre><code>gpg --list-keys --keyid-format short</code></pre> + </li> + <li> + <p>Upload to key server:</p> +<pre><code>gpg --keyserver hkps://keyserver.ubuntu.com --send-keys <YOUR_KEY_ID></code></pre> + </li> + <li> + <p>Append to the project <a href="https://downloads.apache.org/paimon/KEYS";>KEYS</a> file:</p> +<pre><code>svn co https://dist.apache.org/repos/dist/release/paimon/ paimon-dist-release --depth=files +cd paimon-dist-release +(gpg --list-sigs <YOUR_KEY_ID> && gpg --armor --export <YOUR_KEY_ID>) >> KEYS +svn ci -m "Add <YOUR_NAME>'s public key"</code></pre> + </li> + <li> + <p>Configure Git to sign tags:</p> +<pre><code>git config --global user.signingkey <YOUR_KEY_ID></code></pre> + </li> + </ol> + + <h4>GitHub Actions Secrets</h4> + <p>Ensure the following repository secrets are configured:</p> + <table> + <thead> + <tr><th>Secret</th><th>Purpose</th></tr> + </thead> + <tbody> + <tr><td><code>CARGO_REGISTRY_TOKEN</code></td><td>crates.io publishing</td></tr> + <tr><td><code>NEXUS_STAGE_DEPLOYER_USER</code></td><td>Apache Nexus staging</td></tr> + <tr><td><code>NEXUS_STAGE_DEPLOYER_PW</code></td><td>Apache Nexus staging</td></tr> + <tr><td><code>GPG_SECRET_KEY</code></td><td>Java artifact signing</td></tr> + <tr><td><code>GPG_PASSPHRASE</code></td><td>Java artifact signing</td></tr> + <tr><td><code>PYPI_API_TOKEN</code></td><td>PyPI publishing</td></tr> + <tr><td><code>TEST_PYPI_API_TOKEN</code></td><td>TestPyPI publishing</td></tr> + </tbody> + </table> + + <h3>Clone into a Fresh Workspace</h3> +<pre><code>git clone https://github.com/apache/paimon-mosaic.git +cd paimon-mosaic</code></pre> + + <h3>Set Up Environment Variables</h3> +<pre><code>RELEASE_VERSION="0.1.0" +NEXT_VERSION="0.2.0" +RC_NUM="1"</code></pre> + + <h3>Create a Release Branch</h3> +<pre><code>cd tools +RELEASE_VERSION=${RELEASE_VERSION} RELEASE_CANDIDATE=${RC_NUM} ./releasing/create_release_branch.sh</code></pre> + <p>This creates a branch named <code>release-${RELEASE_VERSION}-rc${RC_NUM}</code> from the current HEAD.</p> + + <h3>Bump Version on Main</h3> + <p>After cutting the release branch, bump <code>main</code> to the next version:</p> +<pre><code>git checkout main +cd tools +OLD_VERSION=${RELEASE_VERSION} NEW_VERSION=${NEXT_VERSION} ./releasing/update_branch_version.sh</code></pre> + <p>The script updates version strings in all <code>pom.xml</code>, <code>Cargo.toml</code> (excluding <code>target/</code>), and <code>python/pyproject.toml</code> files, then creates a commit.</p> + + <!-- ============================================================ --> + <h2 id="build-a-release-candidate">Build a Release Candidate</h2> + + <h3>Create the RC Tag</h3> + <p>Push a signed RC tag to trigger CI workflows:</p> +<pre><code>git checkout release-${RELEASE_VERSION}-rc${RC_NUM} Review Comment: This RC tag is created before any documented step sets the release branch to non-SNAPSHOT versions. In the current tree, is still , and only creates the branch. As a result, the Release Java workflow would deploy a SNAPSHOT artifact instead of the staging artifact that the guide asks voters to verify. Please add a release-branch version update step/script before tagging, then bump main afterward. -- 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]
