Skip to content

Commit 9b5e155

Browse files
committed
Apply review comments from antonwolfy
1 parent ae61a63 commit 9b5e155

5 files changed

Lines changed: 53 additions & 30 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,21 +27,21 @@ body:
2727
id: version
2828
attributes:
2929
label: dpctl version
30-
description: Output of `python -c "import dpctl; print(dpctl.__version__)"`
30+
description: Output of `python -c "import dpctl; print(dpctl.__version__)"`, or N/A if dpctl fails to build or import
3131
validations:
3232
required: true
3333
- type: textarea
3434
id: devices
3535
attributes:
3636
label: Devices
37-
description: Output of `python -m dpctl -f`
37+
description: Output of `python -m dpctl -f` (or `sycl-ls` if dpctl fails to import)
3838
render: shell
3939
validations:
4040
required: true
4141
- type: textarea
4242
id: environment
4343
attributes:
4444
label: Environment
45-
description: OS, Python version (and whether free-threaded), how dpctl was installed (conda/pip/source), DPC++ compiler version if built from source.
45+
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.
4646
validations:
4747
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
blank_issues_enabled: true
22
contact_links:
33
- name: Questions and discussions
4-
url: https://github.com/IntelPython/dpctl/discussions
4+
url: https://github.com/IntelPython/dpctl/discussions/categories/q-a
55
about: Ask usage questions here.
66
- name: Security vulnerabilities
77
url: https://github.com/IntelPython/dpctl/blob/master/SECURITY.md

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ body:
2020
id: alternatives
2121
attributes:
2222
label: Alternatives considered
23+
description: Optional. Workarounds you use today, or other designs you considered.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,3 +114,4 @@ dpctl/resources/cmake
114114
venv/
115115
.pytest_cache/
116116
.env
117+
.env.*

‎AGENTS.md‎

Lines changed: 47 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -11,22 +11,29 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
1111
`source /opt/intel/oneapi/setvars.sh && python -m pytest dpctl/tests/...`.
1212
- Check visible devices: `sycl-ls`. Tests skip on missing devices/aspects; a CPU
1313
OpenCL device is enough for most of the suite.
14-
- Python build deps: `pip install numpy cython scikit-build cmake ninja pytest "versioneer[toml]==0.29"`.
14+
- Python build deps: `pip install numpy cython scikit-build cmake ninja setuptools pybind11 pytest "versioneer[toml]==0.29"`.
1515

1616
## Commands
1717

1818
- Build in place + editable install: `python scripts/build_locally.py --verbose`
19-
- defaults to `icx`/`icpx` on `PATH`; other compilers need `--compiler-root`
19+
- defaults to `icx`/`icpx` on `PATH`; for other compilers pass absolute
20+
`--c-compiler`/`--cxx-compiler` paths, or names plus `--compiler-root=<bin dir>`
2021
- `--debug`, `--clean`, `--target-cuda[=sm_XX]`, `--target-hip=<arch>`,
2122
`--cmake-opts="-D..."`
23+
- the first configure clones the Level Zero headers and downloads pybind11;
24+
offline, pass `--no-level-zero` (or
25+
`--cmake-opts="-DDPCTL_LEVEL_ZERO_INCLUDE_DIR=<dir>"`) and install `pybind11`
2226
- Python tests: `python -m pytest dpctl/tests`
2327
- one file: `python -m pytest dpctl/tests/test_sycl_queue.py`
2428
- one test: `python -m pytest dpctl/tests/test_sycl_queue_memset.py::test_memset_partial_count`
2529
- without a C compiler/Cython: add `-k "not test_cython_api and not test_c_headers"`
26-
- C API tests (GoogleTest, needs `GTEST_ROOT`): `(cd libsyclinterface && bash dbg_build.sh)`
27-
- Coverage (C + Python, rebuilds with `-DDPCTL_BUILD_CAPI_TESTS=ON`):
28-
`python scripts/gen_coverage.py --oneapi`
29-
- Docs (needs doxyrest): `python scripts/gen_docs.py --doxyrest-root=<path>`
30+
- C API tests (Linux; GoogleTest must be findable by CMake, e.g. via `GTEST_ROOT`):
31+
`(cd libsyclinterface && bash dbg_build.sh)`
32+
- Coverage (Linux; C + Python, rebuilds in place with `-DDPCTL_BUILD_CAPI_TESTS=ON`,
33+
then runs the full pytest suite unless `--skip-pytest`): `python scripts/gen_coverage.py`,
34+
then `python scripts/build_locally.py --clean` for a normal build
35+
- Docs (Linux only; needs Doxygen and the `docs` extras from `pyproject.toml`):
36+
`python scripts/gen_docs.py`, plus `--doxyrest-root=<path>` for the C API reference
3037
- Lint/format one file (no build needed): `pre-commit run --files <path>`
3138
- Lint/format everything: `pre-commit run --all-files`
3239
(black, isort, flake8, cython-lint, clang-format, codespell, bandit, shellcheck,
@@ -37,6 +44,7 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
3744
- `libsyclinterface/` — C API over SYCL (C++ implementation)
3845
- `include/syclinterface/*.h` — public C headers, `DPCTL<Type>_<Op>` functions
3946
- `source/*.cpp` — implementations
47+
- `helper/` — error handlers and enum/string conversion utils
4048
- `tests/*.cpp` — GoogleTest suite; `*.spv` are prebuilt kernel fixtures
4149
- `dpctl/` — Python package
4250
- `_backend.pxd` — Cython `extern` declarations of the C API
@@ -51,23 +59,28 @@ library (`libsyclinterface`). It is compiled with Intel oneAPI DPC++ (`icx`/`icp
5159
- `docs/doc_sources/` — Sphinx sources
5260
- `conda-recipe/`, `conda-recipe-cf/` — conda packaging used by CI
5361
- `scripts/` — build, coverage, docs drivers
62+
- `benchmarks/` — asv benchmarks
63+
- `cmake/` — CMake config for downstream projects (`dpctl-config.cmake`)
5464

5565
## Adding a SYCL feature (typical PR shape)
5666

5767
1. Declare in `libsyclinterface/include/syclinterface/dpctl_sycl_<x>_interface.h`
58-
with a Doxygen comment and ownership attributes.
68+
with a Doxygen comment and ownership attributes. For an existing SYCL type,
69+
extend its files in steps 1-4 rather than creating new ones.
5970
2. Implement in `libsyclinterface/source/dpctl_sycl_<x>_interface.cpp`.
6071
3. Add GoogleTest cases in `libsyclinterface/tests/test_sycl_<x>_interface.cpp`.
6172
4. Declare in `dpctl/_backend.pxd`; wrap in `dpctl/_sycl_<x>.pyx` (and `.pxd` if
62-
the method is `cdef`).
73+
the method is `cdef` or `cpdef`).
6374
5. Add pytest coverage in `dpctl/tests/`.
64-
6. Add a `CHANGELOG.md` entry with the PR link.
75+
6. Export new public names (e.g. enums) in `dpctl/__init__.py` and list them in
76+
`docs/doc_sources/api_reference/dpctl/*.rst`.
77+
7. For user-visible changes, add a `CHANGELOG.md` entry (see Git).
6578

6679
Reference PRs to copy from:
67-
- New queue operation: gh-2361 (`DPCTLQueue_Memset` → `SyclQueue.memset`,
68-
`dpctl/tests/test_sycl_queue_memset.py`).
80+
- New queue operation: gh-2361 (`DPCTLQueue_MemsetWithEvents` →
81+
`SyclQueue.memset`/`memset_async`, `dpctl/tests/test_sycl_queue_memset.py`).
6982
- New device info query: gh-2324 (`dpctl_sycl_device_interface.h` →
70-
`dpctl/_sycl_device.pyx`; register the check in
83+
`dpctl/_sycl_device.pyx`; add a `check_<name>(device)` to `list_of_checks` in
7184
`dpctl/tests/_device_attributes_checks.py`). New enums go through
7285
`dpctl_sycl_enum_types.h`, `libsyclinterface/helper/`, and `dpctl/enum_types.py`.
7386

@@ -81,45 +94,53 @@ Reference PRs to copy from:
8194
- Never let a C++ exception cross the C boundary: catch, call
8295
`error_handler(e, __FILE__, __func__, __LINE__)`, return `nullptr`/error value.
8396
- Null-check every incoming ref and report via `error_handler`.
84-
- Errors are silent unless `DPCTL_VERBOSITY=warning` (or `error`) is set; set it
85-
when debugging a `nullptr` return.
97+
- Errors are silent unless `DPCTL_VERBOSITY` is set; use `warning` when debugging
98+
a `nullptr` return (`error` hides the null-ref messages).
8699

87100
### Cython / Python
88101
- Release the GIL (`with nogil:`) around calls that may block on the device.
89102
- Python-visible errors: raise specific exceptions (`TypeError`, `ValueError`,
90103
`SyclQueueCreationError`, ...) when the C API returns `NULL`.
91104
- Free-threaded CPython (3.14t) is supported; do not rely on the GIL for
92-
thread safety of shared state.
105+
thread safety of shared state. New `.pyx` files need
106+
`# cython: freethreading_compatible = True`, like the existing ones.
93107
- Line length 80 (black, isort, cython-lint, clang-format).
94108

95109
### Tests
96-
- Get devices with `get_queue_or_skip()` / skip on missing aspects; never assume
97-
a GPU or fp64 support.
110+
- Create queues with `get_queue_or_skip()` (`dpctl/tests/helper`) or
111+
`try: dpctl.SyclQueue()` / `except dpctl.SyclQueueCreationError: pytest.skip(...)`;
112+
skip on missing aspects, never assume a GPU or fp64 support.
98113
- Test both sync and `*_async` variants when adding queue operations.
99114

100115
### Files
101-
- New files need the Apache-2.0 license header from `CONTRIBUTING.md`
102-
(C/C++ headers also need the `\file` Doxygen block).
116+
- New files need the Apache-2.0 license header from `CONTRIBUTING.md` with the
117+
current year; all C/C++ files (not only headers) also need the `\file` Doxygen block.
103118
- Comments and docstrings: short, describe what the code does.
104119

105120
## Git
106121

107122
- Branch off `master`; pre-commit blocks commits directly to `master` and
108123
`maintenance/*`.
109124
- One concern per PR; fill in `.github/pull_request_template.md`.
110-
- Update `CHANGELOG.md` (Keep a Changelog sections: Added, Changed, Deprecated,
111-
Removed, Fixed, Maintenance) for user-visible changes, citing `gh-NNNN`.
125+
- Update `CHANGELOG.md` under `## [dev]` (Keep a Changelog sections: Added, Changed,
126+
Deprecated, Removed, Fixed, Maintenance) for user-visible changes, e.g.
127+
`* Added ... [gh-NNNN](https://github.com/IntelPython/dpctl/pull/NNNN)`; the
128+
number is only known once the PR is opened.
112129

113130
## Boundaries
114131

115132
- Generated, do not edit: `dpctl/*.cxx`, `dpctl/**/*.cxx`, `dpctl/include/`
116-
(headers copied/generated at build time), `dpctl/_version.py` (versioneer),
117-
`_skbuild/`, `build/`.
118-
- Edit C headers in `libsyclinterface/include/`, not their copies under `dpctl/include/`.
133+
(headers copied/generated at build time), `_skbuild/`, `build/`.
134+
- `dpctl/_version.py` is a committed, vendored versioneer file; do not edit it by hand.
135+
- Edit C headers in `libsyclinterface/include/` and Python C-API headers in
136+
`dpctl/apis/include/`, not their copies under `dpctl/include/`.
137+
`Config/dpctl_config.h` is generated from `dpctl_config.h.in`; edit the `.in`.
119138
- In-place `.so` files survive branch switches; rebuild (`--clean`) before
120139
trusting test results after checking out another branch.
121140
- Changing an existing C API signature or enum value is a breaking change:
122-
call it out in the PR and the CHANGELOG `NOTE` list.
141+
call it out in the PR and in a `**NOTE**: This release contains breaking changes:`
142+
list at the top of the `[dev]` section (as under 0.23.0).
123143
- `.github/workflows/` actions are pinned to commit SHAs (checked by zizmor);
124144
keep that when adding steps.
125-
- `conda-recipe*/`, release versions, and doc version lists need maintainer review.
145+
- Don't change `conda-recipe*/`, release versions, or `docs/doc_versions.txt`
146+
unless asked; call such changes out in the PR.

0 commit comments

Comments
 (0)