Apache TVM 贡献者指南:从提交 PR、代码评审到版本发布的完整协作流程
Apache TVM 贡献者指南:从提交 PR、代码评审到版本发布的完整协作流程
本篇指南以 Apache TVM(面向 CPU、GPU 与专用加速器的开源深度学习编译器栈)官方 贡献者指南 为核心骨架,系统讲解参与 TVM 社区开发的完整路径:社区治理模型、PR 提交与提交信息规范、本地测试与 CI 使用、代码评审文化、C++/Python 代码风格、文档撰写规范、Git 协作技巧、错误处理约定以及版本发布流程。读完本文,你将掌握在 TVM 仓库中提交高质量补丁、通过评审并顺利合入的全部实战要点,同时了解背后支撑这些流程的仓库脚本与源码依据。
贡献形式概览:不止是写代码
TVM 是一个由社区成员共同开发的项目,欢迎任何人以任何形式参与。官方指南明确列举的贡献形式包括:
- 对已有补丁(patch)进行代码评审;
- 编写文档与使用示例;
- 在论坛和 issue 中参与社区讨论;
- 改善代码可读性与开发者指南——包括为代码添加注释、撰写解释内部设计选择的文档;
- 提交测试用例增强代码库的健壮性;
- 通过教程、博客、演讲推广项目。
仓库中保留了完整的贡献者名单 CONTRIBUTORS.md,这也是社区识别潜在 committer 的依据之一。
TVM 社区治理模型
TVM 遵循 Apache 风格模型,以 merit(功绩)为核心进行治理,目标是构建一个开放、包容的社区。相关详细内容见 community.rst。
角色体系:Reviewers、Committers 与 PMC
- Reviewers:积极参与贡献并愿意参与代码评审的人。任何 PR 在合入前至少需要一名 reviewer 评审通过。
- Committers:被授予项目写权限的个人,通常负责某个或多个代码区域,监督该区域的代码评审流程。社区会主动从活跃贡献者中物色新 committer,考察点包括:持续的贡献(RFC 讨论、代码评审、新功能提案)、贡献质量(可读性强、含良好测试用例、能提供高质量的评审意见)以及社区参与度。
- PMC(项目管理委员会):由活跃 committer 组成,负责调节讨论、管理版本发布、提名新的 committer/PMC 成员。新成员提名通常需内部共识批准(至少 3 个 +1 票且无否决票),任何否决必须附有理由。
战略决策的投票机制
以下战略决策需要 lazy 2/3 多数(至少 3 票,且 +1 票数量是 -1 票的两倍)的约束性投票通过:
- 采纳指导级别的社区战略,以支持项目新方向或整体演进;
- 在项目中建立新的模块;
- 采纳新的代码库——当现有已发布产品的代码库将被替代代码库替换时;投票未通过则维持现状。
所有决策都应在社区公开讨论后进行,并作为讨论摘要被记录归档。
提交流程:PR 的完整生命周期
pull_request.rst 给出了提交 PR 的完整规范。
提交前准备
- 范围聚焦:建议提交边界清晰、易于评审、便于回退的 PR,避免把多个无关改动塞进一个 PR。
- 基于最新 main 变基:提交前将代码 rebase 到最新的
main分支:
git remote add upstream [url to tvm repo]
git fetch upstream
git rebase upstream/main
- 通过 lint 检查:CI 与本地使用相同的 lint 命令:
# 精确复现 CI 的 lint 流程(常用于调试 lint 脚本错误或避免手动安装工具)
python tests/scripts/ci.py lint
# 运行全部 lint 步骤
docker/lint.sh
# 单独运行某个 lint 步骤(拼错步骤名会打印出所有可用步骤)
docker/lint.sh <step_name> ...
实际运行 docker/lint.sh 时会发现它通过 DEFAULT_STEPS=( file_type asf clang_format cpplint python_format pylint jnilint cppdocs mypy ) 依次执行文件类型检查、ASF 头检查、clang-format、cpplint、Python 格式、pylint、Java lint、C++ 文档与 mypy 检查,每个步骤对应 tests/lint/ 下的独立脚本。若 clang-format 检查失败,可用以下命令自动重排改动文件的格式:
# 对自 upstream/main 以来所有改动文件运行 clang-format 检查
docker/bash.sh ci_lint ./tests/lint/git-clang-format.sh --rev upstream/main
- 补充测试用例:为新功能或 bug 修复添加测试覆盖。
- 编写文档:参见 document.rst 的文档规范。
- 创建 PR 并修复 CI 问题:根据 CI 检查报告逐项修复。
- 主动请求评审:在 PR 中
@相关贡献者。PR 标题中的标签会自动标记订阅用户,因此请把相关主题放进标题,例如[microTVM] Add a cool change,而不是a cool change for microTVM。
Commit Message 规范
TVM 使用 GitHub 平台进行补丁提交与代码评审,最终合入 main 树的 commit 由 PR 的标题和正文组成,因此两者必须随评审进展持续保持更新。GitHub 会用分支上的 commit 自动生成 PR 标题与正文,所以建议从准备 commit 阶段就遵循这些规则。
标题规则(强制项包括):
- 必须存在标题;
- 标题中不得出现 GitHub 用户名(如
@username); - 必须包含组件标签作为提示,例如
[BugFix]、[CI]、[microTVM]、[TVMC]。标签放在方括号内且位于标题最前;多标签使用多个括号,如[BugFix][CI]。推荐使用 Upper Camel Case(如[Fix]、[BugFix]、[Docker]),缩写保持原样(如[CI]、[TVMC])。标签帮助 reviewer 识别可审的 PR,也帮助发布团队生成 release notes; - 使用祈使语气:写 "Add feature X" 而不是 "Added operator X";
- 首字母与缩写大写规范:写 "Fix TVM use of OpenCL library" 而不是 "fix tvm use of opencl library";
- 标题末尾不加句号。
正文规则:
- 必须存在正文;
- 不得使用 GitHub 用户名;
- 避免"纯 bullet"正文——没有描述或解释的 bullet 列表与没有正文同样糟糕。
正文的核心是传达改动的意图,避免含糊。例如标题为 "Fix"、"Cleanup"、"Fix flaky test" 且没有正文的 commit 应当避免,因为评审者无法得知到底修了什么、为什么需要修。官方给出的示范格式如下:
[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'.
对于评审后的追加 commit,没有提交信息的硬性要求;但若追加改动使 PR 标题/正文过时,作者有责任保持其与最新代码一致——因为 PR 标题与正文最终会构成落入 main 树的 commit message。标题/正文缺失不属于"轻微偏差",必须避免。社区对轻微偏差通常以提醒为主,而非回退或封锁。
本地测试:Docker、C++ 与 Python 三套方案
尽管 CI 会自动为每个 PR 运行单元测试,官方仍强烈建议先在本地运行测试,以减轻 reviewer 负担并加速评审。详见 pull_request.rst 的 Testing 章节。
Docker(推荐)
tests/scripts/ci.py 在本地复刻 CI 环境并提供友好接口,直接复用 CI 的 Docker 镜像与脚本。它把构建产物存放在不同的目录(如 build-cpu/),因此可以同时维护多个测试环境而无需每次重新构建(例如同时测试 CPU 与 i386 而保留增量编译):
# 查看所有可用平台
python tests/scripts/ci.py --help
python tests/scripts/ci.py cpu --help
# 在 ci_cpu 容器中执行 CPU 构建(构建产物留在 build-cpu/ 目录)
# 注意:CPU 与 GPU 镜像较大,首次下载需要一定时间
python tests/scripts/ci.py cpu
# 构建后继续运行单元测试
python tests/scripts/ci.py cpu --unittest
# 快速迭代:跳过重建,只跑指定测试
python tests/scripts/ci.py cpu --skip-build --tests tests/python/tir-transform/test_tir_transform_inject_rolling_buffer.py::test_upscale
# 构建后进入容器 shell
python tests/scripts/ci.py cpu --interactive
从 tests/scripts/ci.py 的源码可以看到其设计:get_build_dir(name) 将构建目录定位到仓库根下的 build-{name},构建流程调用 ./tests/scripts/task_config_build_{name}.sh 生成配置、再由 ./tests/scripts/task_build.py --build-dir {build_dir} 执行编译,测试阶段通过 TVM_LIBRARY_PATH 环境变量指向对应构建目录。
Docker 镜像会随版本更新而累积,可用如下命令清理当前分支及 worktree 不再使用的陈旧镜像:
docker/clear-stale-images.sh
更多选项请查阅 --help。
C++ 测试(本地)
运行 C++ 测试需要安装 gtest(安装指引见 from_source.rst):
# 假设位于 tvm 源码根目录
TVM_ROOT=`pwd`
./tests/scripts/task_cpp_unittest.sh
该脚本入口对应 tests/scripts/task_cpp_unittest.sh。
Python 测试(本地)
依赖安装:
pip install --user pytest Cython
运行全部测试:
# 先构建 tvm
make
./tests/scripts/task_python_unittest.sh
运行单个测试文件:
# 先构建 tvm
make
# 让 python 找到 tvm 相关库
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
筛选文件内的单个测试用例:
TVM_FFI=ctypes python -m pytest -v -k "test_all_elemwise" tests/python/frontend/tflite/test_forward.py
代码评审:质量门槛与协作文化
code_review.rst 是一份开放式的评审实践指南,强调开源代码由背景多样的社区维护,评审是"shepherding(引导)"过程,用于共同发现问题、提升代码质量、教育贡献者与评审者。
建立信任与社区参与
- 评审基于信任,需要时间与投入去建立和维护;
- 所有人欢迎在任何 PR 上留言;对于包含重大架构变更的 PR,committer 应等待一段时间(如三天)再合入,给社区表达意见与参与的机会;
- 注意成员差异(时区、工作时间、行程),避免单点瓶颈;帮助他人合入 PR 是鼓励更广泛参与的最好方式。
仔细阅读代码
快速浏览代码只抓取部分方面的评论虽然有用,但只是评审的一部分。一次认真细致的评审是很大的时间投入,有时甚至超过写代码本身。committer 在点击 merge 前必须仔细阅读并理解代码;若合并后出现问题,合入者有责任跟进后续处理。
保持尊重
对评论者:建设性评论能帮助新贡献者及时合入 PR。对作者:评审者应花大量时间读代码,认真回复评审意见,并将来通过帮助评审他人来回报。
代码质量考量因素(F0-F4)
评审时应考虑以下质量因素,按重要性排序:
- F0 整体架构:公共模块、关键数据结构与公共接口的定义,好的架构选择是项目长期成功的关键;
- F1 架构一致性:新功能必须与既有架构选择一致、与现有代码良好交互。每个新功能都会增加项目复杂度,一致的设计能最小化复杂度增量;
- F2 健壮性与测试覆盖:确保代码在所有平台/环境下正确运行,保证新功能的测试覆盖,面向用户的错误要有清晰的错误信息;
- F3 面向用户的 API 文档:公共 API 与关键模块接口的文档是强制的,包括出现在公共接口中的 API 与数据结构(即
include/tvm目录与面向用户的 Python API); - F4 代码可读性:指示明确一致的函数命名、清晰的实现流程、对复杂逻辑与内部函数的描述性注释。
架构设计与一致性最重要,因为它们最可能引入长期技术债。测试覆盖与 API 文档是代码贡献的期望项。可读性相对主观,评审者应给出建设性、可执行的评论,但不应借评审要求别人完全按你的方式写代码。
共识建设与额外建议
- 分歧通过建设性的技术讨论解决;负责该区域的 committer 可作为 shepherd,综合所有意见后建议前进方向;
- 若贡献者认为指南应用不一致,应倾听并持续迭代流程;
- 审慎设计 API 与数据结构:API 一旦被接受就极难更改。原则包括:与知名包 API 一致(如张量算子 API 与 numpy 一致)、与项目内既有 API 一致(如优化 pass 的参数顺序)、考虑未来演进(把优化旋钮封装进构建配置对象)、必须写文档、追求最小化(想想用户写几行代码才能用你的 API,尽量去掉抽象层);
- 最小化依赖:功能只在用户实际使用时才引入依赖;
- 简洁实现:优先向量化数组代码而非循环,优先使用已有 API;
- 沉淀经验:发现可复用的教训时,补充到 code_guide.rst;
- 明确批准/请求修改:评论被处理后记得点 Approve;若部分 reviewer 超时未响应(如一周)而现有评审已充分,code owner 可逐案决定是否合入;
- reviewer 应保持及时反馈,无活动 PR 会有 bot 自动提醒相关方。
Committer 指南:治理角色的责任
committer_guide.rst 为 committer 提供实践建议。
- 社区优先:做决策时把社区放在心中,如"如何鼓励新贡献者更多参与?""能否节省同僚时间?""是否让社区参与了设计提案?"
- 公共归档原则:Apache 方式要求所有决策在公开、可归档的渠道进行。个人渠道收到项目问题时应鼓励对方在讨论论坛开公开帖;线下讨论后应把摘要发到公开渠道(RFC 或讨论帖);
- 独立项目管理:参与项目时默认佩戴 Apache committer 的帽子;容易混淆时可声明当前角色(如 "Wearing [foo] hat: ...");
- Shepherd 一个 PR:将 PR 分配给自己表明已接管;使用状态标签;检查是否需要 RFC;帮助新贡献者请求 reviewer;调节评审并要求明确批准;标记为 accepted 并致谢贡献者与 reviewer;然后合并;
- 时间管理:例如每周设立一个"社区日"集中处理积压 PR;
- 广泛协作:主动为不常线下接触的社区成员做 shepherd 与请求评审。
代码风格指南:C++ 与 Python 的约定
code_guide.rst 记录了评审者与贡献者应遵循的编码约定,多数来自实际贡献过程中的教训总结。
C++ 风格
- 使用 Google C/C++ 风格;
- 公共函数使用 doxygen 格式文档;
- 优先使用具体类型声明而非
auto(只要不长); - 优先按 const 引用传递(如
const Expr&);除非函数通过拷贝构造或移动来消费值,此时按值传递优于 const 引用; - 尽量使用
const成员函数。
clang-format 用于强制执行风格。不同版本的 clang-format 行为可能不同,推荐使用与主线一致的版本,可通过 docker 运行:
# 对单个文件运行 clang-format
docker/bash.sh ci_lint clang-format-10 [path-to-file]
# 运行所有 linter(含 clang-format)
python tests/scripts/ci.py lint
clang-format 并非完美,必要时可在特定区域禁用:
// clang-format off
void Test() {
// clang-format 在此区域被禁用。
}
// clang-format on
由于 clang-format 可能无法识别宏,建议宏像普通函数那样书写:
#define MACRO_IMPL { custom impl; }
#define MACRO_FUNC(x)
// 不推荐:clang-format 可能把它识别为类型
virtual void Func1() MACRO_IMPL
// 推荐
virtual void Func2() MACRO_IMPL;
void Func3() {
// 推荐
MACRO_FUNC(xyz);
}
Python 风格
- 函数与类使用 numpydoc 格式文档;
- 用
python tests/scripts/ci.py lint检查风格; - 使用 Python 3.7 的语言特性;
- 对于平行且短函数体的函数,优先
if/elif/else链;对于过程式函数(最后一个else块远长于if/elif块),优先让最终 else 情况不缩进(pylint 的no-else-return检查已被禁用以允许这种区分):
# 各分支体流程控制相似,用 if/elif/else 链更清晰
def sign(x):
if x > 0:
return "+"
elif x < 0:
return "-"
else:
return ""
# 首个特殊分支是提前返回,后续是更通用的方法,
# 用 else 只会给函数其余部分增加不必要的缩进
def num_unique_subsets(values):
if len(values)==0:
return 1
# 更长的通用解法写在这里
...
编写 Python 测试
所有 Python 测试使用 pytest,测试代码位于 tests/python。若希望测试在多种目标上运行,使用 tvm.testing.parametrize_targets 装饰器:
@tvm.testing.parametrize_targets
def test_mytest(target, dev):
...
它会让 test_mytest 分别以 target="llvm"、target="cuda" 等运行,并确保 CI 在正确的硬件上执行该测试。仅测部分目标时使用 @tvm.testing.parametrize_targets("target_1", "target_2");只测单一目标时使用 tvm.testing 中对应的装饰器,例如 CUDA 测试用 @tvm.testing.requires_cuda。
网络资源与整数常量处理
CI 中从互联网下载文件是 flaky 失败的一大来源,测试期间应尽量避免联网(教程类文档下载模型属例外情况)。需要托管文件时,可由 committer 通过 workflow_dispatch 事件上传到 S3 并在 request_hook.py 的 URL_MAP 中登记新 URL。
处理常量整数表达式时,优先思考是否真的需要常量:如果符号表达式也能工作,应尽量使用符号表达式,使生成代码支持事先未知的形状。确实需要获取常量时,应使用 int64_t 而非 int 以避免整数溢出,并通过 make_const 重建对应表达式类型:
Expr CalculateExpr(Expr value) {
int64_t int_value = GetConstInt<int64_t>(value);
int_value = CalculateExprInInt64(int_value);
return make_const(value.type(), int_value);
}
文档撰写规范
document.rst 说明 TVM 文档参照 Divio 的正式文档风格组织,分为四类:
- 入门教程(Introductory Tutorials):面向新用户的逐步引导,目标是让用户获得成功的第一体验,可重复且可靠;
- How-to 指南:面向有一定经验的用户,解决具体问题(如"如何为 ARM 架构编译优化模型?"),实用性强于完备性,标题应说明解决的问题;
- Reference 参考文档:描述软件如何配置与操作,包括 API、关键函数、命令与接口,尽可能与代码库同构并自动化生成;
- 架构指南(Architecture Guides):解释背景与设计决策——为什么是这样、考虑过哪些替代方案、描述现有系统的 RFC 是什么。
TVM 的特殊之处在于用户与开发者社区高度重叠,因此教程与 how-to 分为"User Guides"与"Developer Guides"两类;microTVM、VTA 等专题有专门的 "Topic Guides";另设 "Getting Started" 区方便新手。
技术细节
- 主文档使用 Sphinx 构建,支持 reStructuredText 与 markdown,优先推荐 rST(特性更丰富);Python doc-string 与教程中可嵌入 rST 语法。构建说明见 docs/README.md。
- Python 参考文档使用 numpydoc 格式,所有公共函数都要写文档,必要时给出使用示例;注意各 section(
Parameters、Returns、Examples)前后必须留空行。新增函数需在docs/reference/api/python下添加 sphinx.autodoc 规则。 - C++ 参考文档使用 doxygen 格式:
/*!
* \brief Description of my function
* \param arg1 Description of arg1
* \param arg2 Descroption of arg2
* \returns describe return value
*/
int myfunction(int arg1, int arg2) {
// When necessary, also add comment to clarify internal logics
}
- Sphinx Gallery 用于构建 Python how-to,源码位于 gallery/,注释块用 reStructuredText 书写。how-to 代码会在构建服务器上运行以生成文档页;如无法访问远程设备(如远程树莓派),可在教程中加标志变量(如
use_rasp)让用户一键切换。新增 how-to 分类时需在 docs/conf.py 与 how-to 索引中注册。 - 文档内部引用使用 Sphinx 的
:ref:标记。 - 含图片的文档:图片文件与使用图片的
.rst分属不同仓库,需要两个 PR 配合,且必须先合入图片仓库的 PR 再合入主仓库 PR,保证文档 URL 有效。
Git 协作技巧
git_howto.rst 汇总了开发中常用的 Git 操作。
解决与 main 的冲突
# 前两步做完一次后可以跳过
git remote add upstream [url to tvm repo]
git fetch upstream
git rebase upstream/main
出现无法自动合并的冲突文件(如 conflicted.py)时:手动修改解决冲突 → git add conflicted.py 标记已解决 → git rebase --continue 继续变基 → git push --force 推送 fork(可能需要强制推送)。
合并多个 commit 为一个
后续 commit 只是对前序的修补时,通常需要合并成有意义的 commit 集:
# 先配置 git 默认编辑器
git config core.editor the-editor-you-like
# 假设合并最近 3 个 commit
git rebase -i HEAD~3
在文本编辑器里将第一个 commit 设为 pick,后续改为 squash;保存后再次弹出编辑器修改合并后的 commit message,最后 git push --force。
重置到最新 main
注意:所有本地改动都会丢失,仅在无本地改动或 PR 刚被合入时使用:
git fetch origin main
git reset --hard FETCH_HEAD
误重置后恢复
git reflog 可列出最近 commit,找到正确哈希后用 git reset 重新指向。
只把最近 k 个 commit 应用到 main 之上
当你的前 m 个 commit 已被合入、直接 rebase 会引发无谓冲突时:
# k 是具体数字;HEAD~2 表示最后一个 commit
git rebase --onto upstream/main HEAD~k
该命令会丢弃最后 k 个之前的所有 commit。
关于 force push 的说明
前两种操作需要 force push,因为改变了 commit 的路径。只要改动只涉及你自己的 commit,对自己的 fork 强制推送是没问题的。
使用 TVM 的 CI
ci.rst 介绍 CI 系统。TVM 主要通过 Jenkins 在 Linux 上运行持续集成测试(配置见 ci/jenkins/templates/ 下的 Jenkinsfile 模板),Jenkins 是唯一被编码为"阻塞合入"的 CI 环节;Windows 与 macOS 则由 GitHub Actions 做最小化测试。一次 CI 运行通常耗时数小时,PR 在 CI 成功完成前不能合入。
面向贡献者:诊断失败
- 通过 Jenkins BlueOcean 视图进入失败的 pipeline stage,再进入失败步骤查看输出日志;
- Jenkins 默认不显示完整日志,日志查看器顶部有 "Show complete log" 按钮可查看纯文本版本;
- pytest 失败会汇总在日志底部,但通常需要向上滚动查看实际失败位置;
- 大多数 Python 测试在 pytest 下运行,可按上文的本地测试方法复现;
- CI 相关问题应在 issue 中报告,附上相关 job、commit 或 PR 链接。
面向维护者:保持 CI 绿色
并发合入导致的 main 破坏:两个 PR 各自通过 CI 但合入后互相破坏 main,会在无关 PR 上暴露错误。责任在合入该 PR 的 committer,典型处理是:回退问题 commit,或提交前向修复。
处理 flaky(偶发)失败:若失败与你的改动无关,先搜索是否有相关 issue,没有则新开 issue。若某测试影响多个 PR 或 main 上的多次提交,应使用 pytest 的 @xfail 装饰器禁用(strict=False 并链接相关 issue):
@pytest.mark.xfail(strict=False, reason="Flaky test: https://github.com/apache/tvm/issues/1234")
def test_something_flaky():
pass
然后正常提交 PR:
git add <test file>
git commit -m'[skip ci][ci] Disable flaky test: ``<test_name>``
See #<issue number>
'
gh pr create
跳过 CI([skip ci]):对于 revert 与琐碎的前向修复,在 PR 标题加 [skip ci] 会让 CI 短路只跑 lint。committer 应只在修复 main 失败时使用,不能用来加速合入。PR 标题在构建首次运行时被检查(在 lint 步骤中),之后的标题修改不会影响 CI:
# 回退 HEAD commit,务必在 commit subject 开头插入 '[skip ci]'
git revert HEAD
git checkout -b my_fix
git push my_repo
# 示例:在已有 PR 的分支上触发跳过 CI
git commit --allow-empty --message "[skip ci] Trigger skipped CI"
git push my_repo
Docker 镜像管理
每个 CI job 的大部分工作在 Docker 容器内完成,镜像由 docker/ 下的 Dockerfile 构建(如 Dockerfile.ci_cpu、Dockerfile.ci_gpu)。
更新镜像 tag 的流程:合入修改 docker/ 下 Dockerfile 或 docker/install 脚本的 PR → 等待 post-merge CI 或 nightly 构建把新镜像上传到 Docker Hub → 找到新 tag(形如 20221208-070144-22ff38dff)并更新 ci/jenkins/docker-images.ini 中对应的 tag → 提交 PR 验证镜像有效性 → 合入后 post-merge CI 完成时 tlcpackstaging tag 会自动重新上传到 tlcpack。
新增 Docker 镜像的步骤:定义 docker/Dockerfile.ci_foo 与 docker/install 下脚本(该 PR 只含这些改动)→ committer 本地验证并批准 → 在 Docker Hub 创建 ci-foo 仓库 → 创建 ECR 仓库 → 合入把镜像加入 Jenkinsfile 的 PR(必须从 apache/tvm 内的分支发起,不能从 fork)→ committer 把镜像加入 tlcpack 的每日重建/验证。
ci-docker-staging 分支:测试 Docker 镜像与 Jenkinsfile 改动用。fork 的普通 PR 构建时,Jenkins 使用 PR 的代码但 Jenkinsfile 来自基分支;而分支构建使用分支内的 Jenkinsfile。因此改动 Jenkinsfile 的 PR 需要 committer 推送到 apache/tvm 的分支来测试。
CI 监控轮值:部分测试偶发失败,CI 监控轮值会监视这些失败并视情况禁用测试,最终由测试作者修复并重新启用。
错误处理规范
error_handling.rst 定义 TVM 的结构化错误体系。TVM 内置多种结构化错误类,应尽量抛出具体错误类型,让用户能按错误类别编写处理逻辑。错误类型列表见 python/tvm/error.py。
在 C++ 中抛出特定错误
在错误消息前加 <ErrorType>: 前缀即可抛对应类型的错误;不带前缀时默认抛 tvm.error.TVMError。该机制同时适用于 LOG(FATAL) 与 ICHECK 宏:
// src/api_test.cc
void ErrorTest(int x, int y) {
ICHECK_EQ(x, y) << "ValueError: expect x and y to be equal."
if (x == 1) {
LOG(FATAL) << "InternalError: cannot reach here";
}
}
该函数注册为 PackedFunc 进入 Python 前端(名为 tvm._api_internal._ErrorTest)后,调用时会发生:
tvm.testing.ErrorTest(0, 1)抛出ValueError: Check failed: x == y (0 vs. 1) : expect x and y to be equal.;tvm.testing.ErrorTest(1, 1)抛出tvm.error.InternalError: cannot reach here,并附带 "TVM hint: You hit an internal error..." 提示。
可以看到,TVM 的 FFI 系统会把 Python 与 C++ 两边的堆栈信息合并到同一条消息中,并自动生成对应的错误类。
如何选择错误类型
遍历 tvm.error 中的错误类型,结合常识与现有代码的用法进行选择,保持错误类型数量适度。需要新增错误类型时:先发 RFC 提案(附描述与代码库内的使用示例)→ 在 tvm.error 中新增并写清文档 → 更新本文档的错误类型列表 → 修改代码使用新类型。
错误消息建议少用抽象包装,直接抛出更清晰:
def preferred():
# 非常清楚抛出的是什么以及错误消息是什么
raise OpNotImplemented("Operator relu is not implemented in the MXNet frontend")
def _op_not_implemented(op_name):
return OpNotImplemented("Operator {} is not implemented.").format(op_name)
def not_preferred():
# 多了一层间接
raise _op_not_implemented("relu")
若确需包装函数构造多行错误消息,请把包装放在同一文件中,便于其他开发者查找实现。
版本发布流程
release_process.rst 描述了 release manager 的完整职责。
发布前准备
- 准备 release notes:包含新特性、改进、bug 修复、已知问题与弃用等。TVM 有每月开发报告汇总进展,可辅助撰写;建议在切分支前开 issue 收集 release notes 草稿反馈,起点脚本见 tests/scripts/release/(内含
gather_prs.py、list_rfcs.py、make_notes.py、test_release_package.sh等)。 - 准备 GPG key:生成后上传到公共 key 服务器;换机器发布时用
gpg --export/gpg --import迁移;最后把签名 key 更新到仓库 KEYS 文件并同步到 ASF SVN(dev 与 release 目录)。
切发布候选(RC)
以 v0.6 为例:
- 提交一个包含两个 commit 的 PR:第一个把版本号从
0.6.dev0更新为0.6.0,第二个把版本号从0.6.0更新为0.7.dev0;PR 标题需注明[Dont Squash]; - 合入后在第一个版本号 commit 上切分支,分支名用基础版本号(
v0.6),并在分支 HEAD 打 tagv0.6.0.rc0:
git clone https://github.com/apache/tvm.git
cd tvm/
# 更新第一个 commit 的版本号
git add .
git commit -m "Bump version numbers to v0.6.0"
# 更新第二个 commit 的版本号
git add .
git commit -m "Bump version numbers to v0.7.dev0"
# PR 合入后,在第一个 commit 上切分支
git checkout <first-commit-id>
git branch v0.6
git push --set-upstream origin v0.6
git tag v0.6.0.rc0
git push origin refs/tags/v0.6.0.rc0
- 确保源码版本号正确,可运行
python3 version.py更新版本;RC 分支推送后应立即更新版本号; - 在 GitHub Releases 页 Draft 新 release:验证版本号、确保 TVM 可构建并通过单元测试;tag 必须匹配
v[0-9]+\.[0-9]+\.[0-9]+\.rc[0-9]模式;勾选 "This is a pre-release";发布后分支仍可改动,但 tag 固定,需要改动就必须打新 tag; - 需要移除旧 RC 时:
git push --delete origin v0.6.0.rc1; - 创建源码包产物并签名(
gpg --armor --output xxx.asc --detach-sig与shasum -a 512生成校验和); - 更新 main 上的版本号并打 dev tag(如
v0.11.dev0),保证 nightly 包版本正确; - 把产物上传到 GitHub release 页面与 ASF SVN 的 dev 目录。
Cherry-Pick 与投票
- RC 分支切出后、投票完成前,release manager 可从 main cherry-pick 修复。由于 release 分支受保护,需要针对 release 分支发起 PR(说明 cherry-pick 原因),且这些 PR 必须签名;
- 投票首先在 Apache TVM developers 列表(dev@tvm.apache.org)进行,也可发
[VOTE]开头的 GitHub issue(会自动镜像)。dev@ 投票要求至少 3 个 binding +1 票且 +1 多于 -1;ASF 中投票至少开放 72 小时,票数不足不能提前关闭投票。投票失败则修改发布内容、重新打 RC 并再次投票; - 投票通过后,把产物从 SVN dev 目录移动到 release 目录(仅 PMC 可操作),更新 KEYS,在 GitHub 创建正式 release tag(
v0.6.0)并删除 RC tag。
发布后工作
- 更新 tvm-site 网站的下载页(包含产物、GPG 签名与 SHA 哈希),并上传该版本的固定文档(若 CI 已删除 release 文档,可重启 Jenkins 上 release 分支的构建获取);
- 向 announce@apache.org 与 dev@tvm.apache.org 发送公告邮件,附 release notes 与下载页链接;
- Patch 版本只保留给关键 bug 修复,必须走与正式发布相同的流程,可由 release manager 决定把 RC 投票窗口缩短为 24 小时;每个 patch 版本需在 release 基础分支(如
v0.11)与 RC tag(如v0.11.1.rc0)上更新版本号。
仓库中的相关资源导航
- 贡献指南总目录:docs/contribute/index.rst
- 本地 CI 复刻工具:tests/scripts/ci.py,lint 总入口 docker/lint.sh
- 代码风格检查:tests/lint/(含 git-clang-format.sh 等)
- 本地测试脚本:tests/scripts/task_cpp_unittest.sh、tests/scripts/task_python_unittest.sh
- CI Docker 镜像:docker/,镜像 tag 配置 ci/jenkins/docker-images.ini
- 错误类型定义:python/tvm/error.py
- 版本管理脚本:version.py
- 发布辅助脚本:tests/scripts/release/
- 贡献者名单:CONTRIBUTORS.md