diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000000..fb9d37400d --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,3 @@ +# CLAUDE.md + +@../AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..66c6457fa6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,118 @@ +# AGENTS.md + +Instructions for AI assistants and agents working with code in this +repository. + +After writing or modifying code, self-review it as a human PR reviewer +would: Is every line needed and justified? Will it be hard to maintain? +Do not present code you cannot explain. When generating substantial +algorithms or logic, note this to the human so they can disclose it in the +commit message or pull request. See the GRASS core +[AI use policy](https://github.com/OSGeo/grass/blob/main/CONTRIBUTING.md#ai-use-policy). + +## Relationship to GRASS core + +This repository holds **addons**: optional, community-maintained GRASS tools +installed by users with `g.extension`. They depend on a GRASS installation +but are built and released separately from core. As far as AI-assisted coding +is concerned, addons are held to the same quality standards as core tools +(a tool may later graduate into the core repository). + +**All core conventions apply here.** Rather than repeat them, this file +documents only what is specific to addons. For everything else, follow: + +- [GRASS core `AGENTS.md`](https://github.com/OSGeo/grass/blob/main/AGENTS.md) + — coding conventions, tool structure, documentation rules, commit messages, + and how to write tests (`grass.tools`, fixtures, test data patterns). +- [Programming Style Guide](https://github.com/OSGeo/grass/blob/main/doc/development/style_guide.md) + — full formatting and style rules. + +The development branch is `grass8`. The git/fork/PR workflow is in +[`CONTRIBUTING.md`](CONTRIBUTING.md); do not re-derive it. +Having the [core repo](https://github.com/OSGeo/grass/) locally at hand +is helpful for checking against the established conventions and already +available functions to avoid code duplication. + +## Creating a new tool + +Scaffold new addons with the +[grass-addon-cookiecutter](https://github.com/OSGeo/grass-addon-cookiecutter) +template rather than copying files by hand. It generates the standard layout +(`.py` script, `Makefile`, `.md` with synced `.html`, and a +gunittest `testsuite/`) with the correct naming. New tests are preferably +pytest in a `tests/` directory (see "Testing" below), although using +the scaffolded `testsuite/` is acceptable when NC SPM sample dataset is used. + +Tools live under `src///`, where `` is `raster`, +`vector`, `imagery`, `temporal`, `raster3d`, `display`, `general`, `db`, +`gui`, `misc`, `models`, or `tools`. The tool name prefix must match its +category (`r.*`, `v.*`, `i.*`, `t.*`, `r3.*`, `d.*`, `g.*`, `db.*`, `m.*`). +An addon directory has the same structure as a core tool (see the core +`AGENTS.md` "Tool Structure" section): `.py` or `main.c`, a `Makefile`, +`.md` (with synced `.html`), and `testsuite/`. + +## Building and installing a single addon + +Two paths, depending on what you need: + +**Compile against an installed GRASS** (what CI does). `MODULE_TOPDIR` must +point to the GISBASE of an **Autotools** install (the path from +`grass --config path`). This builds and installs the addon into that GRASS +tree: + +```bash +cd src/raster/r.example +make MODULE_TOPDIR="$(grass --config path)" +``` + +**Install into a GRASS session for interactive use or testing**, directly +from the local source directory: + +```bash +grass --tmp-project XY --exec \ + g.extension extension=r.example url=$PWD/src/raster/r.example +``` + +For a **CMake** install, the core source code needs to be installed, +not just compiled, for *g.extension* to work. + +## Testing + +Both pytest and gunittest are supported; follow the core `AGENTS.md` "Writing +Tests" for how to write either. Build or install the addon first (see above); +tests run a tool by name, so it must be on `PATH`. + +**pytest** (preferred for new tests, as in core) goes in a `tests/` +directory next to the tool, named `_test.py` or `test_.py`. Use +synthetic data and `grass.tools`. pytest configuration is in +`pyproject.toml`. Run a tool's tests with: + +```bash +export PYTHONPATH="$(grass --config python_path):${PYTHONPATH}" +export LD_LIBRARY_PATH="$(grass --config path)/lib:${LD_LIBRARY_PATH}" +pytest src/raster/r.example/tests/ +``` + +If the addon bundles a Python package (installed under +`$(grass --config path)/etc//`), add that directory to `PYTHONPATH` too +so tests can import it. Run one addon's tests at a time: each addon is a +separate process in CI, since some suites replace entries in `sys.modules` +that would otherwise leak across a shared pytest run. + +**gunittest** goes in a `testsuite/` directory and is the only option when +the test needs the `nc_spm` sample dataset. CI runs the full gunittest suite +against `nc_spm` (`.github/workflows/test.sh` → +`python3 -m grass.gunittest.main ... --min-success`). To run one suite, +install the addon (the `g.extension` command above), start a GRASS session, +and run it; the mechanics, including installing `grass-dev`/`grass-devel`, +are in +[`doc/development/submitting/UNIT_TESTS.md`](doc/development/submitting/UNIT_TESTS.md). + +## Linting, documentation, and commits + +- Lint gate, same command as core: `pre-commit run --all-files`. +- Each addon needs `.md` documentation with a synced `.html`; + follow the core documentation rules. +- Commit messages start with the tool name: `r.example: Add slope option`. + Submit a new tool together with its tests and documentation in one pull + request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e90213af7..297b593351 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,6 +121,9 @@ You can use your favourite tools to change source code or other files in the local copy of the code. When making such changes, please follow the general [GRASS GIS Programming Style Guide](https://github.com/OSGeo/grass/blob/main/doc/development/style_guide.md). +If you use an AI assistant or agent, see [`AGENTS.md`](AGENTS.md) for +project-specific instructions and conventions. + ### Committing - Add files to the commit (changed ones or new ones):