|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Documentation |
| 4 | +- See the root `README.md` → “Project Overview” for a map of directories, and consult subdirectory READMEs for local nuances; follow those layouts when adding code. |
| 5 | +- Keep all README files, `docs/`, and this AGENTS.md in sync whenever tooling or behavior changes. |
| 6 | +- Prefer extending existing utilities in `scripts/` before adding new helper modules. |
| 7 | + |
| 8 | +## Workflow & Tooling |
| 9 | +- Make sure your local environment is bootstrapped with `poetry install --extras dev` and `poetry run pre-commit install`; once that’s done on a machine, you shouldn’t need to repeat it unless dependencies change. |
| 10 | +- Prefix every repo command with `poetry run` to match CI. |
| 11 | +- Re-run `poetry run pytest` locally as part of your development loop; `pyproject.toml` already wires markers, doctests, coverage, and env vars. |
| 12 | +- The pre-commit hooks you enabled during onboarding run automatically; still run `poetry run pre-commit run --all-files` before opening a PR or when new hooks land so your tree matches `.pre-commit-config.yaml` and the checks in `.github/workflows/tidy3d-python-client-tests.yml` (covers `ruff format`, `ruff check`, doc hooks). |
| 13 | + |
| 14 | +### Do / Don't |
| 15 | +- **Do** run `poetry run pre-commit run --all-files` before opening a PR; **don't** skip it even if individual hooks passed earlier. |
| 16 | +- **Do** stick to `poetry run …` commands; **don't** invoke tools outside Poetry, since that drifts from CI environments. |
| 17 | +- **Do** reuse `scripts/` utilities; **don't** add new helper modules without checking for an existing script first. |
| 18 | + |
| 19 | +## Coding Style & Naming |
| 20 | +- Favor descriptive `snake_case` functions and `PascalCase` classes tied to the physics domain. |
| 21 | +- Most simulation and monitor classes subclass `Tidy3dBaseModel`; reserve `pydantic.BaseModel` for lightweight helpers (see `tidy3d/updater.py`), and rely on `.updated_copy(...)` plus shared validators in `tidy3d/components/validators.py`. |
| 22 | +- Public APIs covered in `docs/` should use the existing Numpy-inspired block pattern rendered by our Sphinx Book Theme; lean on current API examples or the theme reference at https://sphinx-book-theme.readthedocs.io/en/stable/reference/api-numpy.html. Internal helpers may keep short docstrings but match local tone. |
| 23 | +- Prefer `tidy3d.log.log` and `tidy3d.exceptions` for contributor-facing messages; touch stdlib `logging` only when muting external libraries such as `pyroots`. |
| 24 | +- Reuse types from `tidy3d/components/types`, domain constants from `tidy3d/constants`, and runtime defaults from `tidy3d/config`. |
| 25 | + |
| 26 | +## Testing Guidelines |
| 27 | +- Mirror the source tree with `test_<feature>.py`, add a short module docstring, and import `tidy3d as td`; keep single-use fixtures local but upstream broadly useful helpers into `tests/conftest.py`. |
| 28 | +- Lean on `tests/conftest.py` for RNG seeding, matplotlib cleanup, logger reset, and autograd helpers, and use pytest’s `tmp_path` for artifacts. |
| 29 | +- `poetry run pytest` is the canonical entry point; the `pyproject` config already selects markers, doctests, coverage, xdist, and env vars, so reproduce CI locally before opening a PR. |
| 30 | +- Prefer pytest primitives (`pytest.raises`, `pytest.approx`, `@pytest.mark.parametrize`) for coverage, and add doctest snippets for new public APIs to keep docs and runtime behavior aligned. |
| 31 | +- Mock all external/web APIs in tests (e.g., `web.run`, HTTP clients) and assert the contract instead of hitting live services; CI must stay hermetic. |
| 32 | +- Numerical tests require explicit maintainer confirmation. They run real simulations and are excluded by default (`-m 'not numerical'`). When approved, run selectively via `poetry run pytest -m numerical path/to/test.py -k specific_case`. |
| 33 | +- Scope tests by path: `poetry run pytest -q tests/test_web/` or `poetry run pytest -q tidy3d/components/geometry/`. |
| 34 | +- Scope tests by keyword: `poetry run pytest -q -k "feature_name or module_name"`. |
| 35 | +- Keep repo defaults (incl. xdist); for speed disable coverage and mute warnings: `poetry run pytest -q --no-cov -W ignore tests/... --maxfail=1`. |
| 36 | +- Doctest a single module quickly: `poetry run pytest -q --no-cov -W ignore tidy3d/components/foo.py`. |
| 37 | + |
| 38 | +## Schema Assets |
| 39 | +- Files under `schemas/` are generated artifacts; never edit them manually. |
| 40 | +- Run `poetry run python scripts/regenerate_schema.py` after model/serialization changes, and commit the output alongside the code. |
| 41 | +- CI reruns the script and fails the PR whenever checked-in schemas drift from regenerated results. |
| 42 | + |
| 43 | +## Commit & Pull Request Guidelines |
| 44 | +- Follow Conventional Commits per `.commitlintrc.json`. |
| 45 | +- Branch names must use an allowed prefix (`chore`, `hotfix`, `daily-chore`) or include a Jira key to satisfy CI. |
| 46 | +- PRs should link issues, summarize behavior changes, list the `poetry run …` checks you executed, and call out docs/schema updates. |
| 47 | + |
| 48 | +_Reminder: update this AGENTS.md whenever workflow, tooling, or review expectations change so agents stay in sync with the repo._ |
0 commit comments