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..144ac1e108d6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,45 @@ +# GitHub Copilot Instructions — dpnp + +## Source of truth +This file is canonical for Copilot behavior in this repository. + +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. 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 (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: +- 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..7dd0f163923f --- /dev/null +++ b/.github/instructions/build.instructions.md @@ -0,0 +1,11 @@ +--- +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/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md new file mode 100644 index 000000000000..67be4ff92aab --- /dev/null +++ b/.github/instructions/testing.instructions.md @@ -0,0 +1,20 @@ +--- +applyTo: "{dpnp/tests/**,tests_external/**}" +--- + +# Testing Instructions for GitHub Copilot + +## 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 new file mode 100644 index 000000000000..dfc8c89b0b3d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# AGENTS.md + +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. +- 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 +Below directories have local `AGENTS.md` for deeper context: +- `.github/AGENTS.md` — CI/workflow/automation context +- `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 +- `scripts/AGENTS.md` — maintenance/developer scripts +- `tests_external/AGENTS.md` — external/integration validation scope 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..ee143ac46f6f --- /dev/null +++ b/dpnp/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS.md — dpnp/ + +Core NumPy-compatible package implementation and Python/Cython-facing behavior. + +- Preserve NumPy API 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`.