From b01c43df6028cd84363fcc3a593342113cbda58a Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Wed, 18 Feb 2026 03:36:26 +0000 Subject: [PATCH 1/4] docs: add hierarchical AGENTS and copilot instructions --- .github/AGENTS.md | 7 +++++++ .github/copilot-instructions.md | 22 ++++++++++++++++++++ .github/instructions/build.instructions.md | 9 ++++++++ .github/instructions/testing.instructions.md | 9 ++++++++ AGENTS.md | 19 +++++++++++++++++ benchmarks/AGENTS.md | 7 +++++++ doc/AGENTS.md | 7 +++++++ dpnp/AGENTS.md | 7 +++++++ examples/AGENTS.md | 7 +++++++ scripts/AGENTS.md | 7 +++++++ tests_external/AGENTS.md | 7 +++++++ 11 files changed, 108 insertions(+) create mode 100644 .github/AGENTS.md create mode 100644 .github/copilot-instructions.md create mode 100644 .github/instructions/build.instructions.md create mode 100644 .github/instructions/testing.instructions.md create mode 100644 AGENTS.md create mode 100644 benchmarks/AGENTS.md create mode 100644 doc/AGENTS.md create mode 100644 dpnp/AGENTS.md create mode 100644 examples/AGENTS.md create mode 100644 scripts/AGENTS.md create mode 100644 tests_external/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 000000000000..5733f8e67d8f --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — .github/ + +CI workflows, automation, and templates. + +- Keep required checks and matrix in workflow files only. +- Keep instruction docs long-lived (no mutable values). +- Treat workflow/job renames as breaking for tooling. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000000..1818eec5460a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,22 @@ +# GitHub Copilot Instructions — dpnp + +## Source of truth +This file is canonical for Copilot behavior in this repository. + +`AGENTS.md` files provide directory scope/guardrails for AGENTS-aware tools and +should not duplicate Copilot policy text. + +## Mandatory flow +Read root `AGENTS.md`, then nearest local `AGENTS.md` for edited files; most specific wins. + +## Authoring rules +- Keep suggestions minimal and scoped. +- Use source-of-truth files for mutable details. +- Do not invent or hardcode versions, flags, or matrix values. + +## Source-of-truth files +- Build/config: `CMakeLists.txt`, `pyproject.toml`, `setup.py`, `setup.cfg` +- CI/checks: `.github/workflows/` +- Style/lint: `.pre-commit-config.yaml`, `.clang-format`, `.flake8` +- API/package paths: `dpnp/`, `doc/` +- Examples/benchmarks context: `examples/`, `benchmarks/` diff --git a/.github/instructions/build.instructions.md b/.github/instructions/build.instructions.md new file mode 100644 index 000000000000..627b6145b168 --- /dev/null +++ b/.github/instructions/build.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: "{CMakeLists.txt,pyproject.toml,setup.py,setup.cfg,**/CMakeLists.txt}" +--- + +# Build Instructions for GitHub Copilot + +- Reuse existing build/config patterns. +- Keep mutable build details in source-of-truth files. +- Avoid introducing parallel build paths unless requested. diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md new file mode 100644 index 000000000000..aa249e5f47fc --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,9 @@ +--- +applyTo: "{dpnp/tests/**,tests_external/**}" +--- + +# Testing Instructions for GitHub Copilot + +- Add regression tests for bug fixes. +- Keep tests deterministic and scoped to changed behavior. +- Prefer smallest test surface proving correctness. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..605912951c94 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md + +This file is for AGENTS-aware tools. + +Scope: +- Repository context for AGENTS-aware agents. +- Directory routing to local AGENTS files. + +For Copilot policy (flow, source-of-truth, edit hygiene), see: +- `.github/copilot-instructions.md` (canonical for Copilot behavior) + +Directory map: +- `.github/AGENTS.md` +- `dpnp/AGENTS.md` +- `doc/AGENTS.md` +- `examples/AGENTS.md` +- `benchmarks/AGENTS.md` +- `scripts/AGENTS.md` +- `tests_external/AGENTS.md` diff --git a/benchmarks/AGENTS.md b/benchmarks/AGENTS.md new file mode 100644 index 000000000000..0aba4a7bbdd3 --- /dev/null +++ b/benchmarks/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — benchmarks/ + +Benchmark scripts and performance evaluation. + +- Keep runs reproducible and inputs explicit. +- Separate harness changes from algorithm changes. +- Preserve output contracts used by downstream analysis. diff --git a/doc/AGENTS.md b/doc/AGENTS.md new file mode 100644 index 000000000000..1fc01c7694bf --- /dev/null +++ b/doc/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — doc/ + +Documentation sources and build artifacts. + +- Keep docs aligned with current public behavior. +- Prefer concise examples; avoid stale version-specific claims. +- Update docs when user-visible behavior changes. diff --git a/dpnp/AGENTS.md b/dpnp/AGENTS.md new file mode 100644 index 000000000000..5bb95edf5f88 --- /dev/null +++ b/dpnp/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — dpnp/ + +Core package implementation and Python/Cython-facing behavior. + +- Preserve API behavior and compatibility by default. +- Keep dtype/shape/error behavior explicit. +- For test policy, follow `.github/instructions/testing.instructions.md`. diff --git a/examples/AGENTS.md b/examples/AGENTS.md new file mode 100644 index 000000000000..e601a76512d3 --- /dev/null +++ b/examples/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — examples/ + +User-facing usage examples. + +- Keep examples runnable and minimal. +- Prefer clarity over micro-optimization. +- Reflect current public APIs. diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 000000000000..fda8b5e19f4a --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — scripts/ + +Developer and maintenance scripts. + +- Keep scripts automation-friendly and deterministic. +- Avoid local-machine assumptions. +- Document required env vars/inputs in-script. diff --git a/tests_external/AGENTS.md b/tests_external/AGENTS.md new file mode 100644 index 000000000000..cdd2b89dd61f --- /dev/null +++ b/tests_external/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — tests_external/ + +External/integration validation surface. + +- Keep tests focused on external/integration behavior. +- Gate feature/platform-specific assertions where needed. +- For regression policy, follow `.github/instructions/testing.instructions.md`. From 24cef9f1c6beb6b347f3c2f16982405db4b32bf3 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Wed, 18 Feb 2026 04:12:03 +0000 Subject: [PATCH 2/4] docs: expand repo/workflow guidance in agent instructions --- .github/copilot-instructions.md | 10 +++++++--- AGENTS.md | 29 +++++++++++++++++------------ 2 files changed, 24 insertions(+), 15 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1818eec5460a..a1b5bd8a015d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -3,14 +3,18 @@ ## Source of truth This file is canonical for Copilot behavior in this repository. -`AGENTS.md` files provide directory scope/guardrails for AGENTS-aware tools and -should not duplicate Copilot policy text. +`AGENTS.md` files provide directory scope/guardrails for AGENTS-aware tools and should not duplicate Copilot policy text. ## Mandatory flow Read root `AGENTS.md`, then nearest local `AGENTS.md` for edited files; most specific wins. +## Contribution expectations +- Keep diffs minimal and scoped to the task. +- Preserve API behavior by default. +- For behavior/API changes: update tests, and docs/examples when user-visible. +- For bug fixes: prefer adding regression coverage. + ## Authoring rules -- Keep suggestions minimal and scoped. - Use source-of-truth files for mutable details. - Do not invent or hardcode versions, flags, or matrix values. diff --git a/AGENTS.md b/AGENTS.md index 605912951c94..c57a534981a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,18 +2,23 @@ This file is for AGENTS-aware tools. -Scope: -- Repository context for AGENTS-aware agents. -- Directory routing to local AGENTS files. +## What this repository is +`dpnp` is the Data Parallel Extension for NumPy: a NumPy-compatible Python API with accelerated execution backends and cross-platform packaging/CI. -For Copilot policy (flow, source-of-truth, edit hygiene), see: +## How to work in this repo +- Keep changes small and single-purpose (bug fix, perf, docs, or infra). +- Preserve API behavior by default; call out intentional behavior changes in PR text. +- Pair user-visible changes with tests and docs/examples updates. +- Avoid duplicating mutable details (versions/flags/matrix) in instruction docs. + +For Copilot behavior policy (flow, source-of-truth, edit hygiene), see: - `.github/copilot-instructions.md` (canonical for Copilot behavior) -Directory map: -- `.github/AGENTS.md` -- `dpnp/AGENTS.md` -- `doc/AGENTS.md` -- `examples/AGENTS.md` -- `benchmarks/AGENTS.md` -- `scripts/AGENTS.md` -- `tests_external/AGENTS.md` +## Directory map +- `.github/AGENTS.md` — CI/workflow/automation context +- `dpnp/AGENTS.md` — core implementation behavior guardrails +- `doc/AGENTS.md` — documentation updates and consistency +- `examples/AGENTS.md` — runnable user-facing examples +- `benchmarks/AGENTS.md` — reproducible performance evaluation +- `scripts/AGENTS.md` — maintenance/developer scripts +- `tests_external/AGENTS.md` — external/integration validation scope From 6f339f9b1453e89531d2c5da5dbe1bff18ed6d68 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 03:01:43 +0000 Subject: [PATCH 3/4] docs: address review feedback (clarify entry point, NumPy focus, path resolution) --- .github/copilot-instructions.md | 11 ++++++++--- .github/instructions/build.instructions.md | 2 ++ AGENTS.md | 7 ++++--- dpnp/AGENTS.md | 4 ++-- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1b5bd8a015d..f2c3f8ad3f3d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -3,14 +3,18 @@ ## Source of truth This file is canonical for Copilot behavior in this repository. -`AGENTS.md` files provide directory scope/guardrails for AGENTS-aware tools and should not duplicate Copilot policy text. +For project context and directory routing, read root `AGENTS.md` first. + +`AGENTS.md` files provide directory scope/guardrails and should not duplicate Copilot policy text. ## Mandatory flow -Read root `AGENTS.md`, then nearest local `AGENTS.md` for edited files; most specific wins. +1. Read root `AGENTS.md`. +2. Read nearest local `AGENTS.md` for edited files. +3. Most specific AGENTS wins when multiple apply. ## Contribution expectations - Keep diffs minimal and scoped to the task. -- Preserve API behavior by default. +- Preserve NumPy-compatible API behavior by default. - For behavior/API changes: update tests, and docs/examples when user-visible. - For bug fixes: prefer adding regression coverage. @@ -19,6 +23,7 @@ Read root `AGENTS.md`, then nearest local `AGENTS.md` for edited files; most spe - Do not invent or hardcode versions, flags, or matrix values. ## Source-of-truth files +All paths relative to project root: - Build/config: `CMakeLists.txt`, `pyproject.toml`, `setup.py`, `setup.cfg` - CI/checks: `.github/workflows/` - Style/lint: `.pre-commit-config.yaml`, `.clang-format`, `.flake8` diff --git a/.github/instructions/build.instructions.md b/.github/instructions/build.instructions.md index 627b6145b168..7dd0f163923f 100644 --- a/.github/instructions/build.instructions.md +++ b/.github/instructions/build.instructions.md @@ -4,6 +4,8 @@ applyTo: "{CMakeLists.txt,pyproject.toml,setup.py,setup.cfg,**/CMakeLists.txt}" # Build Instructions for GitHub Copilot +All paths below are relative to project root. + - Reuse existing build/config patterns. - Keep mutable build details in source-of-truth files. - Avoid introducing parallel build paths unless requested. diff --git a/AGENTS.md b/AGENTS.md index c57a534981a4..d5f204ac67ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,13 @@ # AGENTS.md -This file is for AGENTS-aware tools. +Entry point for agent context in this repo. ## What this repository is `dpnp` is the Data Parallel Extension for NumPy: a NumPy-compatible Python API with accelerated execution backends and cross-platform packaging/CI. ## How to work in this repo - Keep changes small and single-purpose (bug fix, perf, docs, or infra). -- Preserve API behavior by default; call out intentional behavior changes in PR text. +- Preserve NumPy-compatible API behavior by default; call out intentional behavior changes in PR text. - Pair user-visible changes with tests and docs/examples updates. - Avoid duplicating mutable details (versions/flags/matrix) in instruction docs. @@ -15,8 +15,9 @@ For Copilot behavior policy (flow, source-of-truth, edit hygiene), see: - `.github/copilot-instructions.md` (canonical for Copilot behavior) ## Directory map +Below directories have local `AGENTS.md` for deeper context: - `.github/AGENTS.md` — CI/workflow/automation context -- `dpnp/AGENTS.md` — core implementation behavior guardrails +- `dpnp/AGENTS.md` — core NumPy-compatible implementation guardrails - `doc/AGENTS.md` — documentation updates and consistency - `examples/AGENTS.md` — runnable user-facing examples - `benchmarks/AGENTS.md` — reproducible performance evaluation diff --git a/dpnp/AGENTS.md b/dpnp/AGENTS.md index 5bb95edf5f88..ee143ac46f6f 100644 --- a/dpnp/AGENTS.md +++ b/dpnp/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — dpnp/ -Core package implementation and Python/Cython-facing behavior. +Core NumPy-compatible package implementation and Python/Cython-facing behavior. -- Preserve API behavior and compatibility by default. +- Preserve NumPy API compatibility by default. - Keep dtype/shape/error behavior explicit. - For test policy, follow `.github/instructions/testing.instructions.md`. From e6fc825f8e7a001e1569d08c480ce364518e17b4 Mon Sep 17 00:00:00 2001 From: Nikolay Petrov Date: Thu, 19 Feb 2026 03:53:23 +0000 Subject: [PATCH 4/4] docs: address comprehensive review feedback - Add precedence hierarchy for conflict resolution - Clarify multi-directory change handling - Add README/docs links for new contributors - Add explicit test coverage and regression requirements - Define user-visible changes with examples - Add validation workflow guidance --- .github/copilot-instructions.md | 22 ++++++++++++++++---- .github/instructions/testing.instructions.md | 13 +++++++++++- AGENTS.md | 4 ++++ 3 files changed, 34 insertions(+), 5 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f2c3f8ad3f3d..144ac1e108d6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,20 +7,34 @@ For project context and directory routing, read root `AGENTS.md` first. `AGENTS.md` files provide directory scope/guardrails and should not duplicate Copilot policy text. +## Precedence hierarchy (conflict resolution) +When guidance conflicts across files, apply in this order: +1. `.github/copilot-instructions.md` (this file) +2. Applicable `.github/instructions/*.instructions.md` files +3. Nearest local `AGENTS.md` for edited path +4. Root `AGENTS.md` + ## Mandatory flow 1. Read root `AGENTS.md`. -2. Read nearest local `AGENTS.md` for edited files. -3. Most specific AGENTS wins when multiple apply. +2. For each edited file, read its nearest local `AGENTS.md`. +3. If multiple directories changed, apply each scope's local AGENTS to corresponding files. +4. Most specific AGENTS wins for each file. ## Contribution expectations - Keep diffs minimal and scoped to the task. - Preserve NumPy-compatible API behavior by default. -- For behavior/API changes: update tests, and docs/examples when user-visible. -- For bug fixes: prefer adding regression coverage. +- For behavior/API changes: update tests, and docs/examples when user-visible (API signature/behavior, errors, examples output). +- For bug fixes: add regression test coverage. + +## Test and validation requirements +- Add unit/integration tests for changed code paths. +- For bug fixes: include regression tests. +- Keep tests deterministic and scoped to changed behavior. ## Authoring rules - Use source-of-truth files for mutable details. - Do not invent or hardcode versions, flags, or matrix values. +- Prefer single-purpose commits; avoid opportunistic refactors. ## Source-of-truth files All paths relative to project root: diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md index aa249e5f47fc..67be4ff92aab 100644 --- a/.github/instructions/testing.instructions.md +++ b/.github/instructions/testing.instructions.md @@ -4,6 +4,17 @@ applyTo: "{dpnp/tests/**,tests_external/**}" # Testing Instructions for GitHub Copilot -- Add regression tests for bug fixes. +## Test coverage requirements +- Add unit/integration tests for all changed code paths. +- For bug fixes: include regression tests that cover the fixed scenario. + +## Test quality - Keep tests deterministic and scoped to changed behavior. - Prefer smallest test surface proving correctness. + +## Validation workflow +Ensure tests pass locally before PR submission: +```bash +pytest dpnp/tests/ # core tests +pytest tests_external/ # integration tests +``` diff --git a/AGENTS.md b/AGENTS.md index d5f204ac67ac..dfc8c89b0b3d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,10 @@ Entry point for agent context in this repo. ## What this repository is `dpnp` is the Data Parallel Extension for NumPy: a NumPy-compatible Python API with accelerated execution backends and cross-platform packaging/CI. +For detailed documentation, build instructions, and contribution guidelines, see: +- `README.md` (project overview and quickstart) +- `CONTRIBUTING.md` (if exists, or refer to project docs) + ## How to work in this repo - Keep changes small and single-purpose (bug fix, perf, docs, or infra). - Preserve NumPy-compatible API behavior by default; call out intentional behavior changes in PR text.