First of all, thank you for contributing! We welcome all kinds of contributions, including but not limited to
- Bug fixes
- New feature proposals and implementations
- Documentation improvements and translations
- More user-friendly error messages
- New test cases and examples
- Compiler performance enhancements
- High-quality blog posts and tutorials
- Participation in the Taichi forum
- Introducing Taichi to your friends or simply staring the project on GitHub
- Typo fixes in the documentation, code or comments (please go ahead and make a pull request for minor issues like these)
Please take some time to familiarize yourself with this contribution guide before opening a pull request. For more details regarding development of the Taichi compiler, read the development tips.
- Issues marked with "good first issue" are great chances for starters.
- Issues marked with "welcome contribution" are slightly more challenging but still friendly to beginners.
- Please first leave a comment (e.g. I know how to fix this and would like to help!) on the issue, so that people know someone is already working on it. This helps prevent redundant work.
- If no core developer has commented and described a potential solution on the issue, please briefly describe your plan, and wait for a core developer to reply before you start. This helps keep implementations simple and effective.
- Be pragmatic: practically solving problems is our ultimate goal.
- No overkills: always use easy solutions to solve easy problems, so that you have time and energy for real hard ones.
- Almost every design decision has pros and cons. A decision is good if its pros outweigh its cons. Always think about both sides.
- Debugging is hard. Changesets should be small so that sources of bugs can be easily pinpointed.
- Unit tests and integration tests are our friends.
"There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult." — C.A.R. Hoare
One thing to keep in mind is that, Taichi was originally born as an academic research project. This usually means that some parts did not have the luxury to go through a solid design. While we are always trying to improve the code quality, it doesn't mean that the project is free from technical debts. Some places may be confusing or overly complicated. Whenever you spot one, you are more than welcome to shoot us a PR! :-)
A few tips for effective communication in the Taichi community:
- How much information one effectively conveys, is way more important than how many words one typed.
- Be constructive. Be polite. Be organized. Be concise.
- Bulleted lists are our friends.
- Proofread before you post: if you are the reader, can you understand what you typed?
- If you are not a native speaker, consider using a spell checker such as Grammarly.
Please base your discussion and feedback on facts, and not personal feelings. It is very important for all of us to maintain a friendly and blame-free community. Some examples:
This design could be confusing to new Taichi users.
This design is terrible.
- PRs with small changesets are preferred.
- A PR should ideally address only one issue.
- It is fine to include off-topic trivial refactoring such as typo fixes;
- The reviewers reserve the right to ask PR authors to remove off-topic non-trivial changes.
- When implementing a complex feature, consider breaking it down into small PRs to keep a more detailed development history and to interact with core developers more frequently.
- A PR should ideally address only one issue.
- PR titles should be short sentences describing the changes and following certain format.
- In the description of a PR, it will be nice to link relevant GitHub issues
fixes #issue_number) or provide a little context on the motivation. Some important implementation decisions you made in the PR is also helpful.
- If you want early feedback from core developers,
- Open a PR in Draft state on GitHub to share your progress;
- Make sure you @ the corresponding developers in the comments or request reviews from them.
- All PRs should ideally come with corresponding tests. See Testing.
- All PRs should come with documentation updates, except for internal compiler implementations. See Documentation.
- All PRs must pass continuous integration tests before they get merged. See Using continuous integration.
- All PRs must pass code format checks. See Enforcing code style.
- Read a great article from Google on how to have your PR merged quickly. [PDF]
- All commits in a PR will always be squashed and merged into master as a single commit. However, PR authors should not squash commits on their own.
- If you are making multiple PRs,
- Independent PRs should be based on different branches
- PRs with dependencies should be raised only after all
prerequisite PRs are merged into
- Independent PRs should be based on different branches forking from
- Please try to follow these tips from Google:
- The merger should always squash and merge PRs into the master branch.
- The master branch is required to have a linear history.
- Make sure the PR passes continuous integration tests, except for cases like documentation updates. See Using continuous integration.
- Make sure the title follows PR tag rules.
- Continuous Integration (CI) will build and test your commits in a PR in multiple environments.
- Currently, Taichi uses Github Actions.
- CI will be triggered every time you push commits to an open PR.
- You can prepend
[skip ci]to your commit message to avoid triggering CI. For example, a commit with the message
[skip ci] This commit will not trigger CIwill not trigger CI.
- A tick on the left-hand side of a commit hash means CI passed, while a cross means CI failed.
Locally, you can run
ti formatin the command line to re-format code style. Note that you have to install
yapf v0.31.0locally before you use
If you don't have these formatting tools locally, feel free to leverage GitHub Actions: simply comment
/formatin a PR (e.g., #2481) and then Taichi Gardener will automatically push a commit to your branch that formats the code. Note if you want to make more changes afterwards, you'll need to
For your C++ code, please also follow C++ style.
PR titles will be part of the commit history reflected in the
branch, therefore it is important to keep PR titles readable.
- Please always prepend at least one tag such as
[Lang]to PR titles:
- When using multiple tags, make sure there is exactly one space between tags;
- For example,
[Lang][refactor](no space) should be replaced by
- The first letter of the PR title body should be capitalized:
- For example,
[Doc] improve documentationshould be replaced by
[Doc] Improve documentation;
[Lang] "ti.sqr(x)" is now deprecatedis fine because
"is a symbol.
- For example,
- Please do not include back quotes ("`") in PR titles.
- Good examples include
[Metal] Support bitmasked SNode,
[Vulkan] ti.atomic_min/max support, or
[Opt] [ir] Enhanced intra-function optimizations.
Frequently used tags:
[LLVM]: the LLVM backend shared by CPUs and CUDA;
[Lang]: frontend language features, including syntax sugars;
[Std]: standard library, e.g.,
[Sparse]: sparse computation;
[IR]: intermediate representation;
[Opt]: IR optimization passes;
[GUI]: the built-in GUI system;
[Refactor]: code refactoring;
[CLI]: commandline interfaces, e.g., the
[Doc]: documentation under docs/;
[Example]: examples under examples/;
[Test]: tests under tests/;
[Linux]: Linux platform;
[Mac]: macOS platform;
[Windows]: Windows platform;
[Perf]: performance improvements;
[CI]: CI/CD workflow;
[Misc]: something that doesn't belong to any category, such as version bump, reformatting;
[Bug]: bug fixes.
We do appreciate all kinds of contributions, yet we should not expose the title of every PR to end-users. Therefore the changelog will distinguish what the user should know from what the developers are doing. This is done by capitalizing PR tags:
- PRs with visible or notable features to the users should be marked
with tags starting with the first letter capitalized, e.g.,
[CLI]. These PRs will be highlighted in the release note for end-users, therefore it is important to make sure your PR title is effective in telling what your PR does.
- Other PRs (underlying development or intermediate implementation)
should use tags with everything in lowercase letters, e.g.,
- Because of the way the release changelog is generated, there
should be at most one capitalized tag in a PR title to prevent
duplicate PR highlights. For example,
[GUI] [Mac] Support modifier keys(#1189) is an improper tag choice, and we should have used
[gui] [Mac] Support modifier keys in GUIinstead. Please capitalize the tag that is the most relevant to the PR.
Tests should be added to tests/. We have both Python tests and C++ tests.
ti testto run all the tests.
ti test -vfor verbose outputs.
ti test -sfor original output from the tests.
ti test -a <arch(s)>to test only specified backends, e.g.,
ti test -a cuda,metal.
ti test -na <arch(s)>to test all backends excluding specified ones, e.g.,
ti test -na opengl,x64.
ti test <filename(s)>to run tests in specified files. For example,
ti test numpy_iowill run all tests in tests/python/test_numpy_io.py.
ti test -k <key>to run tests that match the specified key. For example,
ti test linalg -k "cross or diag"will run
ti test -t <threads>to set custom number of threads for parallel testing.
For more options, see
ti test -h.
For more details on how to write a Python test case, see Workflow for writing a Python test.
For more details on C++ tests, see Workflow for writing a CPP test.
Documentation source files are under docs/ of the main Taichi repo. An automatic service syncs the updated content with our documentation repo and deploys the documentation at the Taichi documentation site.
To set up a local server and preview your documentation edits in real time, see instructions for Local Development.