Skip to content

Commit e840692

Browse files
zsimiczsimic
committed
Added AGENTS.md
1 parent c808ca7 commit e840692

File tree

2 files changed

+108
-3
lines changed

2 files changed

+108
-3
lines changed

‎AGENTS.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# AGENTS.md
2+
3+
## Purpose
4+
5+
This file defines repo-specific guidance for coding agents working on `setupmeta`.
6+
Use it as the first source of truth for how to make changes safely and consistently.
7+
8+
## Project Summary
9+
10+
- `setupmeta` helps keep `setup.py` files minimal by auto-filling metadata and requirements.
11+
- It provides custom setup commands: `explain`, `version`, and `check`.
12+
- It supports git-tag-based versioning and automated version bumps.
13+
- The project is self-hosted: `setup.py` uses `setupmeta` itself and has bootstrap behavior.
14+
15+
## Core Principles
16+
17+
- Preserve backward compatibility for users relying on legacy `setup.py` workflows.
18+
- Keep runtime dependencies minimal; prefer stdlib for runtime code.
19+
- Favor explicit, test-covered behavior over cleverness.
20+
- Keep documentation aligned with actual behavior and test scenarios.
21+
22+
## Repository Layout
23+
24+
- `setupmeta/`: main library code (`commands`, `model`, `scm`, `versioning`, etc.)
25+
- `tests/`: unit tests + scenario replay tests
26+
- `tests/scenarios/` and `examples/`: behavior fixtures with `expected.txt` snapshots
27+
- `docs/`: user and contributor documentation
28+
- `setup.py`: self-bootstrapping package definition
29+
- `tox.ini`: test/lint/docs/coverage orchestration
30+
31+
## Environment and Commands
32+
33+
Use these commands from repo root:
34+
35+
- Quick tests: `.venv/bin/pytest -q`
36+
- Full test/lint/docs run: `tox`
37+
- Single tox env: `tox -e py314`
38+
- Fast compatibility matrix (old+new + coverage): `tox -e py39,py314,coverage`
39+
- Style only: `tox -e style`
40+
- Docs checks: `tox -e docs`
41+
- Refresh scenario snapshots: `tox -e refreshscenarios`
42+
- Manual command checks:
43+
- `.venv/bin/python setup.py explain`
44+
- `.venv/bin/python setup.py version`
45+
- `.venv/bin/python setup.py check -q`
46+
47+
Notes:
48+
49+
- `tox.ini` pins `UV_CACHE_DIR` to `.tox/.uv-cache`, so no command-line prefix is needed.
50+
- `py37` exists because it is the oldest Python still supported by this library.
51+
- If `py37` is unavailable locally (common on macOS arm64), substitute the oldest available interpreter and pair it with the newest one.
52+
Example: system Python `3.9` + `3.14` via `tox -e py39,py314,coverage`.
53+
- Intent: keep local runs fast while still exercising one older runtime and one modern runtime, with `coverage combine` validating cross-env coverage data.
54+
55+
## Code Change Expectations
56+
57+
- Keep changes narrow and focused.
58+
- Maintain Python compatibility targeted by this repo (including older supported versions).
59+
- When changing behavior, update both tests and docs in the same change.
60+
- Do not silently alter CLI output formats used by scenario snapshots unless intentional.
61+
- If you touch versioning logic, verify:
62+
- `tests/test_versioning.py`
63+
- `tests/test_setup_py.py`
64+
- scenario outputs that include `version`/`explain`.
65+
66+
## Scenario Snapshot Rules
67+
68+
- Scenario tests compare command output against `expected.txt`.
69+
- If behavior changes are intentional:
70+
1. Regenerate snapshots (`tox -e refreshscenarios`).
71+
2. Review diffs in `tests/scenarios/*/expected.txt` and `examples/*/expected.txt`.
72+
3. Ensure docs and release notes explain user-visible changes.
73+
- If behavior changes are not intentional, fix code/tests instead of accepting snapshot churn.
74+
75+
## Documentation Rules
76+
77+
- Keep `README.rst`, `docs/*.rst`, and example READMEs consistent with current behavior.
78+
- Avoid documenting deprecated/removed commands as active features.
79+
- Keep versioning docs aligned with current strategy defaults and command examples.
80+
- Record user-visible changes in `HISTORY.rst`.
81+
82+
## Safety and Review Checklist
83+
84+
Before finalizing a change, verify:
85+
86+
1. Tests pass for affected areas.
87+
2. Formatting/lint checks pass.
88+
3. Scenario snapshots are unchanged unless intentionally updated.
89+
4. Docs are updated if behavior or commands changed.
90+
5. No unrelated files were modified.
91+
92+
## When to Ask for Clarification
93+
94+
Ask the maintainer before proceeding if:
95+
96+
- A change could break backward compatibility.
97+
- Expected output changes are broad/noisy and intent is unclear.
98+
- A docs update conflicts with tested behavior.
99+
- A refactor touches bootstrap or version bump internals in `setup.py`, `setupmeta/hook.py`, `setupmeta/versioning.py`, or `setupmeta/scm.py`.

‎tox.ini‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,20 @@ indexserver =
77
default = https://pypi.org/simple
88

99
[testenv]
10-
setenv = COVERAGE_FILE={toxworkdir}/.coverage.{envname}
10+
setenv = UV_CACHE_DIR={toxworkdir}/.uv-cache
11+
COVERAGE_FILE={toxworkdir}/.coverage.{envname}
1112
usedevelop = True
1213
deps = -rtests/requirements.txt
1314
py37: pip
1415
py37: wheel
1516
commands = pytest {posargs:-vv --cov=setupmeta --cov-report=xml tests}
1617

18+
[testenv:.pkg]
19+
setenv = UV_CACHE_DIR={toxworkdir}/.uv-cache
20+
1721
[testenv:coverage]
18-
setenv = COVERAGE_FILE={toxworkdir}/.coverage
22+
setenv = {[testenv]setenv}
23+
COVERAGE_FILE={toxworkdir}/.coverage
1924
skip_install = True
2025
deps = coverage
2126
commands = coverage combine
@@ -24,7 +29,8 @@ commands = coverage combine
2429
coverage html
2530

2631
[testenv:docs]
27-
setenv = PYTHONWARNINGS=ignore
32+
setenv = {[testenv]setenv}
33+
PYTHONWARNINGS=ignore
2834
skip_install = True
2935
deps = check-manifest
3036
readme-renderer

0 commit comments

Comments
 (0)