Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 192 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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 }}
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
12 changes: 12 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,24 @@ 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:

- **`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.

Expand Down Expand Up @@ -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/).
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.