diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e13277..7f02e27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### Changed +- Updated public install documentation now that `github-repo-auditor` is live on + PyPI. - Added a manual PyPI Trusted Publishing workflow that builds a release tag and publishes from a protected `pypi` environment after PyPI is configured. - Made PyPI publishing explicitly opt-in while keeping GitHub Releases as the supported public distribution path. diff --git a/README.md b/README.md index 35f0a2e..13e81ba 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,16 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score ### Installation -The package is published as GitHub release artifacts today. PyPI/package-index publishing is not active yet, so registry commands like `pip install github-repo-auditor` are not the recommended public path. See [docs/distribution.md](docs/distribution.md) for the current distribution policy. +The package is published on PyPI and through GitHub Releases. For normal CLI use, +install it as an isolated tool: + +```bash +# uv (recommended) +uv tool install github-repo-auditor + +# pipx +pipx install github-repo-auditor +``` Fastest no-clone path: @@ -148,13 +157,10 @@ chmod +x audit.pyz ./audit.pyz --help ``` -Install from the public GitHub source: +Install from the public GitHub source when you want the latest unreleased code: ```bash -# uv (recommended) uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git' - -# pipx pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git' # local editable clone @@ -165,11 +171,12 @@ pip install -e ".[config]" The self-contained `.pyz` binary is also available from the [GitHub Releases](https://github.com/saagpatel/GithubRepoAuditor/releases) page. +See [docs/distribution.md](docs/distribution.md) for the release and publishing policy. For the local web UI, install the `[serve]` extra from source: ```bash -uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]' +pip install "github-repo-auditor[serve]" # or from a clone: pip install -e ".[serve]" ``` diff --git a/docs/distribution.md b/docs/distribution.md index d70c80b..6627935 100644 --- a/docs/distribution.md +++ b/docs/distribution.md @@ -1,9 +1,16 @@ # Distribution -GitHub Repo Auditor is public and currently distributed through GitHub Releases. +GitHub Repo Auditor is public and distributed through PyPI and GitHub Releases. ## Current Public Path +Use PyPI for the normal CLI install: + +```bash +uv tool install github-repo-auditor +pipx install github-repo-auditor +``` + Use the latest release binary when you want the fastest no-clone install: ```bash @@ -12,7 +19,7 @@ chmod +x audit.pyz ./audit.pyz --help ``` -Use the public GitHub source when you want an isolated tool install: +Use the public GitHub source when you want the latest unreleased code: ```bash uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git' @@ -21,33 +28,30 @@ pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git' ## PyPI Status -PyPI publishing is not active yet. The package name `github-repo-auditor` was -available when checked during the public-readiness pass on 2026-05-18, but that -can change and should be rechecked immediately before first publication. +PyPI publishing is active for `github-repo-auditor`. -The repository is prepared for a future PyPI release: +The repository uses GitHub Actions Trusted Publishing: - package metadata lives in `pyproject.toml` - `make build` creates the wheel and source distribution - `make dist-check` runs `twine check` - `scripts/release.sh` builds and checks artifacts by default -- `scripts/release.sh --publish-pypi` is the only script path that uploads to PyPI +- `scripts/release.sh --publish-pypi` remains an explicit local fallback only - `.github/workflows/pypi.yml` is a manual Trusted Publishing workflow for a release tag, using the `pypi` environment and short-lived OIDC credentials -## Activation Checklist +## Release Checklist -Before the first PyPI release: +For a normal public release: -1. Recheck that the `github-repo-auditor` PyPI name is still available. -2. Configure PyPI Trusted Publishing for owner `saagpatel`, repository - `GithubRepoAuditor`, workflow `pypi.yml`, and environment `pypi`. -3. Protect the GitHub `pypi` environment so publishing requires intentional - approval. -4. Run the standard and distribution gates from [release-gates.md](release-gates.md). -5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the release tag, - for example `v0.1.1`. -6. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`. +1. Run the standard and distribution gates from [release-gates.md](release-gates.md). +2. Create a PEP 440-compatible `v*` tag from the verified `main` commit. +3. Wait for the GitHub Release workflow to publish the wheel, source distribution, + and `audit.pyz` assets. +4. Smoke-test the GitHub Release `audit.pyz`. +5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the same release + tag, for example `v0.1.3`. +6. Approve the protected `pypi` environment. +7. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`. -Until that checklist is complete, GitHub Releases remain the supported public -distribution channel. +GitHub Releases and PyPI should always publish the same tag. diff --git a/tests/test_distribution_policy.py b/tests/test_distribution_policy.py index 06e5bdd..867cbfc 100644 --- a/tests/test_distribution_policy.py +++ b/tests/test_distribution_policy.py @@ -35,8 +35,10 @@ def test_distribution_docs_name_supported_public_channel() -> None: release_gates = (ROOT / "docs" / "release-gates.md").read_text() workflows_readme = (ROOT / ".github" / "workflows" / "README.md").read_text() - assert "GitHub Releases remain the supported public" in distribution_doc - assert "PyPI publishing is not active yet" in distribution_doc + assert "distributed through PyPI and GitHub Releases" in distribution_doc + assert "PyPI publishing is active" in distribution_doc + assert "uv tool install github-repo-auditor" in readme + assert "pipx install github-repo-auditor" in readme assert "docs/distribution.md" in readme assert "scripts/release.sh --publish-pypi" in release_gates assert "pypi.yml" in workflows_readme