chore: review

Author: jharlow-intel

CONTRIBUTING.md

@@ -1,10 +1,11 @@
 # Contributing to `mkl_fft`
 
-This document covers the development
-workflow: how to get a working build, how to run the checks, and how the code is
-laid out so a change lands in the right layer.
+This document covers the development workflow: how to get a working build, how
+to run the checks, and what to include in a pull request.
 
-For end-user installation and API usage, see [README.md](README.md). Security
+For end-user installation and API usage, see [README.md](README.md). For a map
+of the source tree, see [`AGENTS.md`](AGENTS.md), which links to the local
+`AGENTS.md` files in directories that have their own rules. Security
 vulnerabilities go through the process in [SECURITY.md](SECURITY.md).
 
 ---
@@ -17,22 +18,31 @@ NumPy. A conda environment is the least surprising way to get them:
 ```sh
 # add python=X.Y to target a specific interpreter
 conda create -n mkl_fft-dev -c conda-forge python pip mkl-devel numpy \
-    meson-python ninja cmake cython pytest scipy mkl-service
+    meson-python ninja cmake cython pytest
 conda activate mkl_fft-dev
 ```
 
 Then build in place, which reuses the environment's MKL and NumPy:
 
 ```sh
-pip install -e ".[test]" --no-build-isolation --verbose
+pip install -e . --no-build-isolation --verbose
 ```
 
 `pyproject.toml` defines the supported Python range, and
 `.github/workflows/build_pip.yml` is canonical for the versions CI covers.
 
-The `[test]` extra pulls in `pytest`, `scipy`, and `mkl-service`. Other extras
-are declared in `pyproject.toml`: `scipy_interface` for the SciPy adapter at
-runtime and `benchmark` for the ASV suite.
+SciPy and `mkl-service` are optional. They are needed only for the
+`mkl_fft.interfaces.scipy_fft` adapter, and the tests that exercise it are
+skipped without them. To use or test the SciPy interface, add both to the
+environment:
+
+```sh
+conda install -c conda-forge scipy mkl-service
+```
+
+The matching pip extras are declared in `pyproject.toml`: `scipy_interface` for
+the SciPy adapter, `test` for `pytest` plus both packages, and `benchmark` for
+the ASV suite.
 
 `README.md` documents the non-editable install paths, including the isolated
 build that resolves its own `mkl` and `numpy`.
@@ -53,78 +63,19 @@ pre-commit run --all-files    # lint and format hooks
 ```
 
 Install the hooks once with `pre-commit install` and they run on each commit.
-`.pre-commit-config.yaml` is the source of truth for the tooling; today it
-covers `black`, `isort`, `flake8`, `pylint` (errors only), `cython-lint`,
-`clang-format`, `codespell`, `shellcheck`, `gitleaks`, and `actionlint`. Line
-length is 80 for Python, Cython, and TOML.
-
-### What CI runs
-
-`.github/workflows/*.yml` is canonical for platform and Python matrices. In
-outline:
+`.pre-commit-config.yaml` is the source of truth for the tooling.
 
-| Workflow | Purpose |
-| --- | --- |
-| `conda-package.yml` | conda build and test against the Intel channel |
-| `conda-package-cf.yml` | conda build and test against conda-forge only |
-| `build_pip.yml` | editable pip build, including pre-release NumPy |
-| `build-with-clang.yml` | build with the IntelLLVM `icx` compiler |
-| `build-with-standard-clang.yml` | build with upstream clang |
-| `pre-commit.yml` | lint and format |
-| `coverity.yml` | static analysis (see `coverity/README.md`) |
-| `openssf-scorecard.yml`, `zizmor.yml` | supply-chain and workflow security |
+Opening a pull request also runs CI, which builds and tests the package across
+platforms and Python versions and runs various lint and static-analysis checks.
 
-To reproduce a conda packaging failure locally, build the recipe the same way CI
-does — `conda build --python <ver> --numpy <ver> -c <channels> --override-channels conda-recipe`
-(or `conda-recipe-cf` for the conda-forge variant). The recipe directories are
-canonical for packaging intent and dependency pins.
+## Code style
 
-## How the code fits together
-
-Build configuration lives in `pyproject.toml` (with `meson-python` as the build
-backend) and `meson.build`. The version is read from `mkl_fft/_version.py` by
-`meson.build`, so that file is the single place a version is set.
-
-A transform call flows down through these layers:
-
-```
-mkl_fft.interfaces.numpy_fft / scipy_fft   drop-in NumPy/SciPy adapters
-mkl_fft (__init__.py)                      public FFT API
-mkl_fft/_mkl_fft.py, _fft_utils.py         argument handling, normalization, dispatch
-mkl_fft/_pydfti.pyx                        Cython bindings
-mkl_fft/src/mklfft.c.src  ->  mklfft.c     C backend, generated at build time
-oneMKL DFTI
-```
+Style is loose, and the pre-commit hooks enforce most of it:
 
-Directories:
-
-- **`mkl_fft/`** — the package. `__init__.py` is the public API surface;
-  `_mkl_fft.py` and `_fft_utils.py` hold the Python-level FFT logic;
-  `_pydfti.pyx` is the Cython binding layer.
-- **`mkl_fft/src/`** — the C backend, written as `*.c.src` templates. At build
-  time `_vendored/process_src_template.py` expands `mklfft.c.src` into
-  `mklfft.c`, which is compiled into the `_pydfti` extension. The generated
-  `.c` is regenerated on every build, so only template edits survive.
-- **`mkl_fft/interfaces/`** — adapters presenting `numpy.fft`- and
-  `scipy.fft`-shaped APIs. `numpy_fft.py` and `scipy_fft.py` are the public
-  modules; the `_`-prefixed siblings are implementation. Upstream signatures and
-  semantics are the contract here.
-- **`mkl_fft/`** patching layer — `patch.py`, `with_patch.py`, `_patch_numpy.py`,
-  `_patch_startup.py`, and the `__main__.py` CLI implement the monkey-patching
-  entry points documented in the README. The contract is that patching stays
-  reversible and observable: anything installed can be uninstalled, and
-  `is_patched()` reports the truth.
-- **`mkl_fft/tests/`** — the suite. `helper.py` holds shared utilities and
-  `third_party/` carries tests adapted from upstream projects.
-- **`_vendored/`** — build-time code-generation helpers vendored from NumPy.
-  They are excluded from `black` and `isort` in `pyproject.toml`.
-- **`conda-recipe/`**, **`conda-recipe-cf/`** — Intel-channel and conda-forge
-  packaging.
-- **`benchmarks/`** — ASV benchmarks, run with the `benchmark` extra.
-
-Each of these directories has an `AGENTS.md` stating the same boundaries for
-coding agents; [`AGENTS.md`](AGENTS.md) at the root indexes them and is a useful
-orientation map for humans too.
+- Python and Cython are formatted with `black` and `isort`, with a line length
+  of 80.
+- C sources follow the repository's `.clang-format`.
+- Otherwise, match the surrounding code.
 
 ## Dos and don'ts
 
@@ -137,8 +88,10 @@ orientation map for humans too.
 - Add tests in `mkl_fft/tests/` alongside behavior changes, and a regression
   test with every bug fix.
 - Keep tests deterministic.
-- Edit the `*.c.src` templates for C backend changes.
-- Keep patching reversible and observable.
+- Edit the `*.c.src` templates in `mkl_fft/src/` for C backend changes. The
+  `.c` files are generated from them on every build.
+- Keep patching reversible and observable: anything installed can be
+  uninstalled, and `is_patched()` reports the truth.
 - Cite the source-of-truth file for mutable details: `pyproject.toml`,
   `meson.build`, `conda-recipe*/meta.yaml`, `.github/workflows/`.
 - Give benchmark numbers reproducible context — hardware, versions, and the

README.md

@@ -170,5 +170,5 @@ pip install scipy
 # Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow: setting up a
-build environment, running the tests and lint hooks, how the Python, Cython, and
-C template layers fit together, and what to include in a pull request.
+build environment, running the tests and lint hooks, code style, and what to
+include in a pull request.