|
1 | 1 | ## Workflow |
2 | 2 |
|
3 | | -- Read-only inspection does not require prior approval. This includes actions like checking status, listing branches or worktrees, inspecting tracking refs, reviewing merged status, reading files, and preparing a proposed cleanup list. |
4 | | -- Present a plan and wait for explicit approval before making changes to repo state. This includes file edits, branch deletion, pruning refs or worktrees, rebases, merges, commits, pushes, and similar mutating actions. |
| 3 | +- Read-only actions don't need prior approval — status, log, branch listing, file reads, drafting. |
| 4 | +- Mutating actions need a plan and explicit approval before running — file edits, commits, pushes, branch/ref/worktree deletion, rebases, merges. |
5 | 5 |
|
6 | 6 | ## Project: OG-IDN |
7 | 7 |
|
8 | 8 | OG-IDN is an Indonesia country calibration of the OG-Core overlapping-generations model of demographics and fiscal policy. |
9 | 9 |
|
10 | 10 | ## Environment |
11 | 11 |
|
12 | | -- Conda environment: `ogidn-dev` |
| 12 | +- Package manager: [`uv`](https://docs.astral.sh/uv/). Install via your package manager (e.g. `brew install uv`) or `pip install uv`. |
| 13 | +- Local virtualenv: `.venv` at the repo root, created by `uv sync --extra dev`. |
| 14 | +- Run Python/pytest/etc. via `uv run <cmd>` (preferred — uses the project venv without activation) or activate first with `source .venv/bin/activate`. |
| 15 | +- For docs/Jupyter Book work, also pass `--extra docs`: `uv sync --extra dev --extra docs`. |
13 | 16 |
|
14 | | -## Python formatting |
| 17 | +## Python formatting and linting |
15 | 18 |
|
16 | | -- Run `black` on all touched `.py` files before staging and pushing. |
17 | | -- Do not run `black` on non-Python files (e.g. README.md will fail to parse). |
18 | | -- Re-run tests after formatting to confirm nothing broke. |
19 | | -- Format command: `conda run -n ogidn-dev python -m black <files>` |
| 19 | +- Sequence: edit → format → test → stage → commit → push. |
| 20 | +- Format + auto-fix: `make format` (runs `uv run ruff format .` + `uv run ruff check . --fix` + `uv run linecheck . --fix`). |
| 21 | +- CI check (no changes): `make lint` (runs `uv run ruff format --check .` + `uv run ruff check .`). |
| 22 | +- Ruff config lives in `pyproject.toml` under `[tool.ruff]`; matches OG-Core. |
| 23 | +- Re-run tests after formatting — ruff can change line breaks that affect string literals and assertions. |
20 | 24 |
|
21 | 25 | ## Testing |
22 | 26 |
|
23 | | -- Full suite: `conda run -n ogidn-dev python -m pytest tests/ -q` |
24 | | -- Targeted: `conda run -n ogidn-dev python -m pytest tests/test_calibrate.py tests/test_input_output.py tests/test_macro_params.py -q` |
| 27 | +- Default suite (matches CI, skips the long example run): `uv run python -m pytest -m 'not local' -q` (or `make test`). |
| 28 | +- Targeted (fast): `uv run python -m pytest tests/test_macro_params.py tests/test_income.py tests/test_input_output.py tests/test_calibrate.py -q`. |
| 29 | +- Full example run (slow, ~35 min – 2 hr): `uv run python examples/run_og_idn.py`. |
25 | 30 |
|
26 | 31 | ## Repo conventions |
27 | 32 |
|
| 33 | +- `pyproject.toml` is the source of truth for dependencies. `uv.lock` pins exact versions across machines and is checked in. |
28 | 34 | - The packaged JSON default parameters are the standard baseline input for offline/default runs. |
29 | | -- Calibration-related changes can affect macro parameters, demographics, earnings distribution, and industry I/O behavior. |
30 | | -- Changes in calibration or data-source behavior should be validated with targeted tests and, where feasible, the relevant example flows. |
| 35 | +- Calibration or data-source changes (macro parameters, demographics, earnings, industry I/O) should be validated with targeted tests and, where feasible, the relevant example flow. |
0 commit comments