Skip to content

Commit 4e43ab8

Browse files
committed
chore(dev): harden pre-push against Windows cp1252 stderr; document MSYS path mangling
- conftest.py: reconfigure sys.stdout/sys.stderr with errors="replace" so pytest-timeout's read_global_capture path no longer crashes when a Windows subprocess writes byte 0x97 (cp1252 em dash) to stderr immediately before a per-test timeout fires. - lefthook.yml: set PYTHONIOENCODING=utf-8:replace on the pre-push test command so subprocesses inherit the same forgiving decoder. - CONTRIBUTING.md: dev-environment notes covering lefthook, MSYS_NO_PATHCONV=1 for gh api leading-slash paths, the pytest-timeout interaction, and the release flow.
1 parent a05412e commit 4e43ab8

3 files changed

Lines changed: 70 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
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.

‎lefthook.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,6 @@ pre-push:
1212
typecheck:
1313
run: uv run mypy src
1414
test:
15+
env:
16+
PYTHONIOENCODING: "utf-8:replace"
1517
run: uv run pytest -q --tb=short

‎tests/conftest.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
"""Shared test fixtures."""
22
import logging
33
import shutil
4+
import sys
45
from pathlib import Path
56
from unittest.mock import patch
67

@@ -10,6 +11,21 @@
1011
from token_goat.project import Project, canonicalize, project_hash
1112
from token_goat.session import SessionCache
1213

14+
# Windows subprocesses (notably git on default cp1252 consoles) occasionally
15+
# emit non-UTF-8 bytes — most commonly 0x97 (cp1252 em dash) — to stderr.
16+
# pytest-timeout 2.4.0's `read_global_capture()` path can crash decoding
17+
# those bytes when a test exceeds the per-test timeout, which masks the
18+
# real timeout message and hangs the runner. Reconfiguring sys.stderr /
19+
# sys.stdout with errors="replace" turns the decode into a substitution
20+
# at the test process boundary.
21+
for _stream in (sys.stdout, sys.stderr):
22+
_reconfigure = getattr(_stream, "reconfigure", None)
23+
if _reconfigure is not None:
24+
try:
25+
_reconfigure(encoding="utf-8", errors="replace")
26+
except (ValueError, OSError):
27+
pass
28+
1329
# ---------------------------------------------------------------------------
1430
# Home-directory helpers (used by test_install.py and test_install_codex.py)
1531
# ---------------------------------------------------------------------------

0 commit comments

Comments
 (0)