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:

# 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.

# 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 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.
  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:
    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.