From a1ed6e32eaca6240032e37dde0be4f6771f37beb Mon Sep 17 00:00:00 2001 From: Simon Kelly Date: Fri, 7 Aug 2026 11:23:51 +0200 Subject: [PATCH 1/2] docs: refresh CLAUDE.md architecture and test prerequisites Procrastinate, context providers and the heartbeat thread were missing from the architecture map, and both test commands understated what they need to run. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c732fbb..07bd857 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,8 +6,8 @@ Official Python client for [Task Badger](https://taskbadger.net/). Public packag ```bash uv sync --frozen # Install deps (incl. dev + cli extras via dependency-groups) -uv run pytest # Run unit tests (integration_tests/ is excluded by default) -uv run pytest integration_tests -vs # Run integration tests (needs Redis + TASKBADGER_API_KEY) +uv run pytest # Run unit tests (needs Redis; integration_tests/ excluded by default) +uv run pytest integration_tests -vs # Run integration tests (needs Redis + Postgres + API key) uv run ruff check . --fix # Lint uv run ruff format . # Format uv build # Build sdist + wheel @@ -20,7 +20,10 @@ Pre-commit runs ruff-check + ruff-format; install with `uv run pre-commit instal - `taskbadger/` — SDK source - `sdk.py`, `mug.py`, `safe_sdk.py` — public API surface (re-exported from `__init__.py`) - `decorators.py` — `@track` decorator - - `systems/`, `celery.py` — Celery integration (optional extra) + - `celery.py`, `procrastinate.py` — per-queue integrations (optional extras) + - `systems/`, `_integrations.py` — auto-tracking layer (`BaseSystemIntegration`) wired onto a Celery/Procrastinate app + - `context_providers/`, `_error_context.py` — pluggable error context (e.g. Sentry issue links) via `init(context_providers=[...])` + - `_heartbeat.py` — background thread pinging long-running tasks - `cli/`, `cli_main.py` — Typer-based CLI (optional `[cli]` extra) - `internal/` — **generated** by `openapi-python-client`; do not hand-edit - `tests/` — unit tests (pytest, pytest-httpx) @@ -40,7 +43,7 @@ The `update-api` invoke task curls `localhost:8000/api/schema.json` by default - Ruff: line-length 120, target Python 3.10, rules `E F I UP DJ PT`. - Supports Python 3.10–3.14 — don't use 3.11+ syntax (e.g. `Self`, `LiteralString`). -- Celery and CLI deps are optional; guard imports inside `taskbadger/celery.py`, `taskbadger/systems/celery.py`, `taskbadger/cli/`. +- Extras (`celery`, `procrastinate`, `cli`, `sentry`) are all optional; keep their imports inside the corresponding module (`taskbadger/celery.py`, `taskbadger/procrastinate.py`, `taskbadger/systems/`, `taskbadger/cli/`, `taskbadger/context_providers/sentry.py`). - `taskbadger/internal/*` is generator output — lint is best-effort, don't reformat manually. ## Releasing @@ -54,5 +57,8 @@ GitHub Actions then drafts a release; publishing the release triggers `publish.y ## Gotchas - `pytest` skips `integration_tests/` via `norecursedirs` — name them explicitly to run. -- Integration tests need `TASKBADGER_ORG`, `TASKBADGER_PROJECT`, `TASKBADGER_API_KEY` env vars and a running Redis. -- Imports of `celery`, `typer`, `rich` must stay optional — only the core httpx/attrs deps are guaranteed. +- Integration tests need `TASKBADGER_ORG`, `TASKBADGER_PROJECT`, `TASKBADGER_API_KEY`, a running Redis, and Postgres via `PROCRASTINATE_DSN` (defaults to `postgresql://postgres:postgres@localhost:5432/procrastinate`). +- Unit tests also need Redis — `tests/conftest.py` points Celery at `redis://localhost:6379` so serialization is exercised for real. +- Don't unpin `openapi-python-client<0.29` — 0.29 generates `datetime.fromisoformat` calls that can't parse the API's `Z`-suffixed timestamps on Python 3.10. +- User-facing features are documented in `README.md`, not a docs site — add a section there when adding one. +- Only the core httpx/attrs/dateutil/tomlkit deps are guaranteed at runtime. From 0043b4dd5dbd78b04712aee2ac5af2ec364acd42 Mon Sep 17 00:00:00 2001 From: Simon Kelly Date: Fri, 7 Aug 2026 11:23:59 +0200 Subject: [PATCH 2/2] chore: adopt conventional commits and grouped release notes Release notes are generated from PR titles; without categories they land as one flat list. Co-Authored-By: Claude Opus 5 (1M context) --- .github/release.yml | 32 ++++++++++++++++++++++++++++++++ CLAUDE.md | 9 +++++++++ 2 files changed, 41 insertions(+) create mode 100644 .github/release.yml diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..579a767 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,32 @@ +changelog: + exclude: + labels: + - duplicate + - invalid + - wontfix + categories: + - title: ⚠️ Breaking Changes + labels: + - breaking + - title: 🚀 Features + labels: + - feat + - enhancement + - title: 🐛 Bug Fixes + labels: + - fix + - bug + - title: 📚 Documentation + labels: + - docs + - documentation + - title: 🧹 Maintenance + labels: + - chore + - refactor + - perf + - test + - ci + - title: Other Changes + labels: + - "*" diff --git a/CLAUDE.md b/CLAUDE.md index 07bd857..67b3b08 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,15 @@ The `update-api` invoke task curls `localhost:8000/api/schema.json` by default - Extras (`celery`, `procrastinate`, `cli`, `sentry`) are all optional; keep their imports inside the corresponding module (`taskbadger/celery.py`, `taskbadger/procrastinate.py`, `taskbadger/systems/`, `taskbadger/cli/`, `taskbadger/context_providers/sentry.py`). - `taskbadger/internal/*` is generator output — lint is best-effort, don't reformat manually. +## Commits and PRs + +Conventional Commits for commit subjects and PR titles: `type(scope): summary`. + +- Types: `feat` `fix` `docs` `chore` `refactor` `perf` `test` `ci`. Breaking: `feat!:` / `fix!:` plus a `BREAKING CHANGE:` footer. +- Scopes (optional): `celery`, `procrastinate`, `cli`, `sdk`, `sentry`, `internal`. +- **Label every PR with its type** (`feat`, `fix`, …). Release notes are auto-generated from PR titles and grouped by label via `.github/release.yml`; an unlabelled PR falls into "Other Changes". +- PRs merge as merge commits, so only PR titles reach the changelog — commit subjects are history hygiene. + ## Releasing ```bash