From 47db2af7b869d5e3eeb478169849c7988d1ce1dd Mon Sep 17 00:00:00 2001 From: arpitjain099 Date: Tue, 7 Jul 2026 09:39:16 +0900 Subject: [PATCH 1/4] Add CONTRIBUTING.md with setup and PR guidelines Signed-off-by: arpitjain099 --- CONTRIBUTING.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..62b3701 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing to NPS-ActiveSpace + +Thank you for your interest in contributing to this project. Whether you're fixing +a bug, adding a feature, or improving documentation, your help is welcome. + +## Getting started + +1. Fork and clone the repository: + + ``` + git clone https://github.com//NPS-ActiveSpace.git + cd NPS-ActiveSpace + ``` + +2. Create a virtual environment (Python 3.12+): + + ``` + python -m venv .venv + source .venv/bin/activate + ``` + +3. Install system dependencies. On Ubuntu/Debian: + + ``` + sudo apt-get install gdal-bin libgdal-dev + ``` + + On macOS with Homebrew: `brew install gdal`. The GDAL Python binding version + must match your system GDAL version. + +4. Install the project and its dependencies: + + ``` + pip install --upgrade pip + pip install -r requirements.txt + pip install -e . + pip install pytest + ``` + +5. Run the test suite to make sure everything works: + + ``` + pytest tests/ -v + ``` + +## Making changes + +- Create a feature branch from `main` (e.g. `feature/my-improvement` or `fix/issue-description`). +- Write tests for new functionality when possible. Tests live in the `tests/` directory. +- Keep commits focused. One logical change per commit is easier to review. + +## Pull requests + +When you're ready to submit your work: + +- Give the PR a clear, descriptive title. +- Explain what the change does and why it's needed in the PR description. +- Make sure CI passes (the test suite runs automatically on PRs to `main`). +- If your change relates to an open issue, reference it in the description. + +Smaller, well-scoped PRs are easier to review and more likely to be merged quickly. + +## Code style + +- Follow the patterns you see in the existing codebase. +- Python 3.12+ features are fine to use. +- Add type hints where practical, especially for function signatures. +- Configuration files use the ConfigParser `.config` format (see `nps_active_space/config/` + for examples). + +## License + +This project is in the public domain within the United States under +[CC0 1.0 Universal](LICENSE.md). All contributions will be released under the +same terms. By submitting a pull request, you agree to this waiver of copyright +interest. From 23160612fd4bb81944ca6796fcd6197fbcff90b6 Mon Sep 17 00:00:00 2001 From: Elliott Ruebush Date: Tue, 7 Jul 2026 21:20:47 -0400 Subject: [PATCH 2/4] Replace boilerplate CONTRIBUTING.md and add AGENTS.md style guide. CONTRIBUTING defers setup to the README and style to AGENTS.md. AGENTS.md documents repo layout, science-vs-plumbing conventions, and testing patterns. Co-authored-by: Cursor --- AGENTS.md | 44 ++++++++++++++++++++++++++++ CONTRIBUTING.md | 76 +++++++------------------------------------------ 2 files changed, 55 insertions(+), 65 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a29ff77 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# NPS-ActiveSpace — Code Conventions + +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. + +> Activate `.venv` before running Python commands. + +## 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, and I/O, then pass data and paths into library functions. +- Prefer concise, single-responsibility functions. If one function or class gets too large, break it into multiple smaller ones. +- Use descriptive variable and function names. +- Comments explain the unclear *why* and should be used for scientific concepts, potentially confusing geospatial operations, or non-obvious trade-offs. Don't just restate the code. +- Units should be clearly specified in variable names (e.g., `altitude_m`, `EVENT_GAP_SECONDS`, `elapsed_seconds`) + + +## Python Code Conventions +- Target Python 3.12. +- Use type hints for all new code and prefer modern type hints only: `list[X]`, `dict[str, X]`, `X | None`. Not `typing.List`, `typing.Optional`. +- Prefer `match`/`case` in named library functions for handling enums or exhaustive case matching. +- Name DataFrames for what they hold (e.g. `mxak_points`, `flight_tracks`), not `df`. + +## 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` for test assertions on dataframe results. Dataclasses/Pydantic: assert equality against an expected instance. For narrow tests, assert a single field or geometry check. +- Algorithm logic: synthetic/minimal unit tests. Real-format I/O: parametrized regression against bundled fixtures. +- New logic ships with tests. If something is difficult to test in a unit test (physics model subprocess, GUI, external binaries), mention it in the PR description and document any manual testing/verification that you do. + +## Git + +- Propose file renames, subdir moves, or structural refactors for maintainer sign-off before implementing. +- Keep commits logically scoped. +- After a squash-merge, rebase dependent PRs: `git rebase --onto `. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62b3701..b31863e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,22 @@ -# Contributing to NPS-ActiveSpace +# Contributing -Thank you for your interest in contributing to this project. Whether you're fixing -a bug, adding a feature, or improving documentation, your help is welcome. +## Setup -## Getting started +Install as described in the [README](README.md#installation). Use `pip install -e ".[dev]"` to include test tools. -1. Fork and clone the repository: +## Workflow - ``` - git clone https://github.com//NPS-ActiveSpace.git - cd NPS-ActiveSpace - ``` +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. -2. Create a virtual environment (Python 3.12+): - - ``` - python -m venv .venv - source .venv/bin/activate - ``` - -3. Install system dependencies. On Ubuntu/Debian: - - ``` - sudo apt-get install gdal-bin libgdal-dev - ``` - - On macOS with Homebrew: `brew install gdal`. The GDAL Python binding version - must match your system GDAL version. - -4. Install the project and its dependencies: - - ``` - pip install --upgrade pip - pip install -r requirements.txt - pip install -e . - pip install pytest - ``` - -5. Run the test suite to make sure everything works: - - ``` - pytest tests/ -v - ``` - -## Making changes - -- Create a feature branch from `main` (e.g. `feature/my-improvement` or `fix/issue-description`). -- Write tests for new functionality when possible. Tests live in the `tests/` directory. -- Keep commits focused. One logical change per commit is easier to review. - -## Pull requests - -When you're ready to submit your work: - -- Give the PR a clear, descriptive title. -- Explain what the change does and why it's needed in the PR description. -- Make sure CI passes (the test suite runs automatically on PRs to `main`). -- If your change relates to an open issue, reference it in the description. - -Smaller, well-scoped PRs are easier to review and more likely to be merged quickly. +Prefer small, focused PRs with a concise, clear description. ## Code style -- Follow the patterns you see in the existing codebase. -- Python 3.12+ features are fine to use. -- Add type hints where practical, especially for function signatures. -- Configuration files use the ConfigParser `.config` format (see `nps_active_space/config/` - for examples). +See [`AGENTS.md`](AGENTS.md) for Python conventions, naming, type hints, testing patterns, and git workflow. ## License -This project is in the public domain within the United States under -[CC0 1.0 Universal](LICENSE.md). All contributions will be released under the -same terms. By submitting a pull request, you agree to this waiver of copyright -interest. +This project is [public domain (CC0)](LICENSE.md). By submitting a pull request you waive any copyright interest in your contribution. From fb4816b67e2485ddae72172c3b24c480366bcc76 Mon Sep 17 00:00:00 2001 From: Elliott Ruebush Date: Wed, 8 Jul 2026 14:48:30 -0400 Subject: [PATCH 3/4] Additional tweaks to AGENTS.md and CONTRIBUTING.md --- AGENTS.md | 38 ++++++++++++++++++++------------------ CONTRIBUTING.md | 4 ++++ 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a29ff77..ecdbec8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# NPS-ActiveSpace — Code Conventions +# 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. @@ -6,8 +6,6 @@ See [README.md](README.md) for detailed background and installation instructions See [CONTRIBUTING.md](CONTRIBUTING.md) for PR workflow. -> Activate `.venv` before running Python commands. - ## Repo layout - **Source**: `nps_active_space/` at the repo root. The codebase includes general library utils as well as workflow scripts (under `scripts/`). @@ -16,29 +14,33 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for PR workflow. - **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, and I/O, then pass data and paths into library functions. -- Prefer concise, single-responsibility functions. If one function or class gets too large, break it into multiple smaller ones. -- Use descriptive variable and function names. -- Comments explain the unclear *why* and should be used for scientific concepts, potentially confusing geospatial operations, or non-obvious trade-offs. Don't just restate the code. -- Units should be clearly specified in variable names (e.g., `altitude_m`, `EVENT_GAP_SECONDS`, `elapsed_seconds`) +- 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 type hints for all new code and prefer modern type hints only: `list[X]`, `dict[str, X]`, `X | None`. Not `typing.List`, `typing.Optional`. -- Prefer `match`/`case` in named library functions for handling enums or exhaustive case matching. -- Name DataFrames for what they hold (e.g. `mxak_points`, `flight_tracks`), not `df`. +- 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. ## 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` for test assertions on dataframe results. Dataclasses/Pydantic: assert equality against an expected instance. For narrow tests, assert a single field or geometry check. -- Algorithm logic: synthetic/minimal unit tests. Real-format I/O: parametrized regression against bundled fixtures. -- New logic ships with tests. If something is difficult to test in a unit test (physics model subprocess, GUI, external binaries), mention it in the PR description and document any manual testing/verification that you do. +- 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 - -- Propose file renames, subdir moves, or structural refactors for maintainer sign-off before implementing. - Keep commits logically scoped. -- After a squash-merge, rebase dependent PRs: `git rebase --onto `. +- 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 index b31863e..b8777d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,9 @@ # 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. From 7e9c00235ebefa6ff10fe2ba35da8f138bedd80c Mon Sep 17 00:00:00 2001 From: Elliott Ruebush Date: Wed, 8 Jul 2026 15:07:23 -0400 Subject: [PATCH 4/4] add bullet point on timezones --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index ecdbec8..7107216 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for PR workflow. - 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