diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7107216 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# NPS-ActiveSpace — Code conventions for humans and LLM agents + +NPS-ActiveSpace is a scientific Python package for modeling geographic extent of audibility from a given point using sound pressure level and causal data. It also includes related library functionality and visualization capabilities. + +See [README.md](README.md) for detailed background and installation instructions. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for PR workflow. + +## Repo layout + +- **Source**: `nps_active_space/` at the repo root. The codebase includes general library utils as well as workflow scripts (under `scripts/`). +- **Tests**: `tests/` — mirrors source paths; test file names mirror source modules +- **Config**: ConfigParser `.config` files in `nps_active_space/config/`; copy `template.config` to `.config` and pass `-e ` to scripts. +- **Scripts**: run from the repo root, e.g. `python nps_active_space/scripts/run_ground_truthing.py -e DENA ...`. See [nps_active_space/scripts/README.md](nps_active_space/scripts/README.md) for more details on each script + example invocations. + +## General Code Conventions +- Scientific logic lives in library modules (`active_space/`, `ground_truthing/`, `utils/`, `validation/`). Scripts handle argparse, config, then pass data and paths into library functions. +- Prefer concise, single-responsibility functions, classes, and modules. If one piece of logic gets too large, break it up into multiple clearly-named smaller ones. +- Don't leave comments that just restate the code. They should be used for scientific concepts, non-obvious geospatial operations, or to explain decisions. +- Units should be clearly specified in variable names (e.g., `altitude_m`, `EVENT_GAP_SECONDS`, `elapsed_seconds`). Unit conversions should live in clearly named functions (e.g. `feet_to_meters`, `seconds_to_hours`) + + +## Python Code Conventions +- Target Python 3.12. +- Use modern type hints for all function signatures: `list[X]`, `dict[str, X]`, `X | None`. Not `typing.List`, `typing.Optional`. +- Prefer `match`/`case` for handling enum values or exhaustive case matching. +- Name DataFrames for what they hold (e.g. `sorted_mxak_points`, `flight_tracks`), not just `df`. +- Use `pathlib` and ensure cross-platform path support for any code dealing with file system paths. +- Timestamps are currently stored as tz-naive. Data parsers should return UTC-naive. See our [UTC standardization issue](https://github.com/dbetchkal/NPS-ActiveSpace/issues/96) for desired future state. + +## Testing + +- `pytest` from the repo root with an activated venv. +- Group related tests into classes (`class TestX:`). +- DataFrames: use pandas or geopandas `testing.assert_frame_equal` against an expected result for test assertions on dataframe results. For narrow tests, assert a single field or created an expected dataframe with a subset of columns. +- New logic should ship with tests. If something is difficult to test in a unit test (physics model subprocess, GUI, external binaries), mention it in the PR description explaining why. +- Document any manual testing/verification that you do in PR descriptions. + +## Git +- Keep commits logically scoped. +- After a squash-merge, rebase dependent PRs with the `--onto` flag to minimize merge conflicts: `git rebase --onto `. + +## Additional agent instructions + +- Activate `.venv` before running Python commands. +- Run `pytest` after code changes. Don't mark work complete without passing tests. +- Keep changes small and scoped. Don't refactor unrelated code or rename/move files without maintainer sign-off. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b8777d6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing + +If you're not sure where to start, take a scan through our [GitHub Issues](https://github.com/dbetchkal/NPS-ActiveSpace/issues) and see if anything catches your eye! + +If you're interested in making a larger-scale change, please consider creating a new issue or commenting on existing one to discuss with the repo maintainers. We'd love to meet you and hear about what you're interested in working on! + +## Setup + +Install as described in the [README](README.md#installation). Use `pip install -e ".[dev]"` to include test tools. + +## Workflow + +1. Fork and create a branch — `feature/description` or `fix/description`. +2. New logic should ship with tests. See [Style Guide](AGENTS.md) for more details. +3. Ensure existing and new tests pass before marking a PR ready for review. GitHub actions will run against PRs pointing at main. +4. Open a pull request against `main` with a clear title and description of what changed and why. Reference any related issues. + +Prefer small, focused PRs with a concise, clear description. + +## Code style + +See [`AGENTS.md`](AGENTS.md) for Python conventions, naming, type hints, testing patterns, and git workflow. + +## License + +This project is [public domain (CC0)](LICENSE.md). By submitting a pull request you waive any copyright interest in your contribution.