Release Process

Release Process

Veloura publishes from GitHub Releases through PyPI Trusted Publishing.

1. Choose a version

Use semantic versioning:

• Patch: compatible fixes and small hardening changes.
• Minor: backward-compatible features.
• Major: intentional compatibility breaks.

PyPI versions and filenames are permanent. Never rebuild and upload a changed artifact under an existing version.

2. Update source metadata

Keep these values aligned:

• pyproject.toml
• veloura/__init__.py
• Versioned documentation headings
• Demo user-agent, when applicable

Search before release:

rg -n '0\.6\.[0-9]+|version\s*=|__version__' \
  pyproject.toml veloura README.md docs examples

3. Verify locally

python3 -m unittest discover -s tests -v
python3 -m compileall -q veloura examples
python3 -m html.parser docs/index.html
python3 -m build
python3 -m twine check dist/veloura_audio-0.6.6*

Install the wheel in a clean environment:

cd /tmp
python3 -m venv veloura-release-check
source veloura-release-check/bin/activate
python3 -m pip install /path/to/veloura_audio-0.6.6-py3-none-any.whl
python3 -m veloura doctor
python3 -c 'import veloura; print(veloura.__version__)'

4. Commit and push

git add -A
git commit -m "Release 0.6.6"
git push origin main

Confirm CI is green before publishing.

5. Publish the GitHub Release

Create a release with:

• Tag: v0.6.6
• Target: main
• A human-readable title.
• Notes describing user-visible behavior and verification.

The workflow checks that the tag matches the package version, runs tests, builds the wheel and source archive, validates both, and publishes through the protected pypi environment.

Manual workflow runs are intentionally build-only. They verify artifacts but do not publish to PyPI.

6. Verify PyPI

Wait for the workflow to finish, then:

cd /tmp
python3 -m venv veloura-pypi-check
source veloura-pypi-check/bin/activate
python3 -m pip install --no-cache-dir veloura-audio==0.6.6
python3 -m veloura doctor
python3 -c 'import veloura; print(veloura.__version__)'

Check the PyPI files, hashes, and Trusted Publishing provenance.

If publishing fails

Read the exact failing step.

• File already exists: that version is already published. Bump the version.
• Tag mismatch: create a tag matching v plus the project version.
• Trusted Publisher rejected: check the PyPI project, owner/repository, workflow filename, environment, and event configuration.
• Tests or Twine failed: fix the source, bump the version only if files were already uploaded, and rerun verification.

Do not delete a valid release merely to hide a failed workflow. Preserve the history and publish a corrected patch version when needed.