diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..f8c07a5 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,192 @@ +name: Release +run-name: Release ${{ inputs.version }}${{ inputs.dry-run && ' (dry run)' || '' }} + +on: + workflow_dispatch: + inputs: + version: + description: Version tag, such as v1.2.3 + required: true + dry-run: + description: "Dry run: upload to Test PyPI only. Uncheck to publish to PyPI and create the GitHub release." + type: boolean + default: true + +concurrency: + group: release + cancel-in-progress: false + +permissions: {} + +jobs: + check-version: + name: Check the version + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Check out the repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Install uv + uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 + with: + enable-cache: false + - name: Check that the release runs from main + run: | + if [[ "$GITHUB_REF" != refs/heads/main ]]; then + echo "Releases run from main, not $GITHUB_REF" + exit 1 + fi + - name: Check that the tag matches the package version + run: | + package_version=$(uv version --short --frozen) + echo "Tag: $INPUTS_VERSION, package version: $package_version" + [[ "$INPUTS_VERSION" == "v$package_version" ]] + env: + INPUTS_VERSION: ${{ inputs.version }} + - name: Check that the tag doesn't exist yet + run: | + if git ls-remote --exit-code --tags origin "refs/tags/$INPUTS_VERSION"; then + echo "Tag $INPUTS_VERSION already exists" + exit 1 + fi + env: + INPUTS_VERSION: ${{ inputs.version }} + + extract-changelog: + name: Extract the changelog entry + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Check out the repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Check the changelog has a released heading for this version + run: | + VERSION="${INPUTS_VERSION#v}" awk ' + /^(```|~~~)/ { fence = !fence } + !fence && /^## / && $2 == ENVIRON["VERSION"] { ok = tolower($0) !~ /unreleased/; exit } + END { exit !ok } + ' CHANGELOG.md + env: + INPUTS_VERSION: ${{ inputs.version }} + - name: Extract the changelog entry + run: | + VERSION="${INPUTS_VERSION#v}" awk ' + /^(```|~~~)/ { fence = !fence } + !fence && /^## / { if (found) exit; if ($2 == ENVIRON["VERSION"]) { found = 1; next } } + found + ' CHANGELOG.md > __CHANGELOG-extracted.md + cat __CHANGELOG-extracted.md + env: + INPUTS_VERSION: ${{ inputs.version }} + - name: Check the extracted entry isn't empty + run: grep -q '[^[:space:]]' __CHANGELOG-extracted.md + - name: Upload the extracted entry + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: changelog-extracted + path: __CHANGELOG-extracted.md + + build: + name: Build and inspect the package + needs: [check-version, extract-changelog] + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # Build provenance attestation + attestations: write # Build provenance attestation + steps: + - name: Check out the repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Build and inspect the package + uses: hynek/build-and-inspect-python-package@67230f7b8410ae0052b39c1efc89d89fff43ff10 # v3.0.2 + with: + attest-build-provenance-github: ${{ !inputs.dry-run }} + + upload-to-test-pypi: + name: Upload to Test PyPI + needs: build + runs-on: ubuntu-latest + environment: + name: test-pypi + url: https://test.pypi.org/project/pdc-api/ + permissions: + id-token: write # PyPI trusted publishing + steps: + - name: Download the package + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: Packages + path: dist + - name: Upload to Test PyPI + uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 + with: + repository-url: https://test.pypi.org/legacy/ + skip-existing: true + + upload-to-pypi: + name: Upload to PyPI + needs: upload-to-test-pypi + if: ${{ !inputs.dry-run }} + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/project/pdc-api/ + permissions: + id-token: write # PyPI trusted publishing + steps: + - name: Download the package + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: Packages + path: dist + - name: Upload to PyPI + uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 + + github-release: + name: Create the GitHub release + needs: [upload-to-test-pypi, upload-to-pypi] + if: ${{ !cancelled() + && needs.upload-to-test-pypi.result == 'success' + && (needs.upload-to-pypi.result == 'success' || needs.upload-to-pypi.result == 'skipped') }} + runs-on: ubuntu-latest + permissions: + contents: write # Create the tag and release + steps: + - name: Download the package + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: Packages + path: dist + - name: Download the extracted changelog entry + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: changelog-extracted + - name: Show what the release would contain + if: ${{ inputs.dry-run }} + run: | + echo "Tag $INPUTS_VERSION on $GITHUB_SHA" + ls dist + cat __CHANGELOG-extracted.md + env: + INPUTS_VERSION: ${{ inputs.version }} + - name: Create the GitHub release + if: ${{ !inputs.dry-run }} + run: | + gh release create "$INPUTS_VERSION" \ + --title "$INPUTS_VERSION" \ + --target "$GITHUB_SHA" \ + --notes-file __CHANGELOG-extracted.md \ + dist/*.whl \ + dist/*.tar.gz + env: + GH_REPO: ${{ github.repository }} + GH_TOKEN: ${{ github.token }} + INPUTS_VERSION: ${{ inputs.version }} diff --git a/AGENTS.md b/AGENTS.md index 4a18bf8..31b59d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ A framework-free Python client for the Philanthropy Data Commons (PDC) API. The - `just pdc up` starts PDC's CI stack in Docker; `just integration` runs the live suite against it. - `just typecheck` runs mypy (with the pydantic plugin) over `src` and both test suites, mypy in strict mode over `src`, then pyrefly and ty over `src` and both test suites, and fails at the end if any of them failed. `just typecheck-mypy`, `just typecheck-pyrefly`, and `just typecheck-ty` run one checker each. All take `--python` and `--lowest-direct`, which work as they do for `just test`. - `just zizmor` audits the GitHub Actions workflows; run it after changing anything in `.github/`. It runs offline audits only unless `GH_TOKEN` is set. Arguments go to zizmor. +- Releases go through the Release workflow, which creates the tag; see "Releasing" in `CONTRIBUTING.md`. New changelog entries go under `## Unreleased`. - Verify with `just check` (lint, type checks, and both suites). The unit tests can't catch a change in PDC's behavior; if the stack isn't available, run `just lint`, `just typecheck`, and `just test` and say that integration verification is pending. ## Standards diff --git a/CHANGELOG.md b/CHANGELOG.md index aba5fdc..0662251 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ This project follows [Semantic Versioning](https://semver.org). Until 1.0, a min PDC does not bump its spec version for every API change, so each entry names the spec version and the date the spec was downloaded. +## 0.4.1 (2026-11-20) + +- `pdc-api` is published on [PyPI](https://pypi.org/project/pdc-api/). Install it with `pip install pdc-api`. + ## 0.4.0 (2026-11-19) Breaking changes that make names consistent before a wider release: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3aa5618..c6e0427 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,4 +56,16 @@ just check Generation is deterministic, and CI fails if `_generated.py` doesn't match the pinned spec. When a regenerated model breaks against real PDC data, add or change a rule in `codegen/preprocess.py`. Don't edit `_generated.py` by hand. Delete a rule once PDC fixes the problem it patches. +## Releasing + +1. Open a pull request that bumps `version` in `pyproject.toml`, runs `uv lock`, and renames the changelog's `## Unreleased` heading to `## X.Y.Z (YYYY-MM-DD)`. Merge it. +2. Do a dry run. On the [Release workflow](https://github.com/PhilanthropyDataCommons/pdc-api-python/actions/workflows/release.yml) page, click **Run workflow**, leave the branch on `main`, enter the tag `vX.Y.Z`, leave **Dry run** checked, and run it. The workflow checks that the tag matches the package version and doesn't exist yet, and that the changelog has a dated entry for it. It then builds and inspects the package, uploads it to Test PyPI, and prints the files and release notes it would publish. +3. Check the package on [Test PyPI](https://test.pypi.org/project/pdc-api/) and the release notes in the log of the run's **Create the GitHub release** job. +4. Run the workflow again with the same tag and **Dry run** unchecked. +5. When the PyPI upload asks for approval, a `pypi` environment reviewer approves it. The workflow then uploads to PyPI and creates the tag and GitHub release on the commit it ran on, with the changelog entry as the notes. + +Don't create the tag by hand. GitHub releases are immutable, so once the workflow publishes a release, its tag and files can't be changed or deleted. As on PyPI, fixing a bad release takes a new version. + +PyPI and Test PyPI publish through [trusted publishing](https://docs.pypi.org/trusted-publishers/), from the `release.yml` workflow. Test PyPI trusts the `test-pypi` environment, and PyPI trusts the `pypi` environment, which only `main` can use. + Issues and pull requests are welcome. diff --git a/README.md b/README.md index 0392c34..eab5034 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,16 @@ Install it as `pdc-api` and import it as `pdc_api`. ## Installation -The package is not on PyPI yet. Install it from a tagged release on GitHub: +Install it from [PyPI](https://pypi.org/project/pdc-api/): ```bash -pip install "pdc-api @ git+https://github.com/PhilanthropyDataCommons/pdc-api-python@v0.4.0" +pip install pdc-api ``` or with uv: ```bash -uv add git+https://github.com/PhilanthropyDataCommons/pdc-api-python --tag v0.4.0 +uv add pdc-api ``` Two optional extras add test and seeding helpers: @@ -27,7 +27,7 @@ Two optional extras add test and seeding helpers: - **`testing`:** helpers for mocking PDC responses in your own tests, built on [`responses`](https://github.com/getsentry/responses). - **`seeding`:** helpers for creating PDC and Keycloak test data, built on [`python-keycloak`](https://github.com/marcospereirampj/python-keycloak) and [Faker](https://github.com/joke2k/faker). -Add them to the requirement, as in `"pdc-api[testing,seeding] @ git+https://github.com/PhilanthropyDataCommons/pdc-api-python@v0.4.0"`. +Add them to the requirement, as in `pdc-api[testing,seeding]`. Python 3.12 or later is required. @@ -236,8 +236,8 @@ def test_lists_changemakers(): ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and regenerating the models. +See [CONTRIBUTING.md](https://github.com/PhilanthropyDataCommons/pdc-api-python/blob/main/CONTRIBUTING.md) for development setup, tests, and regenerating the models. ## License -[AGPL-3.0](LICENSE). Maintained by [DrivenData](https://drivendata.org). +[AGPL-3.0](https://github.com/PhilanthropyDataCommons/pdc-api-python/blob/main/LICENSE). Maintained by [DrivenData](https://drivendata.co/). diff --git a/pyproject.toml b/pyproject.toml index 21464d4..cda457e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "pdc-api" -version = "0.4.0" +version = "0.4.1" description = "Python client for the Philanthropy Data Commons (PDC) API" readme = "README.md" license = "AGPL-3.0-only" diff --git a/uv.lock b/uv.lock index bafbfd2..1632472 100644 --- a/uv.lock +++ b/uv.lock @@ -1046,7 +1046,7 @@ wheels = [ [[package]] name = "pdc-api" -version = "0.4.0" +version = "0.4.1" source = { editable = "." } dependencies = [ { name = "pydantic" },