提交 Pull Request#

指南#

  • 建议作者发送范围明确的 PR，以便在出现问题时进行审查和回复。因此，作者应该避免将多个不相关的变化合并成单个 PR。

  • 在你提交 PR 之前，请根据 main 的最新版本重新编写代码，你可以通过运行

    git remote add upstream [url to tvm repo]
git fetch upstream
git rebase upstream/main

  • 确保代码通过 lint 检查

    # While the lint commands used should be identical to those run in CI, this command reproduces
# the CI lint procedure exactly (typically helpful for debugging lint script errors or
# to avoid installing tools manually)
python tests/scripts/ci.py lint

# Run all lint steps.
docker/lint.sh

# To run steps individually, specify their step names on the command-line. An incorrectly
# spelled step name causes the tool to print all available steps.
docker/lint.sh <step_name> ...

    如果 clang-format lint 检查失败，运行如下 git-clang-format 来自动重新格式化你的代码：

    # Run clang-format check for all the files that changed since upstream/main
docker/bash.sh ci_lint ./tests/lint/git-clang-format.sh upstream/main

  • 添加测试用例来覆盖新特性或修复补丁引入的 bug。

  • 记录你写的代码，参见 Documentation

  • 创建 pull request 并修复 CI 检查报告的问题。

  • Request code reviews from other contributors and improve your patch according to their reviews by @-ing them in your pull request. Tags in PR titles will automatically tag subscribed users, so make sure to put relevant topics in your PR titles (e.g. [microTVM] Add a cool change and not a cool change for microTVM). Please see the Commit Message Guideline below on the guidelines about the tags in a PR/commit title and how to write good PR/commit messages.

    • 为了让您的代码快速被评审，鼓励您帮助评审其他人的代码，这样他们就可以反过来帮助您。

    • 代码评审是帮助改进贡献者代码质量的指导过程。应该积极地对待它，在评审之前尽可能地改进代码。我们非常重视那些没有大量评论的补丁。

    • 详细的指导方针并总结了有益的经验教训。

  • 审核人员批准拉请求后，可以合并 PR。

Commit Message Guideline#

Apache TVM uses the Github (GH) platform for patch submission and code review via Pull Requests (PRs). The final commit (title and body) that is merged into the Apache TVM main tree is composed of the PR’s title and body and must be kept updated and reflecting the new changes in the code as per the reviews and discussions.

Although these guidelines apply essentially to the PRs’ title and body messages, because GH auto-generates the PR’s title and body from the commits on a given branch, it’s recommended to follow these guidelines right from the beginning, when preparing commits in general to be submitted to the Apache TVM project. This will ease the creation of a new PR, avoiding rework, and also will help the review.

The rules below will help to achieve uniformity that has several benefits, both for review and for the code base maintenance as a whole, helping you to write commit messages with a good quality suitable for the Apache TVM project, allowing fast log searches, bisecting, and so on.

PR/commit title:

  • Guarantee a title exists (enforced);

  • Don’t use Github usernames in the title, like @username (enforced);

  • A tag must be present as a hint about what component(s) of the code the PRs / commits “touch” (enforced). For example [BugFix], [CI], [microTVM], and [TVMC]. Tags go between square brackets and appear first in the title. If more than one tag exist, multiple brackets should be used, like [BugFix][CI]. The case recommended for tags, in geral, is the upper camel case. For example, prefer the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC] instead of [ci] and [tvmc]. Tags help reviewers to identify the PRs they can/want to review and also help the release folks when generating the release notes;

  • Use an imperative mood. Avoid titles like “Added operator X” and “Updated image Y in the CI”, instead use the forms “Add feature X” and “Update image Y in the CI” instead;

  • Observe proper use of caps at the beginning (uppercase for the first letter) and for acronyms, like, for instance, TVM, FVP, OpenCL. Hence instead of “fix tvm use of opencl library”, write it as “Fix TVM use of OpenCL library”;

  • Do not put a period at the end of the title.

PR/commit body:

  • Guarantee a body exists (enforced);

  • Don’t use Github usernames in body text, like @username (enforced);

  • Avoid “bullet” commit message bodies: “bullet” commit message bodies are not bad per se, but “bullet” commit messages without any description or explanation is likely as bad as commits without any description, rationale, or explanation in the body.

For minor deviations from these guidelines, the community will normally favor reminding the contributor of this policy over reverting or blocking a commmit / PR.

Commits and PRs without a title and/or a body are not considered minor deviations from these guidelines and hence must be avoided.

Most importantly, the contents of the commit message, especially the body, should be written to convey the intention of the change, so it should avoid being vague. For example, commits with a title like “Fix”, “Cleanup”, and “Fix flaky test” and without any body text should be avoided. Also, for the review, it will leave the reviewer wondering about what exactly was fixed or changed and why the change is necessary, slowing the review.

Below is an example that can be used as a model:

[microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods

Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
the Project API build, flash, and open_transport methods.

However, since the board type is already configured when the project is
created (i.e. when the generate_project method is called), it’s possible to
avoid this redundancy by obtaining the board type from the project
configuration files.

This commit adds code to obtain the board type from the project CMake files,
removing this option from build, flash, and open_transport methods, so it’s
only necessary to specify the ‘zephyr_board’ option when calling
generate_project.

This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
method to ‘generate_project’, reducing further the number of required options
when building a project, since the ‘build’ method is usually called more often
than the ‘generate_project’.

After a new PR is created and the review starts it’s common that reviewers will request changes. Usually the author will address the reviewers’ comments and push additional commits on top of the initial ones. For these additional commits there is no recommendation regarding the commit messages. However if the additional commits render the PR title and/or body outdated then it’s the author’s responsibility to keep the PR title and body in sync with new changes in the code and updated the PR title and body accordingly (remember that the PR title and body will be used to compose the final commit message that will land in the main tree).

Committers will seek to fix any issues with the commit message prior to committing but they retain the right to inform the author of the rules and encourage them to follow them in future. Also, they retain the right to ask to the author to update the PR title and/or body when they are not correctly updated or fixed.

CI 环境#

使用 Docker 映像创建稳定的 CI 环境，可以部署到多台机器上。按照 此 issue 模板 中的步骤来更新 CI Docker 映像。

测试#

尽管有钩子为每个拉请求自动运行单元测试，但总是建议提前在本地运行单元测试，以减少审阅人员的负担，加快审阅过程。

C++（本地）#

运行 C++ 测试需要安装 gtest，请参见 启用 C++ 测试

# assume you are in tvm source root
TVM_ROOT=`pwd`

./tests/scripts/task_cpp_unittest.sh

Python（本地）#

必要的依赖关系：

pip install --user pytest Cython synr

如果要运行所有测试：

# build tvm
make

./tests/scripts/task_python_unittest.sh

如果要运行单个测试：

# build tvm
make

# let python know where to find tvm related libraries
export PYTHONPATH=python
rm -rf python/tvm/*.pyc python/tvm/*/*.pyc python/tvm/*/*/*.pyc

TVM_FFI=ctypes python -m pytest -v tests/python/unittest/test_pass_storage_rewrite.py

# Additionally if you want to run a single test, for example test_all_elemwise inside a file.
TVM_FFI=ctypes python -m pytest -v -k "test_all_elemwise" tests/python/frontend/tflite/test_forward.py