From 7bce51dd486baef14077e0891c515e39088a7290 Mon Sep 17 00:00:00 2001 From: Saagar Date: Mon, 18 May 2026 02:49:58 -0700 Subject: [PATCH] docs: polish public project surface - replace placeholder README badges with live public status badges - refresh release and workflow docs for active PyPI publishing - tighten contributor and security guidance for public users Tests: ruff check src/ tests/; python3 -m pytest tests/test_distribution_policy.py -q -p no:cacheprovider; python3 -m pytest -q -p no:cacheprovider --- .github/workflows/README.md | 4 +++- CHANGELOG.md | 4 ++++ CONTRIBUTING.md | 10 +++++----- README.md | 8 +++++++- SECURITY.md | 2 +- docs/audit-serve.md | 10 ++++++++-- docs/release-gates.md | 23 ++++++++++++----------- tests/test_distribution_policy.py | 5 +++++ 8 files changed, 45 insertions(+), 21 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 68d65a3..463ba1b 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -35,7 +35,9 @@ environment `pypi`. ## `audit.yml` — Manual Automated Audit -Runs manually via `workflow_dispatch`. The automatic weekly schedule is disabled while the repository remains private to avoid recurring GitHub Actions billing. +Runs manually via `workflow_dispatch`. No automatic weekly schedule is enabled; this +keeps public CI usage intentional and avoids opening or updating scheduled handoff +issues unless an operator starts the workflow. Steps: 1. Install the package with config support. diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f02e27..ec77c23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### Changed +- Replaced placeholder README badges with live CI, PyPI, release, Python, and + license badges for the public repository. +- Refreshed public contributor, security, release-gate, and workflow docs now + that PyPI publishing is active. - 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ea628d..6cbe238 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Thank you for your interest in contributing. This guide covers how to set up a l ## Prerequisites - **Python 3.11 or later** — the codebase uses `match` statements, `X | Y` union syntax, and other 3.11+ features. -- **A GitHub Personal Access Token** — required to audit private repos and avoid rate limits. Create one at with `repo` and `read:org` scopes. +- **A GitHub Personal Access Token** — optional for public-only audits, but useful for private repos, organization metadata, and higher rate limits. Create one at with the narrowest scopes needed for the audit you plan to run. - **Git** — standard installation, used for shallow cloning during audits. ## Local Setup @@ -18,15 +18,15 @@ cd GithubRepoAuditor # Install all runtime + dev dependencies make install-dev -# Copy the environment template and fill in your token +# Copy the environment template if you need authenticated audit runs cp .env.example .env -# Edit .env — at minimum set GITHUB_TOKEN= +# Edit .env and set GITHUB_TOKEN= ``` If you do not use `make`, the equivalent pip command is: ```bash -python3 -m pip install -r requirements.txt pytest ruff mypy +python3 -m pip install -e ".[dev,config]" ``` ## Running Tests @@ -171,4 +171,4 @@ Before opening a PR, verify: ## Questions -Open an issue or start a discussion on GitHub. Please include the output of `python3 -m src.cli --help` and your Python version (`python3 --version`) when reporting bugs. +Open an issue on GitHub. Please include the output of `audit --help` and your Python version (`python3 --version`) when reporting bugs. diff --git a/README.md b/README.md index 13e81ba..8773e41 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # GitHub Repo Auditor -[![Python](https://img.shields.io/badge/Python-%233776ab?style=flat-square&logo=python)](#) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](#) [![Tests](https://img.shields.io/badge/tests-covered-brightgreen?style=flat-square)](#) +[![CI](https://github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml/badge.svg)](https://github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/github-repo-auditor.svg)](https://pypi.org/project/github-repo-auditor/) +[![Python](https://img.shields.io/pypi/pyversions/github-repo-auditor.svg)](https://pypi.org/project/github-repo-auditor/) +[![Release](https://img.shields.io/github/v/release/saagpatel/GithubRepoAuditor?display_name=tag)](https://github.com/saagpatel/GithubRepoAuditor/releases/latest) +[![License](https://img.shields.io/github/license/saagpatel/GithubRepoAuditor.svg)](LICENSE) > Know the truth about every project you've ever started — because `git log` across 100 repos doesn't tell you which ones are worth finishing. @@ -112,6 +116,8 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score - Release gates: [docs/release-gates.md](docs/release-gates.md) - Distribution status: [docs/distribution.md](docs/distribution.md) - Project history: [docs/project-history.md](docs/project-history.md) +- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) +- Security policy: [SECURITY.md](SECURITY.md) ## Features diff --git a/SECURITY.md b/SECURITY.md index 5f50f30..d3f9389 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -22,4 +22,4 @@ We aim to acknowledge reports within 48 hours and resolve confirmed vulnerabilit - **GitHub token handling**: tokens are passed via env var, never logged or stored on disk - **Notion API token**: same handling as above - **Subprocess git clone**: uses authenticated URLs that are cleaned from env after use -- **Output files**: reports written to local directory only +- **Output files**: reports are written to the local `output/` directory only diff --git a/docs/audit-serve.md b/docs/audit-serve.md index 02d86b7..c1e19a2 100644 --- a/docs/audit-serve.md +++ b/docs/audit-serve.md @@ -14,10 +14,16 @@ The web UI dependencies are in the `[serve]` extra and are not installed by defa # editable / dev install pip install -e '.[serve]' -# or via uv tool from the public GitHub source +# from PyPI +pip install 'github-repo-auditor[serve]' + +# or via pipx from PyPI +pipx install 'github-repo-auditor[serve]' + +# or via uv tool from the public GitHub source for unreleased code uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]' -# or via pipx from the public GitHub source +# or via pipx from the public GitHub source for unreleased code pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]' ``` diff --git a/docs/release-gates.md b/docs/release-gates.md index 2a508a1..2827886 100644 --- a/docs/release-gates.md +++ b/docs/release-gates.md @@ -153,19 +153,20 @@ All three must pass before tagging: and non-PEP 440 tag suffixes can break the release build. - Public hardening releases should use patch versions (`v0.1.x`). Feature releases should move the minor version (`v0.2.0`, `v0.3.0`, and so on). -- PyPI upload is explicit opt-in and not part of the current public install story. - `scripts/release.sh` builds and checks artifacts by default; it uploads only when - run as `scripts/release.sh --publish-pypi` with valid credentials. CI only checks - and uploads to GitHub Releases. -- After PyPI Trusted Publishing is configured, prefer the manual `Publish to PyPI` - workflow over local token-based uploads. It builds the release tag in one job and - publishes from a separate `pypi` environment job with `id-token: write`. +- PyPI publishing is active through the manual `Publish to PyPI` workflow. Keep + GitHub Releases and PyPI on the same tag for each public release. +- `scripts/release.sh` builds and checks artifacts by default. + `scripts/release.sh --publish-pypi` remains an explicit local fallback only; + prefer Trusted Publishing over token-based local uploads. +- The manual `Publish to PyPI` workflow builds the release tag in one job and + publishes from a separate protected `pypi` environment job with + `id-token: write`. - The `[serve]` extra is not bundled in the shiv binary by default. Users who need the - web UI should install from the GitHub source with the `[serve]` extra or use a local - editable clone. + web UI should install `github-repo-auditor[serve]` from PyPI or use a local editable + clone. -See [distribution.md](distribution.md) for the public distribution policy and the -remaining PyPI activation checklist. +See [distribution.md](distribution.md) for the public distribution policy and release +checklist. ## Web UI Gate (scope: audit serve) diff --git a/tests/test_distribution_policy.py b/tests/test_distribution_policy.py index 867cbfc..23a3473 100644 --- a/tests/test_distribution_policy.py +++ b/tests/test_distribution_policy.py @@ -39,7 +39,12 @@ def test_distribution_docs_name_supported_public_channel() -> None: 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 "github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml/badge.svg" in readme + assert "img.shields.io/pypi/v/github-repo-auditor.svg" in readme assert "docs/distribution.md" in readme + assert "PyPI publishing is active through the manual" in release_gates + assert "not part of the current public install story" not in release_gates + assert "remaining PyPI activation checklist" not in release_gates assert "scripts/release.sh --publish-pypi" in release_gates assert "pypi.yml" in workflows_readme assert "id-token: write" in workflows_readme