This is an automated email from the ASF dual-hosted git repository.
guanmingchiu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/mahout.git
The following commit(s) were added to refs/heads/main by this push:
new 6762f85b6 Add release.md (#866)
6762f85b6 is described below
commit 6762f85b66a031af40ad647ed2168b06d0e4ab23
Author: Guan-Ming (Wesley) Chiu <[email protected]>
AuthorDate: Tue Jan 20 02:22:27 2026 +0800
Add release.md (#866)
---
dev/release.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 126 insertions(+)
diff --git a/dev/release.md b/dev/release.md
new file mode 100644
index 000000000..cde6f0616
--- /dev/null
+++ b/dev/release.md
@@ -0,0 +1,126 @@
+# Release Process for Qumat and Qumat-QDP (via ATR)
+
+This document describes the process for releasing `qumat` and `qumat-qdp`. The
process is divided into three main phases:
+1. **Community Pre-Release**: Preparation and testing of the Release
Candidate (RC) by the community.
+2. **Official Release**: Formal signing, voting, and distribution of source
artifacts using the **Apache Trusted Releases (ATR)** platform.
+3. **Final Publication**: Publishing the final version to PyPI after the vote
passes.
+
+## Prerequisites
+
+- **ASF Account**: Required for PMC members to log in to the ATR platform.
+- **PyPI Account**: Required for uploading RCs for community testing.
+
+---
+
+## Phase 1: Community Pre-Release (RC Preparation)
+
+The goal of this phase is to ensure the release candidate is stable and ready
for a formal vote.
+
+### 1.1 Plan the Release
+- Discuss and decide on the release timeline (e.g., "RC1 target date") on
the `[email protected]` mailing list or Slack.
+
+### 1.2 Prepare Artifacts
+Update version numbers and build the artifacts locally.
+
+**Update Versions to RC:**
+Ensure the version includes the `rc` suffix (e.g., `1.0.0rc1`):
+- `qumat/pyproject.toml`
+- `qdp/qdp-python/pyproject.toml`
+- `qdp/Cargo.toml` (if releasing Rust core)
+
+**Build:**
+```bash
+# For Qumat
+cd qumat && python -m build
+
+# For Qumat-QDP
+cd qdp/qdp-python && maturin build --release
+```
+
+**Important:** Store these build artifacts safely. They will be used for both
PyPI upload and ATR submission.
+
+### 1.3 Upload to PyPI (RC Version)
+Upload the generated artifacts to **PyPI** as a Release Candidate.
+
+```bash
+# Upload Qumat
+cd qumat
+twine upload dist/*
+
+# Upload Qumat-QDP
+cd qdp/qdp-python
+twine upload target/wheels/*
+```
+
+*Note: This makes the RC available on the official PyPI for easy testing with
`pip install --pre qumat==1.0.0rc1`.*
+
+### 1.4 Open Testing Issue
+Open a GitHub Issue titled **"Testing Qumat <Version> RC1"**.
+- List the installation commands (e.g., `pip install --pre qumat`).
+- Track feedback, reported bugs, and verification results.
+
+### 1.5 Community Testing & Closure
+- Allow a testing interval (e.g., 3-5 days).
+- If critical bugs are found: Fix them, increment the RC number (e.g., RC2),
and repeat from Step 1.2.
+- Once the community is satisfied and the issue shows positive feedback,
close the issue and proceed to Phase 2.
+
+---
+
+## Phase 2: PMC Official Release via ATR
+
+This phase is executed by a PMC member or Release Manager using the ATR
platform. The PMC votes on **source artifacts**, which are the canonical
release artifacts for Apache projects.
+
+### 2.1 Submit Source Artifacts to ATR
+1. Navigate to the [ATR Web UI](https://release-test.apache.org/).
+2. Select the **Mahout** project.
+3. Click **"Start New Release"**.
+4. Upload the **source tarballs** from Phase 1.2:
+ - `qumat/dist/qumat-1.0.0.tar.gz`
+ - `qdp/qdp-python/target/wheels/qumat_qdp-1.0.0.tar.gz`
+ - ATR will handle GPG signing and generate checksums (SHA256/SHA512).
+
+### 2.2 Verify Release
+Check the "Release Candidates" section in ATR to ensure:
+- Source artifacts are correct
+- GPG signatures are valid
+- Checksums are generated
+
+### 2.3 Vote
+Use the ATR platform to generate the Vote email template.
+1. In the ATR UI, find the Release Candidate.
+2. Click **"Generate Vote Email"** or **"Start Vote"**.
+3. Send the email to `[email protected]`.
+4. Wait for the standard 72-hour voting period (requiring 3 binding +1 votes
from Committers or PMC Members).
+
+---
+
+## Phase 3: Final Publication
+
+### 3.1 Finalize Release in ATR
+Once the vote passes:
+1. Go to the Release Candidate in the ATR UI.
+2. Click **"Promote to Release"** (or **"Publish"**).
+ - This moves the signed source artifacts to the Apache release SVN at
`https://dist.apache.org/repos/dist/release/mahout/`.
+
+### 3.2 Publish Final Version to PyPI
+After the PMC vote passes, publish the final version to PyPI. The artifacts
must be built from the voted source in Apache SVN to ensure they match what the
PMC approved.
+
+**Automated Process:**
+Set up a GitHub Actions workflow that:
+- Is triggered manually via "Workflow Dispatch" with the release version as
input.
+- Downloads the approved source tarball from Apache SVN
(`https://dist.apache.org/repos/dist/release/mahout/`).
+- Verifies GPG signatures and checksums.
+- Builds wheels from the verified source.
+- Uploads to PyPI using Trusted Publisher configuration.
+
+**Important:** The PyPI release is built from the exact source code stored in
Apache SVN that the PMC voted on, ensuring consistency between the Apache
release and PyPI.
+
+### 3.3 Post-Release Actions
+- **Tag the release** in Git:
+ ```bash
+ git tag -a v1.0.0 -m "Release 1.0.0"
+ git push origin v1.0.0
+ ```
+- **Bump the version** in `main` to the next development version (e.g.,
`1.1.0.dev0`).
+- **Announce the release** on `[email protected]`.
+- **Update website documentation** with the new release notes.
