Contribution workflow and automated checks¶
This document describes the process for getting code changes into master.
It covers one-time setup, checks run on commits and PRs, how to fix failed checks, and the rules for branches, commit messages, and versions, in that order.
For writing the code itself, see the document for what you are adding.
| What you are adding | Document |
|---|---|
| Model | Writing custom models |
Node and kernel |
Writing custom nodes and kernels |
| Group | Writing custom groups |
1. One-time setup¶
1.1 Build and commit hooks¶
Clone the repository with --recursive and build it as described in the Quickstart.
Then install the commit hooks. The hooks check changes when committing.
1.2 Python package and tests¶
When modifying Python bindings or a Node, install the package and run the tests.
torch is used only as a reference implementation for tests. Without installing the CPU build first, the download will include several GB of CUDA binaries.
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e ".[test]"
python -m pytest python/tests
1.3 Enable the clang-tidy hook¶
When modifying C++ code, also enable the clang-tidy hook. This hook does nothing until enabled.
clang-tidy requires compilation information (compile_commands.json), which Visual Studio builds do not provide.
This command only configures CMake with Ninja in build-tidy/; it does not build the project.
On Windows, it finds the latest Visual Studio installation with C++ tools and runs in that environment, so a developer command prompt is not required.
Delete the build-tidy/ directory to disable the hook.
2. Checks run on commits¶
| Hook | Scope | When a problem is found |
|---|---|---|
| clang-format | Staged C++ lines | Fixes the lines and stops the commit. Stage the fixes and commit again. |
| ruff format | Staged Python files | Same as above. |
| ruff check | Staged Python files | Reports the problem and stops the commit. |
| clang-tidy | Staged C++ lines in vai/, models/, and examples/ |
Reports the problem and stops the commit. Does nothing until 1.3 has been completed. |
Hooks help catch problems early. PRs run the same checks again, so skipping hook installation only delays when problems are found.
3. Checks run on PRs¶
3.1 Check list¶
Checks run when a PR is opened and when commits are added to it. Only the checks that the changed files need are run.
| Check | What it does | When it does not run |
|---|---|---|
format |
Checks code formatting and Python mistakes. | Never. It runs on every PR. |
tidy |
Checks C++ naming rules and mistakes. | PRs that change only the python/ folder, the docs/ folder, mkdocs.yml, or .md files |
vai-linux, vai-windows |
Builds the C++ code. (GCC 14, MSVC.) | Same as above. |
pyvai-linux |
Builds the Python package and runs python/tests. |
PRs that change only the docs/ folder, mkdocs.yml, or .md files |
docs |
Checks that Built-in nodes matches the Node headers, and builds the documentation site. |
PRs that change none of the docs/ folder, mkdocs.yml, and the vai/nodes/ folder |
For example, a PR that changes only documentation runs format and docs.
The PR page shows a check with its workflow name, as in CI / format. The docs check appears as docs / build.
In format and tidy, each tool examines a different scope.
| Check | Tool | Scope | Failure condition |
|---|---|---|---|
format |
clang-format | C++ lines added or changed in this PR | Formatting such as line breaks or indentation differs from the settings in .clang-format. |
format |
ruff format | The whole of each Python file changed in this PR | Formatting differs from ruff's format. |
format |
ruff check | Every Python file in the repository | There is a mistake such as an unused import. |
tidy |
clang-tidy | C++ lines added or changed in this PR in the vai/, models/, and examples/ folders |
A naming rule is broken or there is a mistake. |
3.2 Checking only changed lines¶
C++ checks examine only the lines added or changed in this PR, rather than entire files. Since the repository's code predates the checking tools, existing problems are outside the scope of the PR. Problems on untouched lines do not cause the PR to fail.
3.3 First PR from a fork¶
Checks on the first PR from a fork start after a maintainer approves the run. Until then, the checks are shown as pending.
4. Fixing failed checks¶
Tool versions are pinned in the CI configuration. All three tools can be installed with pip install.
| Tool | Version |
|---|---|
| clang-format | 21.1.8 |
| clang-tidy | 22.1.8 |
| ruff | 0.17.4 |
4.1 clang-format¶
Format only the lines changed on the branch, then commit the result.
4.2 ruff¶
4.3 clang-tidy¶
The check log shows the location and check name. Naming violations also show the suggested replacement name.
vai/nodes/slice.h:164:8: error: invalid case style for struct 'probe_struct' [readability-identifier-naming]
164 | struct probe_struct { int x; };
| ^~~~~~~~~~~~
| ProbeStruct
To check before opening a PR, enable the hook in 1.3 or configure the editor to read .clang-tidy.
Visual Studio and clangd read this file and show diagnostics while editing.
On Windows, do not pass git diff output directly to clang-tidy-diff.
git uses / in paths while clang-tidy uses \, so checks can pass even when problems exist. The hook script converts the paths before passing them on.
4.4 Node documentation¶
Built-in nodes is generated from the descriptive comments in Node headers.
After changing descriptive comments, slots, or Config, regenerate the documentation and commit both generated files. Do not edit these documents directly.
5. Rules enforced by automated checks¶
The configuration files at the repository root define the rules. This section summarizes their contents.
5.1 C++ formatting¶
Checked by .clang-format.
| Item | Rule |
|---|---|
| Indentation and line length | Use four spaces, no tabs. Lines are limited to 120 characters. |
| Opening braces | Follow 3.2 of Common code conventions. |
| Constructs allowed on one line | Short functions inside classes, empty functions, short lambdas, and short enum declarations. Bodies of if and for always start on the next line. |
| Arguments of a function call | If they do not fit on one line, put each argument on its own line. |
| Constructor initializer lists | Put each member on its own line, with : and , at the start of the line. |
| Braced initializers | Put a space inside the braces. (Example: { .inDim = 64, .outDim = 32 }.) |
| Preprocessor directives | Indent directives inside #if by one level. Do not indent inside an include guard. |
| Pointers and references | Attach * and & to the type. (Examples: const char* path, Node& node.) |
| Includes and comments | Preserve include order and comment line breaks as written. |
| Exclusions | Do not format external/, vai/shaders/, or the third-party headers in vai/utils/ (stb_image.h, stb_image_write.h, tiny-json.h). |
5.2 C++ naming¶
Checked by .clang-tidy. Rules and exceptions are in 3.1 of Common code conventions.
The tool cannot enforce the rule against prefixing constants with k, because kBeginOfText also matches camelCase. This rule is checked in review.
5.3 C++ bug checks¶
.clang-tidy runs bugprone-*, performance-*, and clang-analyzer-* checks.
Four checks that are closer to style preferences (narrowing-conversions, exception-escape, easily-swappable-parameters, enum-size) and the opt-in analyzer checks (clang-analyzer-optin.*) are excluded.
If a diagnostic does not apply to a line, disable only that check on that line and explain why.
const float pad = float(M) / float(CEIL_DIV(M, b) * b); // NOLINT(bugprone-integer-division): Ceiling division is intentional
Do not use // NOLINT without a check name, as it disables all checks on that line.
5.4 Python¶
Follow the configuration in pyproject.toml.
| Item | Rule |
|---|---|
| Formatting | Follow ruff format. Lines are limited to 100 characters. |
| Checks | Run ruff check's F (pyflakes), E4, E7, E9 (pycodestyle rules closer to errors), and B (bugbear). |
| Exceptions | If a diagnostic does not apply to a line, add # noqa: <rule> and explain why. |
6. Branches, commit messages, and PRs¶
Branches follow GitHub Flow, and commit messages follow Conventional Commits.
6.1 Branches¶
Create a working branch from master and merge it through a PR. There is no develop branch.
| Branch | Purpose |
|---|---|
master |
Reviewed and checked code |
feat/reshape-op |
New feature |
fix/model-loader-crash |
Bug fix |
docs/build-guide |
Documentation change |
- Name a branch
<type>/<short-description>, in lower case with hyphens. The types are those in the table in 6.2. - Create one branch and one PR per piece of work.
- Branch names are not checked for PRs from forks. The same format is recommended.
6.2 Commit messages¶
The subject has the form type(scope): description.
scopeis the module that changed and can be omitted. (Examples:python,engine,linear,yolox.)descriptionstarts with an English verb in the imperative and states what changed.
| Type | When to use | Example |
|---|---|---|
feat |
New feature | feat(graph): add reshape operation |
fix |
Fix for incorrect behavior | fix(loader): reject truncated model files |
perf |
Performance improvement with the same behavior | perf(vulkan): reduce allocation overhead |
refactor |
Structural change with the same behavior | refactor(graph): extract shape helpers |
docs |
Documentation change | docs: clarify build requirements |
test |
Test-only change | test(loader): cover empty model files |
build |
Build and dependency change | build: require CMake 3.20 |
ci |
CI change | ci: add compiler checks |
style |
Formatting change that does not affect behavior | style: format public headers |
chore |
Other maintenance | chore: update the issue templates |
Choose the type as follows.
- Use
featwhen the change makes something new possible. - Use
fixwhen the change corrects incorrect behavior. - Use
perfwhen the change does the same thing faster.
A commit has one purpose. Put a feature and its tests together, and keep unrelated refactoring separate. Split PRs the same way. The test is "if only this change is reverted, does the rest still build and pass its tests?" Implementation, call sites, and tests that must be reverted together belong in one unit.
For a change that is incompatible with existing usage, add ! after the type and describe the impact and the migration after BREAKING CHANGE: in the body.
feat(loader)!: require explicit model format
BREAKING CHANGE: load_model(path) now takes a format argument.
Change existing calls to load_model(path, format).
6.3 Opening and merging a PR¶
| Item | Rule |
|---|---|
| Merge path | Changes enter master only through PRs. |
| PR title | Use the commit subject format in 6.2. With a squash merge, this title becomes the commit subject on master. |
| PR description | Describe the changes and how they were verified. Also mention any checks that failed for reasons unrelated to the changes. For an incompatible change, include a BREAKING CHANGE: paragraph. |
| Approval | Two approvals from the maintainer team are required. Changes to paths listed in CODEOWNERS must include approval from the relevant code owner. |
| Merge method: PRs from forks | Use squash merge. The PR's commits enter master as one commit. |
| Merge method: PRs from branches of this repository | Use a merge commit. The PR's commits enter master as they are, so every commit must follow 6.2. Otherwise, use squash merge. |
| After merging | Delete the merged working branch. |
7. Versions¶
Tags have the form vMAJOR.MINOR.PATCH and follow SemVer.
| Change | Part to increase | Example |
|---|---|---|
| Change incompatible with the existing public API | MAJOR | v1.2.3 → v2.0.0 |
| Compatible new feature, deprecation notice for a public API | MINOR | v1.2.3 → v1.3.0 |
| Compatible bug fix, compatible performance improvement | PATCH | v1.2.3 → v1.2.4 |
The release version is decided by the types of the commits that entered master. Branch names do not affect the version.
Commit on master |
Effect on the version |
|---|---|
! or BREAKING CHANGE, with any type |
MAJOR |
feat |
MINOR |
fix, perf |
PATCH |
| Any other type | No release on its own |
- When a release bundles several changes, increase the highest part among them.
0.xversions come before the API is stable. The two tables above apply from1.0.- To verify before a full release, use a candidate version such as
v1.0.0-rc.1.