dev/release.md

# 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 `dev@mahout.apache.org` 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 `dev@mahout.apache.org`.
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 `dev@mahout.apache.org`.
-   **Update website documentation** with the new release notes.