From 0a1bf67bd255b2b84424bc995ba34c2a2595e6b5 Mon Sep 17 00:00:00 2001 From: mrava87 Date: Wed, 4 Feb 2026 09:24:08 +0000 Subject: [PATCH 1/2] build: added AGENTS.md file to help coding agents --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2e604f40 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# Agent Guide for PyLops + +## Project structure (high level) +- `pylops/`: core library source code. +- `pytests/`: pytest test suite (discovered via `pytests/*.py`). +- `docs/`: Sphinx documentation sources and build output. +- `examples/`: runnable examples and small scripts. +- `tutorials/`: tutorial notebooks/scripts used in docs. +- `testdata/`: data used by tests/examples. +- `build/`, `pylops.egg-info/`: build artifacts (usually not edited). + +## Common commands (prefer Makefile targets) +- `make tests`: run CPU tests with pytest. +- `make tests_cpu_ongpu`: run CPU tests on GPU systems (disables CuPy usage). +- `make tests_gpu`: run GPU tests (requires CuPy; sets TEST_CUPY_PYLOPS=1). +- `make lint`: run `flake8` on `docs/`, `examples/`, `pylops/`, `pytests/`, `tutorials/`. +- `make typeannot`: run `mypy` on `pylops/`. +- `make doc`: clean docs build artifacts and build HTML docs. +- `make docupdate`: rebuild HTML docs without a clean. +- `make servedoc`: serve docs from `docs/build/html/`. +- `make coverage`: run tests with coverage and build HTML/XML reports. + +## CI (GitHub Actions) +- `build.yaml`: main test matrix on `ubuntu-latest` and `macos-latest` for Python `3.10`–`3.13`. + - Installs dev requirements (CPU vs ARM variants), pyfftw, torch, then runs `pytest`. +- `build-mkl.yaml`: Ubuntu-only tests using Intel oneMKL via conda (Python `3.11`–`3.13`). +- `buildcupy.yaml`: self-hosted GPU job running CuPy tests (`TEST_CUPY_PYLOPS=1`). +- `flake8.yaml`: flake8 linting on `pylops/` with the same ignores/max line length as `setup.cfg`. +- `codacy-coverage-reporter.yaml`: runs tests with coverage and uploads `coverage.xml` to Codacy. +- `deploy.yaml`: builds and publishes the package to PyPI on GitHub release publish. + +## Code style and typing guidelines +- Follow `flake8` rules from `setup.cfg`: + - Max line length is 88. + - Ignored rules: `E203`, `E501`, `W503`, `E402`. + - `__init__.py` allows unused imports (`F401`, `F403`, `F405`). +- Prefer clear, PEP 8–style Python, keeping imports at the top unless there is a strong reason. +- Type checking uses `mypy` with `numpy.typing` plugin enabled. + - `mypy` runs on `pylops/` only via `make typeannot`. + - Several third-party modules are configured with `ignore_missing_imports = True` in `setup.cfg`. +- When changing APIs or adding new modules, add or update tests under `pytests/`. + +## Notes for agents +- Use Makefile targets rather than invoking tools directly where possible. +- Keep changes focused; avoid editing build artifacts or generated docs. From f03fff3e6424d726d30d6a5de997a7fea5cdfc97 Mon Sep 17 00:00:00 2001 From: mrava87 Date: Wed, 4 Feb 2026 09:34:13 +0000 Subject: [PATCH 2/2] minor: added info about contributing to AGENTS.md --- AGENTS.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2e604f40..b89d11d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,3 +43,26 @@ ## Notes for agents - Use Makefile targets rather than invoking tools directly where possible. - Keep changes focused; avoid editing build artifacts or generated docs. + +## Issue-to-PR workflow (feature contributions) +Use `docs/source/contributing.rst` as the source of truth. When taking a GitHub issue through to PR, follow this sequence: +1. Ensure dev environment is set up (per `DevInstall` in the docs). +2. Branch from `dev` for your work: + - `git checkout -b dev` +3. Implement the change and add/update tests in `pytests/`. +4. Run CPU tests: + - `make tests` +5. If a GPU is available, also run: + - `make tests_gpu` +6. Run linting: + - `make lint` +7. Update docs if functionality changes: + - `make docupdate` +8. Commit and push: + - `git add .` + - `git commit -m ""` (Conventional Commits recommended, not required) + - `git push -u origin ` +9. Open a PR and ensure it meets the PR guidelines: + - Include tests for new core routines. + - Update docs when adding functionality. + - Ensure all tests pass.