Skip to content

releasing.md

Latest commit

 

History

History
100 lines (70 loc) · 2.79 KB

releasing.md

File metadata and controls

100 lines (70 loc) · 2.79 KB

Releasing TraceLens

TraceLens uses tag-driven releases. The package version comes from the git tag, and CI publishes only when a maintainer pushes a release tag.

This avoids CI-generated version commits, release loops, and PyPI's immutable version constraint.

Release Model

  • Every pull request and every main commit runs tests, lint, typecheck, and package build validation.
  • A tag named vX.Y.Z builds package version X.Y.Z.
  • Pushing that tag triggers .github/workflows/release.yml.
  • The release workflow publishes to PyPI using trusted publishing.

One-Time PyPI Setup

Before the first release, create the PyPI project and configure trusted publishing:

  1. Confirm the package name is available:

    python -m pip index versions tracelens

    A "No matching distribution found" response means the name is currently unclaimed on PyPI.

  2. In PyPI, add a trusted publisher for this repository:

    • Owner: ssf0409
    • Repository: tracelens
    • Workflow: release.yml
    • Environment: release

  3. In GitHub, create the release environment under repository settings. Add required reviewers if you want a manual approval gate before publishing.

No PyPI API token is required when trusted publishing is configured correctly.

Cut A Release

  1. Move changelog entries from [Unreleased] to a dated version section:

    ## [0.1.0] - 2026-05-20

  2. Ensure the verification gate is green:

    uv lock --check
uv run --frozen pytest -q
uv run --frozen ruff check src/ tests/ examples/ benchmarks/high-stakes-autonomous
uv run --frozen --extra dev mypy src/tracelens/
uv build --sdist --wheel

  3. Run the release-relevant environment checks from Contributor Testing, especially the clean wheel smoke when packaging, CLI, README, public imports, or dependency metadata changed.

  4. Commit the release notes.

  5. Create and push the tag:

    git tag v0.1.0
git push origin v0.1.0

  6. Watch the GitHub Actions release workflow.

  7. After PyPI publish completes, smoke test from a clean environment:

    python -m venv /tmp/tracelens-release-smoke
/tmp/tracelens-release-smoke/bin/python -m pip install tracelens
/tmp/tracelens-release-smoke/bin/tracelens --help

Dependency Guidance

Downstream projects should depend on TraceLens from PyPI:

dependencies = [
    "tracelens>=0.1.0",
]

Public GitHub or PyPI dependencies do not need a CI secret. A secret is only needed when a downstream CI job checks out or installs a private repository.

For local pre-release checks, prefer the built-wheel and downstream smoke guidance in Contributor Testing. TestPyPI is optional and mainly useful when changing the publishing workflow itself.