Skip to content
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

DOC: contributor docs for delegation #103

Merged
merged 1 commit into from
Jan 19, 2025
Merged

DOC: contributor docs for delegation #103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
36 changes: 33 additions & 3 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,14 @@ converting code to consume the standard.

Thanks to [all contributors](contributors.md) so far!

## How to contribute a function
## How to contribute a new function

- [Open an issue](https://github.com/data-apis/array-api-extra/issues/new) to
propose the new function.
- Add the implementation of your function to `src/array_api_extra/_funcs.py`.
propose the new function. You may want to wait for initial feedback on the
issue before diving into an implementation. Feel free to skip this step if
there is already an open issue for the function.
- Add the implementation of your function to
`src/array_api_extra/_lib/_funcs.py`.
- Ensure that your function includes type annotations and a
[numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html).
- Add your function to `__all__` at the top of the file.
Expand All @@ -20,6 +23,33 @@ Thanks to [all contributors](contributors.md) so far!
- Add your function to `docs/api-reference.md`.
- [Make a PR!](https://github.com/data-apis/array-api-extra/pulls)

## How to add delegation to a function

See [the tracker for adding delegation][delegation-tracker].

[delegation-tracker]: https://github.com/data-apis/array-api-extra/issues/100

- If you would like to discuss the task before diving into the implementation,
click on the three dots next to the function on the tracker issue, and choose
"Convert to sub-issue".
- Create a function in `src/array_api_extra/_delegation.py` with a signature
matching the function in `src/array_api_extra/_lib/_funcs.py`, and move the
docstring to the new function. Leave a one-line docstring in `_funcs.py`,
pointing to `_delegation.py` to see the full docstring.
- Also move the initial `array_namespace` call and any input validation over to
the new function.
- Add delegation to backends using the `if _delegate` pattern. See
`src/array_api_extra/_lib/_backends.py` for the full list of backends we have
worked with so far.
- After all delegation layers, return the result from the implementation in
`_funcs`.
- Simplify the signature in `_funcs.py` to remove impossible arguments now that
it is only called internally via `_delegation`. For example, the `xp`
parameter can be changed from type `ModuleType | None` to `ModuleType`.
- Don't worry if you are not sure how to do some of the above steps or think you
might have done something wrong -
[make a PR!](https://github.com/data-apis/array-api-extra/pulls)

## Development workflow

If you are an experienced contributor to Python packages, feel free to develop
Expand Down
Loading