Skip to content

Latest commit

 

History

History
71 lines (47 loc) · 4.36 KB

CONTRIBUTING.md

File metadata and controls

71 lines (47 loc) · 4.36 KB
Raw

Contributing to NumDot

New collaborators are very welcome! There's 3 quick ways to start:

Understanding NumDot Technology

First off, NumDot is a GDExtension, that is, an extension for the Godot engine. If you aren't familiar with them, I recommend doing the short C++ GDExtension tutorial to understand the tools involved.

NumDot itself is a very thin wrapper over xtensor. That means little code is involved, but some of it involves fairly advanced concepts:

  • Tensors and broadcasting: If unfamiliar with these terms, we recommend experimenting with NumPy first. While NumPy is not involved, it is the most popular implementation of this concept.
  • C++ Templates: To generate efficient code with few lines, NumDot makes use of C++ templates. They're essentially fancy generics, but are a bit harder to understand.
  • C++ Variant: To offer support for different data types, NumDot uses std::variant.
  • XTensor / XArray: XTensor is used for actually doing the math. That means you need to understand what it's doing to produce code that works with it.

You don't need to be proficient with all of these technologies to help! Check out the open issues for anything that interests you. There is a lot left to do!

Making a contribution

Setting up the project is covered on the docs: Custom Builds

Additionally, please make sure you adhere to code style guideline, and update documentation, as described below.

Include Policy

include-what-you-use should be used to keep the includes tidy and explicit. This workflow is needed because code that works with one compiler can break down with another, due to differences in intrinsic headers. If you can't run it, don't worry, we can always fix includes post merge.

# Run the tool, dump the results into iwyu.txt.
iwyu_tool.py -p . src > iwyu.txt

The resulting txt is very explicit. Drop xsimd and intrinsics specific files you are offered, but most of the rest can be copied over as-is.

Documentation

If you changed NumDot's public API, you should also update its documentation. Start by running the doctool:

# Update the .xml files from source
cd demo && godot --doctool ../ --gdextension-docs && cd ..
# Update the .rst files from .xml files
curl -sSL https://raw.githubusercontent.com/godotengine/godot/master/doc/tools/make_rst.py | python3 - -o "docs/classes" -l "en" doc_classes

Edit the new entries in ./doc_classes/ (see the godot docs for more information).

Proposing your changes

When you're done, edit the changelog page under the 'Latest (Unstable)' heading in /docs/setup/changelog.

Make a commit:

# Check your changes first.
git diff
# If everything seems ok:
git add .
git commit -m "My change message."
git push

Finally, make a Pull Request (PR). We will check your changes, make suggestions, and finally integrate your code into the project. Try to make sure you don't include any accidental changes, like editing the test file.

Any Problems?

Please come by our Discord and have a chat with us. We are happy you want to help, and should be able to help you make a contribution.