Skip to content

Add AGENTS.md and issue templates #2402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ndgrigorian wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add AGENTS.md and issue templates #2402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e32ec9
Add AGENTS.md and templates
ndgrigorian Oct 26, 2026
71277bb
Apply review comments
ndgrigorian Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Bug report
description: Report incorrect behavior, a crash, or a build failure
labels: ["bug"]
body:
- type: textarea
id: description
attributes:
label: Description
description: What happened, and what did you expect?
validations:
required: true
- type: textarea
id: reproducer
attributes:
label: Reproducer
description: Minimal code or commands that trigger the problem.
render: python
validations:
required: true
- type: textarea
id: output
attributes:
label: Output
description: Full traceback or error output. Run with `DPCTL_VERBOSITY=warning` for C API diagnostics.
render: shell
- type: input
id: version
attributes:
label: dpctl version
description: Output of `python -c "import dpctl; print(dpctl.__version__)"`

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The form also covers build failures (line 2), but this and the Devices field are required and both need a working import dpctl. Maybe add a fallback?

Suggested change
description: Output of `python -c "import dpctl; print(dpctl.__version__)"`
description: Output of `python -c "import dpctl; print(dpctl.__version__)"`, or N/A if dpctl fails to build or import

validations:
required: true
- type: textarea
id: devices
attributes:
label: Devices
description: Output of `python -m dpctl -f`

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

render: shell
validations:
required: true
- type: textarea
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.

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

validations:
required: true
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: true
contact_links:
- name: Questions and discussions
url: https://github.com/IntelPython/dpctl/discussions

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

about: Ask usage questions here.
- name: Security vulnerabilities
url: https://github.com/IntelPython/dpctl/blob/master/SECURITY.md
about: Report security issues privately, not as public issues.
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: Feature request
description: Propose new SYCL functionality or an API change
labels: ["enhancement"]
body:
- type: textarea
id: motivation
attributes:
label: Motivation
description: What do you need to do that dpctl does not support today?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed API
description: Python, Cython, or C API you would like, and the SYCL feature it maps to.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

10 changes: 10 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,13 @@ dpctl/resources/cmake

# asv artifacts
*.asv*

# agent-related
.claude/settings.local.json
.claude/worktrees/

# virtual environments, test caches, local env files
.venv/
venv/
.pytest_cache/
.env

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Suggested change
.env
.env
.env.*

125 changes: 125 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# AGENTS.md

dpctl is a Python/Cython wrapper over a subset of SYCL, built on a C API
library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icpx`).

## Environment

- Activate the compiler before building or testing: `source /opt/intel/oneapi/setvars.sh`
(or use a conda env with `dpcpp_linux-64`). The environment does not persist
between shell invocations; source it in the same command:
`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"`.

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"`.


## Commands

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

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>`

- `--debug`, `--clean`, `--target-cuda[=sm_XX]`, `--target-hip=<arch>`,
`--cmake-opts="-D..."`

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`

- Python tests: `python -m pytest dpctl/tests`
- 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)`

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)`

- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):
`python scripts/gen_coverage.py --oneapi`
Comment on lines +27 to +28

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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

- Docs (needs doxyrest): `python scripts/gen_docs.py --doxyrest-root=<path>`

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doxyrest seems optional: gen_docs.py only enables it when --doxyrest-root is passed, and docs/CMakeLists.txt falls back to a template index without it. What it does need is Sphinx and Doxygen (both find_package(... REQUIRED)), and the script errors out on non-Linux:

Suggested change
- Docs (needs doxyrest): `python scripts/gen_docs.py --doxyrest-root=<path>`
- Docs (Linux only; needs Doxygen and the `docs` extras from `pyproject.toml`):
`python scripts/gen_docs.py`, plus `--doxyrest-root=<path>` for the C API reference

- Lint/format one file (no build needed): `pre-commit run --files <path>`
- Lint/format everything: `pre-commit run --all-files`
(black, isort, flake8, cython-lint, clang-format, codespell, bandit, shellcheck,
gitleaks, actionlint). Config: `pyproject.toml`, `.flake8`, `.clang-format`.

## Structure

- `libsyclinterface/` — C API over SYCL (C++ implementation)
- `include/syclinterface/*.h` — public C headers, `DPCTL<Type>_<Op>` functions
- `source/*.cpp` — implementations
- `tests/*.cpp` — GoogleTest suite; `*.spv` are prebuilt kernel fixtures
- `dpctl/` — Python package
- `_backend.pxd` — Cython `extern` declarations of the C API
- `_sycl_*.pyx/.pxd` — `SyclDevice`, `SyclQueue`, `SyclContext`, `SyclEvent`, ...
- `memory/` — USM memory objects (`MemoryUSMDevice`, ...), IPC memory
- `compiler/` — `SyclKernelBundle` creation (SPIR-V, SYCL source)
- `program/` — deprecated alias of `dpctl.compiler`
- `utils/` — order manager, device queries, Intel device info
- `apis/include/` — Python C-API headers for extensions (`dpctl_capi.h`, `dpctl4pybind11.hpp`)
- `tests/` — pytest suite; `tests/helper/` has `get_queue_or_skip` and friends
- `examples/` — python, cython, pybind11, c extension examples (each with README)
- `docs/doc_sources/` — Sphinx sources
- `conda-recipe/`, `conda-recipe-cf/` — conda packaging used by CI
- `scripts/` — build, coverage, docs drivers

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: benchmarks/ and cmake/ are missing here, and so is libsyclinterface/helper/ (error handlers and utils), which line 72 refers to.

Suggested change
- `scripts/` — build, coverage, docs drivers
- `scripts/` — build, coverage, docs drivers
- `benchmarks/` — asv benchmarks
- `cmake/` — CMake config for downstream projects (`dpctl-config.cmake`)


## Adding a SYCL feature (typical PR shape)

1. Declare in `libsyclinterface/include/syclinterface/dpctl_sycl_<x>_interface.h`
with a Doxygen comment and ownership attributes.

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both reference PRs below extended the existing dpctl_sycl_<x>_interface.* and test_sycl_<x>_interface.cpp files, so maybe say that explicitly? Otherwise an agent may create new files:

Suggested change
with a Doxygen comment and ownership attributes.
with a Doxygen comment and ownership attributes. For an existing SYCL type,
extend its files in steps 1-4 rather than creating new ones.

2. Implement in `libsyclinterface/source/dpctl_sycl_<x>_interface.cpp`.
3. Add GoogleTest cases in `libsyclinterface/tests/test_sycl_<x>_interface.cpp`.
4. Declare in `dpctl/_backend.pxd`; wrap in `dpctl/_sycl_<x>.pyx` (and `.pxd` if
the method is `cdef`).
Comment on lines +61 to +62

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gh-2361 declares cpdef memset/memset_async in _sycl_queue.pxd, so the .pxd is needed for cpdef too:

Suggested change
4. Declare in `dpctl/_backend.pxd`; wrap in `dpctl/_sycl_<x>.pyx` (and `.pxd` if
the method is `cdef`).
4. Declare in `dpctl/_backend.pxd`; wrap in `dpctl/_sycl_<x>.pyx` (and `.pxd` if
the method is `cdef` or `cpdef`).

5. Add pytest coverage in `dpctl/tests/`.
6. Add a `CHANGELOG.md` entry with the PR link.
Comment on lines +63 to +64

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gh-2324 also touched dpctl/__init__.py and docs/doc_sources/api_reference/dpctl/constants.rst, which these steps miss. And line 111 limits CHANGELOG entries to user-visible changes, while this step reads as unconditional:

Suggested change
5. Add pytest coverage in `dpctl/tests/`.
6. Add a `CHANGELOG.md` entry with the PR link.
5. Add pytest coverage in `dpctl/tests/`.
6. Export new public names (e.g. enums) in `dpctl/__init__.py` and list them in
`docs/doc_sources/api_reference/dpctl/*.rst`.
7. For user-visible changes, add a `CHANGELOG.md` entry (see Git).


Reference PRs to copy from:
- New queue operation: gh-2361 (`DPCTLQueue_Memset` → `SyclQueue.memset`,
`dpctl/tests/test_sycl_queue_memset.py`).
Comment on lines +67 to +68

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: DPCTLQueue_Memset already existed before gh-2361; it added DPCTLQueue_MemsetWithEvents for memset_async:

Suggested change
- New queue operation: gh-2361 (`DPCTLQueue_Memset` → `SyclQueue.memset`,
`dpctl/tests/test_sycl_queue_memset.py`).
- New queue operation: gh-2361 (`DPCTLQueue_MemsetWithEvents` →
`SyclQueue.memset`/`memset_async`, `dpctl/tests/test_sycl_queue_memset.py`).

- New device info query: gh-2324 (`dpctl_sycl_device_interface.h` →
`dpctl/_sycl_device.pyx`; register the check in
`dpctl/tests/_device_attributes_checks.py`). New enums go through
Comment on lines +70 to +71

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we be more specific about how to register it? It's a check_<name>(device) function appended to list_of_checks, which the check fixture at the end of that file is parametrized over:

Suggested change
`dpctl/_sycl_device.pyx`; register the check in
`dpctl/tests/_device_attributes_checks.py`). New enums go through
`dpctl/_sycl_device.pyx`; add a `check_<name>(device)` to `list_of_checks` in
`dpctl/tests/_device_attributes_checks.py`). New enums go through

`dpctl_sycl_enum_types.h`, `libsyclinterface/helper/`, and `dpctl/enum_types.py`.

## Conventions

### C API
Comment thread
ndgrigorian marked this conversation as resolved.
Resolved
- Opaque refs (`DPCTLSyclQueueRef`, ...) via `wrap<T>`/`unwrap<T>`
(`dpctl_sycl_type_casters.hpp`).
- Annotate ownership: `__dpctl_give` (caller must delete), `__dpctl_take`
(callee consumes), `__dpctl_keep` (borrowed). See `Support/MemOwnershipAttrs.h`.
- Never let a C++ exception cross the C boundary: catch, call
`error_handler(e, __FILE__, __func__, __LINE__)`, return `nullptr`/error value.
- Null-check every incoming ref and report via `error_handler`.
- Errors are silent unless `DPCTL_VERBOSITY=warning` (or `error`) is set; set it
when debugging a `nullptr` return.
Comment on lines +84 to +85

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With DPCTL_VERBOSITY=error the null-ref messages stay hidden: they go through the std::string overload of error_handler, which defaults to error_level::warning (libsyclinterface/helper/include/dpctl_error_handlers.h). So only warning shows everything:

Suggested change
- Errors are silent unless `DPCTL_VERBOSITY=warning` (or `error`) is set; set it
when debugging a `nullptr` return.
- Errors are silent unless `DPCTL_VERBOSITY` is set; use `warning` when debugging
a `nullptr` return (`error` hides the null-ref messages).


### Cython / Python
- Release the GIL (`with nogil:`) around calls that may block on the device.
- Python-visible errors: raise specific exceptions (`TypeError`, `ValueError`,
`SyclQueueCreationError`, ...) when the C API returns `NULL`.
- Free-threaded CPython (3.14t) is supported; do not rely on the GIL for
thread safety of shared state.
Comment on lines +91 to +92

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All .pyx files have # cython: freethreading_compatible = True; worth making it a rule for new ones?

Suggested change
- Free-threaded CPython (3.14t) is supported; do not rely on the GIL for
thread safety of shared state.
- Free-threaded CPython (3.14t) is supported; do not rely on the GIL for
thread safety of shared state. New `.pyx` files need
`# cython: freethreading_compatible = True`, like the existing ones.

- Line length 80 (black, isort, cython-lint, clang-format).

### Tests
- Get devices with `get_queue_or_skip()` / skip on missing aspects; never assume
a GPU or fp64 support.
Comment on lines +96 to +97

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only test_sycl_device.py uses get_queue_or_skip(). Most tests (93 places, including test_sycl_queue_memset.py referenced above) do try: dpctl.SyclQueue() / except dpctl.SyclQueueCreationError: pytest.skip(...). Also the helper returns a queue rather than a device:

Suggested change
- Get devices with `get_queue_or_skip()` / skip on missing aspects; never assume
a GPU or fp64 support.
- Create queues with `get_queue_or_skip()` (`dpctl/tests/helper`) or
`try: dpctl.SyclQueue()` / `except dpctl.SyclQueueCreationError: pytest.skip(...)`;
skip on missing aspects, never assume a GPU or fp64 support.

- Test both sync and `*_async` variants when adding queue operations.

### Files
- New files need the Apache-2.0 license header from `CONTRIBUTING.md`
(C/C++ headers also need the `\file` Doxygen block).
Comment on lines +101 to +102

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CONTRIBUTING.md asks for the \file block in every C API source file, and all headers, sources and tests in libsyclinterface have one. It also says the copyright year has to be kept current, while its template shows 2020:

Suggested change
- New files need the Apache-2.0 license header from `CONTRIBUTING.md`
(C/C++ headers also need the `\file` Doxygen block).
- New files need the Apache-2.0 license header from `CONTRIBUTING.md` with the
current year; all C/C++ files (not only headers) also need the `\file` Doxygen block.

- Comments and docstrings: short, describe what the code does.

## Git

- Branch off `master`; pre-commit blocks commits directly to `master` and
`maintenance/*`.
- One concern per PR; fill in `.github/pull_request_template.md`.
- Update `CHANGELOG.md` (Keep a Changelog sections: Added, Changed, Deprecated,
Removed, Fixed, Maintenance) for user-visible changes, citing `gh-NNNN`.
Comment on lines +110 to +111

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An agent can't know the PR number before the PR is opened, and the entries are links rather than bare gh-NNNN. Maybe show the format?

Suggested change
- Update `CHANGELOG.md` (Keep a Changelog sections: Added, Changed, Deprecated,
Removed, Fixed, Maintenance) for user-visible changes, citing `gh-NNNN`.
- Update `CHANGELOG.md` under `## [dev]` (Keep a Changelog sections: Added, Changed,
Deprecated, Removed, Fixed, Maintenance) for user-visible changes, e.g.
`* Added ... [gh-NNNN](https://github.com/IntelPython/dpctl/pull/NNNN)`; the
number is only known once the PR is opened.


## Boundaries

- Generated, do not edit: `dpctl/*.cxx`, `dpctl/**/*.cxx`, `dpctl/include/`
(headers copied/generated at build time), `dpctl/_version.py` (versioneer),
`_skbuild/`, `build/`.
Comment on lines +115 to +117

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dpctl/_version.py isn't generated: it's tracked in git and vendored from versioneer 0.29 ([tool.versioneer] in pyproject.toml), and changes only when versioneer is upgraded. "Do not edit" still applies, but an agent may treat it as a build artifact:

Suggested change
- Generated, do not edit: `dpctl/*.cxx`, `dpctl/**/*.cxx`, `dpctl/include/`
(headers copied/generated at build time), `dpctl/_version.py` (versioneer),
`_skbuild/`, `build/`.
- Generated, do not edit: `dpctl/*.cxx`, `dpctl/**/*.cxx`, `dpctl/include/`
(headers copied/generated at build time), `_skbuild/`, `build/`.
- `dpctl/_version.py` is a committed, vendored versioneer file; do not edit it by hand.

- Edit C headers in `libsyclinterface/include/`, not their copies under `dpctl/include/`.

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dpctl/include/ also gets copies of the dpctl/apis/include/ headers (top-level CMakeLists.txt install rule). And Config/dpctl_config.h is generated by CMake from dpctl_config.h.in:

Suggested change
- Edit C headers in `libsyclinterface/include/`, not their copies under `dpctl/include/`.
- Edit C headers in `libsyclinterface/include/` and Python C-API headers in
`dpctl/apis/include/`, not their copies under `dpctl/include/`.
`Config/dpctl_config.h` is generated from `dpctl_config.h.in`; edit the `.in`.

- In-place `.so` files survive branch switches; rebuild (`--clean`) before
trusting test results after checking out another branch.
- Changing an existing C API signature or enum value is a breaking change:
call it out in the PR and the CHANGELOG `NOTE` list.
Comment on lines +121 to +122

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no standing NOTE list in CHANGELOG.md; it only appears under released versions (e.g. 0.23.0), so an agent won't find one in [dev]:

Suggested change
- Changing an existing C API signature or enum value is a breaking change:
call it out in the PR and the CHANGELOG `NOTE` list.
- Changing an existing C API signature or enum value is a breaking change:
call it out in the PR and in a `**NOTE**: This release contains breaking changes:`
list at the top of the `[dev]` section (as under 0.23.0).

- `.github/workflows/` actions are pinned to commit SHAs (checked by zizmor);
keep that when adding steps.
- `conda-recipe*/`, release versions, and doc version lists need maintainer review.

@antonwolfy antonwolfy Oct 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What should an agent do here? Every path already needs maintainer review through CODEOWNERS, so maybe make it an instruction:

Suggested change
- `conda-recipe*/`, release versions, and doc version lists need maintainer review.
- Don't change `conda-recipe*/`, release versions, or `docs/doc_versions.txt`
unless asked; call such changes out in the PR.

Loading