Add AGENTS.md and issue templates by ndgrigorian · Pull Request #2402 · IntelPython/dpctl

ndgrigorian · 2026-10-26T20:16:36Z

Flagged by agent readiness checking tools

Have you provided a meaningful PR description?
Have you added a test, reproducer or referred to an issue with a reproducer?
Have you tested your changes locally for CPU and GPU devices?
Have you made sure that new changes do not introduce compiler warnings?
Have you checked performance impact of proposed changes?
Have you added documentation for your changes, if necessary?
Have you added your changes to the changelog?
If this PR is a work in progress, are you opening the PR as a draft?

ndgrigorian · 2026-10-26T20:16:48Z

@jharlow-intel
Take a look if you have thoughts

github-actions · 2026-10-26T20:20:14Z

View rendered docs @ https://intelpython.github.io/dpctl/pulls/2402/index.html

coveralls · 2026-10-26T20:22:40Z

coverage: 74.989%. remained the same — agentify-dpctl into master

jharlow-intel

Thanks. Running this through our agent-readiness scanners and checking the documented commands turned up a few changes that are probably needed.

Flagged by agent readiness checking tools

ndgrigorian · 2026-10-29T20:13:23Z

@antonwolfy @vlad-perevezentsev take a look when you have a chance

antonwolfy

Thanks for adding this. I checked the commands, paths and conventions in AGENTS.md against the tree and left suggestions where they're wrong or could mislead an agent. The main ones are dpctl/_version.py listed as generated, the network access the first build needs, and the test and CHANGELOG guidance. The issue forms validate against GitHub's schema, so the comments there are minor.

antonwolfy · 2026-10-30T19:22:33Z

+  `source /opt/intel/oneapi/setvars.sh && python -m pytest dpctl/tests/...`.
+- Check visible devices: `sycl-ls`. Tests skip on missing devices/aspects; a CPU
+  OpenCL device is enough for most of the suite.
+- Python build deps: `pip install numpy cython scikit-build cmake ninja pytest "versioneer[toml]==0.29"`.


setuptools isn't listed, but build_locally.py runs setup.py build_ext and pip install -e . --no-build-isolation, and a fresh venv on Python 3.12+ doesn't have it. pybind11 is worth adding too, since otherwise CMake downloads it (FetchContent in the top-level CMakeLists.txt):

Suggested change

- Python build deps: `pip install numpy cython scikit-build cmake ninja pytest "versioneer[toml]==0.29"`.

- Python build deps: `pip install numpy cython scikit-build cmake ninja setuptools pybind11 pytest "versioneer[toml]==0.29"`.

antonwolfy · 2026-10-30T19:22:33Z

+## Commands
+
+- Build in place + editable install: `python scripts/build_locally.py --verbose`
+  - defaults to `icx`/`icpx` on `PATH`; other compilers need `--compiler-root`


It seems --compiler-root is only required when --c-compiler/--cxx-compiler aren't absolute paths (resolve_compilers in scripts/_build_helper.py), and it's joined with the compiler name, so it has to be the directory with the binaries (CI passes .../dpcpp_compiler/bin in os-llvm-sycl-build.yml):

Suggested change

- defaults to `icx`/`icpx` on `PATH`; other compilers need `--compiler-root`

- defaults to `icx`/`icpx` on `PATH`; for other compilers pass absolute

`--c-compiler`/`--cxx-compiler` paths, or names plus `--compiler-root=<bin dir>`

antonwolfy · 2026-10-30T19:22:33Z

+- Build in place + editable install: `python scripts/build_locally.py --verbose`
+  - defaults to `icx`/`icpx` on `PATH`; other compilers need `--compiler-root`
+  - `--debug`, `--clean`, `--target-cuda[=sm_XX]`, `--target-hip=<arch>`,
+    `--cmake-opts="-D..."`


Should we mention that the first configure needs network access? Level Zero is on by default and GetLevelZeroHeaders.cmake does a git clone of its headers, and pybind11 is downloaded when it isn't installed. In a sandbox this ends in a fairly confusing CMake error.

Suggested change

`--cmake-opts="-D..."`

`--cmake-opts="-D..."`

- the first configure clones the Level Zero headers and downloads pybind11;

offline, pass `--no-level-zero` (or

`--cmake-opts="-DDPCTL_LEVEL_ZERO_INCLUDE_DIR=<dir>"`) and install `pybind11`

antonwolfy · 2026-10-30T19:22:33Z

+  - one file: `python -m pytest dpctl/tests/test_sycl_queue.py`
+  - one test: `python -m pytest dpctl/tests/test_sycl_queue_memset.py::test_memset_partial_count`
+  - without a C compiler/Cython: add `-k "not test_cython_api and not test_c_headers"`
+- C API tests (GoogleTest, needs `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`


Nit: libsyclinterface/tests/CMakeLists.txt just does find_package(GTest REQUIRED), so a system GoogleTest works as well and GTEST_ROOT is only one way to point at it. The script is also Linux only:

Suggested change

- C API tests (GoogleTest, needs `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`

- C API tests (Linux; GoogleTest must be findable by CMake, e.g. via `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`

antonwolfy · 2026-10-30T19:22:33Z

+- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):
+  `python scripts/gen_coverage.py --oneapi`


--oneapi is already the default (CI runs plain python scripts/gen_coverage.py --verbose). Maybe also say that it runs the whole pytest suite at the end and leaves the in-place build instrumented (build_ext --inplace with the Coverage build type)?

Suggested change

- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):

`python scripts/gen_coverage.py --oneapi`

- Coverage (Linux; C + Python, rebuilds in place with `-DDPCTL_BUILD_CAPI_TESTS=ON`,

then runs the full pytest suite unless `--skip-pytest`): `python scripts/gen_coverage.py`,

then `python scripts/build_locally.py --clean` for a normal build

antonwolfy · 2026-10-30T19:22:34Z

+    id: devices
+    attributes:
+      label: Devices
+      description: Output of `python -m dpctl -f`


Same here:

Suggested change

description: Output of `python -m dpctl -f`

description: Output of `python -m dpctl -f` (or `sycl-ls` if dpctl fails to import)

antonwolfy · 2026-10-30T19:22:34Z

+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ compiler version if built from source.


python -m dpctl -f shows the driver versions but not the DPC++ runtime version, which often matters for dpctl issues. Should we ask for it?

Suggested change

description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ compiler version if built from source.

description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ runtime version (`intel-sycl-rt` in `conda list`/`pip list`), DPC++ compiler version if built from source.

antonwolfy · 2026-10-30T19:22:34Z

+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered


Nit: the last field has no description:

Suggested change

label: Alternatives considered

label: Alternatives considered

description: Optional. Workarounds you use today, or other designs you considered.

antonwolfy · 2026-10-30T19:22:34Z

+blank_issues_enabled: true
+contact_links:
+  - name: Questions and discussions
+    url: https://github.com/IntelPython/dpctl/discussions


Nit: maybe link straight to the Q&A category?

Suggested change

url: https://github.com/IntelPython/dpctl/discussions

url: https://github.com/IntelPython/dpctl/discussions/categories/q-a

antonwolfy · 2026-10-30T19:22:34Z

+.venv/
+venv/
+.pytest_cache/
+.env


Nit: .env.local and similar variants aren't covered:

Suggested change

.env

.env

.env.*

ndgrigorian requested review from antonwolfy and vlad-perevezentsev as code owners October 26, 2026 20:16

ndgrigorian mentioned this pull request Oct 26, 2026

Introducing AGENTS.md #2233

Closed

2 tasks done

jharlow-intel reviewed Oct 26, 2026

View reviewed changes

Comment thread AGENTS.md Resolved

Comment thread AGENTS.md Resolved

Comment thread .gitignore Resolved

Comment thread AGENTS.md Resolved

ndgrigorian requested a review from jharlow-intel October 27, 2026 18:22

ndgrigorian added 2 commits October 29, 2026 13:13

Add AGENTS.md and templates

0e32ec9

Flagged by agent readiness checking tools

Apply review comments

71277bb

ndgrigorian force-pushed the agentify-dpctl branch from 36da929 to 71277bb Compare October 29, 2026 20:13

antonwolfy reviewed Oct 30, 2026

View reviewed changes

	- Python build deps: `pip install numpy cython scikit-build cmake ninja pytest "versioneer[toml]==0.29"`.
	- Python build deps: `pip install numpy cython scikit-build cmake ninja setuptools pybind11 pytest "versioneer[toml]==0.29"`.

	- defaults to `icx`/`icpx` on `PATH`; other compilers need `--compiler-root`
	- defaults to `icx`/`icpx` on `PATH`; for other compilers pass absolute
	`--c-compiler`/`--cxx-compiler` paths, or names plus `--compiler-root=<bin dir>`

-    `--cmake-opts="-D..."`
+    `--cmake-opts="-D..."`
+  - the first configure clones the Level Zero headers and downloads pybind11;
+    offline, pass `--no-level-zero` (or
+    `--cmake-opts="-DDPCTL_LEVEL_ZERO_INCLUDE_DIR=<dir>"`) and install `pybind11`

	- C API tests (GoogleTest, needs `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`
	- C API tests (Linux; GoogleTest must be findable by CMake, e.g. via `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`

		- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):
		`python scripts/gen_coverage.py --oneapi`

-- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):
-  `python scripts/gen_coverage.py --oneapi`
+- Coverage (Linux; C + Python, rebuilds in place with `-DDPCTL_BUILD_CAPI_TESTS=ON`,
+  then runs the full pytest suite unless `--skip-pytest`): `python scripts/gen_coverage.py`,
+  then `python scripts/build_locally.py --clean` for a normal build

	description: Output of `python -m dpctl -f`
	description: Output of `python -m dpctl -f` (or `sycl-ls` if dpctl fails to import)

	description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ compiler version if built from source.
	description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ runtime version (`intel-sycl-rt` in `conda list`/`pip list`), DPC++ compiler version if built from source.

	label: Alternatives considered
	label: Alternatives considered
	description: Optional. Workarounds you use today, or other designs you considered.

	url: https://github.com/IntelPython/dpctl/discussions
	url: https://github.com/IntelPython/dpctl/discussions/categories/q-a

Conversation

ndgrigorian commented Oct 26, 2026

Uh oh!

ndgrigorian commented Oct 26, 2026

Uh oh!

github-actions Bot commented Oct 26, 2026

Uh oh!

coveralls commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jharlow-intel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ndgrigorian commented Oct 29, 2026

Uh oh!

antonwolfy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

coveralls commented Oct 26, 2026 •

edited

Loading