Merge pull request #63 from taskbadger/sk/conventional-commits

chore: adopt conventional commits and grouped release notes

Author: snopoke

.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:
+        - "*"

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,9 +43,18 @@ 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.
 
+## 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
@@ -54,5 +66,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.