# Contributor's Guide The wgpu-py project is a community effort, shaped by a group of contributors from around the world. And you can contribute too! ## Creating issues, pull-requests, and discussions We coordinate our work using GitHub, * The [issues](https://github.com/pygfx/wgpu-py/issues) are meant to track problems and feature requests. * The [pull-requests](https://github.com/pygfx/wgpu-py/pulls) (a.k.a. PR's) are used to contribute new code to the project. * The [discussions](https://github.com/pygfx/wgpu-py/discussions) are to ask questions and have discussions related to (using) the project. Before creating a new issues, please first search the issue list to see if your problem is already known. If it is, you can then participate by letting us know you encountered the same problem, and maybe add specific details that can help us fix the problem. If you're new to Github, see Github's documentation for [creating an issue](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/creating-an-issue) and [creating a pull-request](https://docs.github.com/en/get-started/using-github/github-flow). And we are also here to help you! ## How can I contribute? ### Reporting problems If you run into a difficulty when using wgpu-py, we'd like to know, so that we can fix or document it. If you encounter what you think is a bug, please let us know by creating an issue! Likewise in case things are unclear, e.g. because the documentation is incomplete or outdated. ### Asking questions If you are trying to achieve something and you're not sure how to do this with wgpu-py, you can start a discussion. We can then give some tips, and others with similar goals can benefit too. ### Requesting and contributing features If you feel that something is missing, you can create an issue to request that feature. We especially appreciate if you're willing to contribute the new feature via a pull-request. It can be good to first open an issue (especially for large/complex features) to discuss the approach and design. This increases the chance of a successful pull-request. ### Promoting wgpu-py We love it when wgpu-py is used in a derived project, blog posts, article, or scientific paper. We love it even more if it is referenced to help increase the visibility of the project. Also feel free to reach out to let us know! See our Zenodo page for citation details: https://doi.org/10.5281/zenodo.18836262 ### Active contributions If you just want to help move the project forward, we welcome you to: * Check the issue list, to see if there are issues that you can help with, maybe by fixing a bug or contributing a new feature. * Check the pull-requests, to see if you can help review it, or maybe test it out. * Check the discussions, to see if you can help answer user questions. * Read the documentation, and see if it can be improved. ## AI Policy *This policy was gratefully inspired by the AI policies of SciPy and scikit-image.* We are a small developer team, and we enjoy reviewing and discussing code written by other humans. We recognize that LLMs may be useful, but overall prefer for contributions to be hand-written. ### Responsibility You are responsible for all the code that you contribute, including the AI generated code. You must understand and be able to explain the submitted code as well as its relation with the surrounding code. It is not acceptable to submit a patch that you cannot understand and explain yourself. ### Disclosure You must disclose whether AI has been used to produce any code of your pull-request. If so, you must document which tool(s) have been used, how they were used, and specify what code or text is AI generated. ### Copyright Contributors must own the copyright of any code submitted to wgpu-py. Code generated by AI may infringe on copyright and it is your responsibility to not infringe. We reserve the right to reject any pull requests where the copyright is in question. ### Communication When interacting with developers (in discussions, issues, pull-requests, etc.) do not use AI to speak for you, except for translation or grammar editing. Human-to-human communication is essential for an open source community to thrive. ### AI Agents The use of an AI agent that writes code and then submits a pull request autonomously is not permitted. ## Coding Style The wgpu-py project uses `ruff` to format and lint the code: ```bash # Reformat the code if necessary ruff format # Check for linting errors. ruff check ``` Optionally, if you install [pre-commit](https://github.com/pre-commit/pre-commit/) hooks with `pre-commit install`, lint fixes and formatting will be automatically applied on `git commit`. ## Code generation, and updating to a later version of WebGPU or wgpu-native To update to upstream changes, we use a combination of automatic code generation and manual updating. See [the codegen utility](codegen/README.md) for more information. ## Testing The test suite is divided into multiple parts: * `pytest -v tests` runs the unit tests. * `pytest -v examples` tests the examples. * `pytest -v wgpu/__pyinstaller` tests if wgpu is properly supported by pyinstaller. * `pytest -v codegen` tests the code that autogenerates the API. * `pytest -v tests_mem` tests against memoryleaks. There are two types of tests for examples included: ### Type 1: Checking if examples can run When running the test suite, pytest will run every example in a subprocess, to see if it can run and exit cleanly. You can opt out of this mechanism by including the comment `# run_example = false` in the module. ### Type 2: Checking if examples output an image You can also (independently) opt-in to output testing for examples, by including the comment `# test_example = true` in the module. Output testing means the test suite will attempt to import the `canvas` instance global from your example, and call it to see if an image is produced. To support this type of testing, ensure the following requirements are met: * The `RenderCanvas` class is imported from the `rendercanvas.auto` module. * The `canvas` instance is exposed as a global in the module. * A rendering callback has been registered with `canvas.request_draw(fn)`. Reference screenshots are stored in the `examples/screenshots` folder, the test suite will compare the rendered image with the reference. Note: this step will be skipped when not running on CI. Since images will have subtle differences depending on the system on which they are rendered, that would make the tests unreliable. For every test that fails on screenshot verification, diffs will be generated for the rgb and alpha channels and made available in the `examples/screenshots/diffs` folder. On CI, the `examples/screenshots` folder will be published as a build artifact so you can download and inspect the differences. If you want to update the reference screenshot for a given example, you can grab those from the build artifacts as well and commit them to your branch. ### Testing Locally Testing locally is possible, however pixel perfect results will differ from those on the CIs due to discrepancies in hardware, and driver (we use llvmpipe) versions. On linux, it is possible to force the usage of LLVMPIPE in the test suite and compare the generated results of screenshots. Beware, the results on your machine may differ to those on the CI. We always include the CI screenshots in the test suite to improve the repeatability of the tests. If you have access to a linux machine with llvmpipe installed, you may run the example pixel comparison testing by setting the WGPUPY_WGPU_ADAPTER_NAME environment variable appropriately. For example ``` WGPUPY_WGPU_ADAPTER_NAME=llvmpipe pytest -v examples/ ``` The `WGPUPY_WGPU_ADAPTER_NAME` variable is modeled after the https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables and should only be used for testing the wgpu-py library itself. It is not part of the supported wgpu-py interface.