|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Dev environment notes specific to this repo. Most of the project conventions live in `CLAUDE.md`; this file collects the rough edges around the local toolchain. |
| 4 | + |
| 5 | +## Setup |
| 6 | + |
| 7 | +```powershell |
| 8 | +uv sync --all-extras |
| 9 | +uv run pytest -m "not slow" # fast tier; matches CI gating step |
| 10 | +uv run pytest # full suite (adds the slow tier) |
| 11 | +uv run ruff check |
| 12 | +uv run mypy src |
| 13 | +``` |
| 14 | + |
| 15 | +## Lefthook (pre-commit / pre-push) |
| 16 | + |
| 17 | +Lefthook wires lint + a focused WAL-growth regression test into `pre-commit`, and `mypy src` + the full suite into `pre-push`. The full suite is occasionally racy on Windows under heavy disk pressure (see the slow-tier split in `.github/workflows/ci.yml`); the gating fact is CI on `origin/main`, so when the pre-push hook hangs intermittently it is reasonable to push with `--no-verify`. The release flow does this by convention. |
| 18 | + |
| 19 | +## Git Bash / MSYS path mangling |
| 20 | + |
| 21 | +Git Bash (the shell that ships with Git for Windows) rewrites POSIX-looking paths that start with `/` into Windows paths, so a call like `gh api /repos/DFKHelper/token-goat/...` becomes `gh api C:/Program Files/Git/repos/DFKHelper/...` and fails with `invalid API endpoint`. Two ways around it: |
| 22 | + |
| 23 | +```bash |
| 24 | +# Option A — omit the leading slash (works for gh): |
| 25 | +gh api repos/DFKHelper/token-goat/actions/runs/<id> |
| 26 | + |
| 27 | +# Option B — disable MSYS path conversion for the call: |
| 28 | +MSYS_NO_PATHCONV=1 gh api /repos/DFKHelper/token-goat/actions/runs/<id> |
| 29 | +``` |
| 30 | + |
| 31 | +The same trick applies to any tool that takes URL-style paths on the command line. |
| 32 | + |
| 33 | +## pytest-timeout × Windows stderr |
| 34 | + |
| 35 | +The per-test timeout is 30 s (`pyproject.toml`). When a Windows subprocess writes Windows-1252 bytes (most commonly the em dash `0x97`) to stderr and a test then trips the timeout, pytest-timeout 2.4.0's capture-decode path can crash on the invalid UTF-8 byte before it prints the timeout message. The combo is rare but masks the real failure when it fires. |
| 36 | + |
| 37 | +Two defensive layers are in place: |
| 38 | + |
| 39 | +- `tests/conftest.py` reconfigures `sys.stdout`/`sys.stderr` with `errors="replace"`. |
| 40 | +- `lefthook.yml` sets `PYTHONIOENCODING=utf-8:replace` on the pre-push test command so subprocesses spawned by tests inherit the same forgiving decoder. |
| 41 | + |
| 42 | +If you still see a decode crash, run the suspect test directly with `-s` to bypass capture and identify the real failure. |
| 43 | + |
| 44 | +## Release flow |
| 45 | + |
| 46 | +See the release checklist captured in user memory (`project_release_checklist.md`). Summary: |
| 47 | + |
| 48 | +1. Bump `pyproject.toml` and regenerate `uv.lock` (`uv lock`) in one commit. |
| 49 | +2. Fold `[Unreleased]` CHANGELOG entries into the new `[X.Y.Z] - YYYY-MM-DD` heading. |
| 50 | +3. Commit with `--no-verify` (lefthook precedent), push `main`, tag `vX.Y.Z`, push the tag. |
| 51 | +4. `gh release create vX.Y.Z --notes-file …` triggers `.github/workflows/publish.yml` (OIDC publish). |
| 52 | +5. Poll `https://pypi.org/pypi/token-goat/json` for the new version. |
0 commit comments