Hy 项目贡献指南:从报告 Bug 到合入 PR 的完整协作流程

原创2026-10-12 16:22:561,614 阅读
文章标签:编程语言编译器语言运行时

Hy 项目贡献指南:从报告 Bug 到合入 PR 的完整协作流程

本文以仓库根目录的 CONTRIBUTING.rst 为主线,系统梳理 Hy(一种嵌入 Python 的 Lisp 方言)的开源协作规范:从 Issue 提交流程、Commit 信息要求,到 pytest 测试机制、Sphinx 手册构建、NEWS/AUTHORS 维护与 PR 合入规则,并逐项结合仓库源码验证其落地方式。读完本文,你将能按官方规范提交一份可被审查、可被合入的 Hy 代码或文档 PR。

欢迎各种形式的贡献

文档开篇即明确:Hy 欢迎且高度赞赏一切贡献,"每一小点都有帮助"。官方列举的潜在贡献形式包括:

  • 报告并修复 bug;
  • 请求新特性;
  • 添加新特性;
  • 为未解决的 bug 或未经测试的特性编写测试(对 Hy 暂时无法通过的测试,可以用 xfail 标记,见后文"xfail 机制");
  • 清理代码;
  • 改进文档;
  • 在项目的 Discussions 讨论页或 Stack Overflow 上回答问题;
  • 在自己的组织、用户组、会议甚至公交车站宣传 Hy。

这份清单说明 Hy 的贡献门槛刻意保持得很低:测试、文档、答疑与推广同样属于贡献,并非只有提交代码才算。

Issue:报告 bug 与请求特性的正确姿势

Hy 使用统一的 issue 追踪渠道来处理 bug 报告、特性请求与文档问题。

  1. 先查重:报告 bug 或请求特性前,先搜索 issue 追踪器,确认没有重复条目。
  2. 用最新的 master 复现:报告 bug 时,应确保能用在 master 分支上的最新开发版复现。稳定版中的 bug 通常也是先在 master 上修复,随后才进入新的稳定版本。
  3. 拿不准就直接发:文档明确写道"不确定某件事是不是 bug 时,完全可以创建 issue",维护团队会帮忙判断——这进一步降低了报告门槛。
  4. 文档问题同渠道:文档本身的错误或缺失,也使用同一个 issue 追踪器报告。

动手之前:重大变更先讨论

若你打算对 Hy 语言本身提出重大变更,或对某个改动方向没有把握,建议先创建 issue 讨论清楚,再开始写代码。这样能让其他人尽早对想法给出反馈,避免大量返工。

Commit 信息规范:让历史清晰可读

文档对提交历史的质量有明确要求:

  • 粒度组织:很多 PR 足够小,一个 commit 即可;较大的 PR 应按逻辑单元拆分为多个独立 commit。
  • 杜绝三种情况:PR 中不应出现 merge commit,不应出现"修复或回退同一 PR 内其他 commit"的 commit——文档直接建议使用 git rebase 来整理。
  • 保持干净:避免提交无意义的空白字符改动。
  • 不留 TODO 注释:不要提交带有 "FIXME"、"TODO"、"XXX" 之类标记的注释。代码或文档应该如何改进的想法应进入 issue 列表,而不是留在代码里。
  • 首行精炼:commit message 的第一行应在 50 个字符内概括整体改动;如需补充更多信息,用空行与首行分隔,再接正文。

一个符合规范的 commit message 示例:

Fix a crash when using require in hy.eval

The require form was leaving a stale symbol in the local scope,
which caused a crash when hy.eval was invoked with require.
Closes #1234

测试:pytest 与 xfail 机制

运行全部测试

在仓库根目录执行 pytest 即可运行整个测试套件:

$ pytest

新代码必须配测试

新特性和 bug 修复都应编写测试。如果你修复 bug 时它关联了某个 GitHub issue,应在测试注释中附上该 issue 的 URL,方便追溯。任何 PR 只要导致测试失败,就不允许被合入——这是硬性门槛。

xfail:标记"预期失败"的测试

有些测试针对尚未实现或环境不支持的场景,可以用 pytest 的 xfail 机制标记为"预期失败",而不是直接跳过。仓库中就有现成实例:tests/test_bin.py 中

@pytest.mark.xfail(not PY3_10, reason = 'not worth debugging, since CPython 3.9 is unmaintained and this is a minor, undocumented feature')
def test_pdb_ll(tmp_path):

如果某天你让一个 xfail 测试开始通过,记得移除它的 xfail 标记,让它正式回归测试套件。

清理字节码缓存

测试文件的字节码编译产物(__pycache__、.pyc 等)可以用以下命令一次性清除:

$ git clean -dfx tests/

跳过慢速测试

test_bin.py 中包含大量通过子进程启动 hy 命令的端到端测试,运行较慢。只想快速迭代时,可以用:

$ pytest --ignore=tests/test_bin.py

源码佐证:测试是如何组织的

从仓库实际结构看,Hy 的测试被组织成多个层次,每一层都有对应的配置与收集机制:

  • pytest 配置:setup.cfg 中定义了 [tool:pytest] 段,其中 python_functions=test_* hyx_test_* 让 pytest 同时识别 Python 常规函数与 Hy 名称 mangling 后的测试函数;filterwarnings 则将 DeprecationWarning 等警告统一收敛。

  • 原生(native)测试收集:conftest.py 通过 pytest_collect_file 钩子把 tests/native_tests/ 下的 .hy 文件(__init__.hy 除外)直接收集为 pytest 测试模块;同时 conftest.py 会在测试开始时弹出 HYSTARTUP 环境变量,避免用户 REPL 启动脚本干扰测试结果(关联 hylang/hy 的 issue #2029)。

  • 原生测试的写法:tests/native_tests/operators.hy 展示了 Hy 惯用的"宏驱动测试"——定义一个 op-and-shadow-test 宏,自动为每个操作符生成"真实操作符"与"shadow 操作符"两组测试函数,例如:

    (import pytest)
    (import hy.pyops *)
    
    (defmacro op-and-shadow-test [op #* body] ...)
    
    (op-and-shadow-test +
      (assert (= (f 1 2) 3))
      (assert (= (f "a" "b" "c") "abc")))
    
  • 导入/编译测试:tests/importer/test_importer.py 中的 test_import_error_cleanup 验证失败的导入不会在 sys.modules 中留下死模块,test_import_autocompiles 验证 (import) 会对模块进行字节码编译(在字节码生成被禁用时该测试通过 skipif(sys.dont_write_bytecode, ...) 跳过)。

文档贡献:构建 Sphinx 手册

一般来说,新特性都应获得手册覆盖,方式有两种:直接编辑手册源文件,或修改会被并入手册的 docstring。渲染手册前需先安装依赖:

$ pip install -r docs/requirements.txt

然后用 Sphinx 构建 HTML 手册:

$ cd docs; sphinx-build . _build -b html

从源码看,docs/requirements.txt 锁定 Sphinx == 5.0.2、Pygments >= 2.18.0,并引入 sphinxcontrib-hydomain 扩展(Hy 专用 Sphinx 域);docs/conf.py 中启用了 napoleon、intersphinx、autodoc 与 hydomain 扩展,手册的版本号直接取自 hy.__version__,HTML 主题为 nature 并挂载了自定义样式 docs/_static/custom.css。这意味着"改源码 docstring → 重新构建手册 → 文档自动更新"是一条完全自动化的链路。

NEWS 与 AUTHORS:变更记录与署名

  • NEWS:只要你对代码做了用户可见(user-visible)的改动,就应在 NEWS 文件中添加一条或多条描述。NEWS.rst 展示了其组织方式:Hy 自 1.0.0 起采用语义化版本,Unreleased 区块按 Bug Fixes、Misc. Improvements 等分类登记待发布变更,每个正式版本再归入独立版本块(如 1.3.0,附昵称与发布日期)。
  • AUTHORS:最后,别忘了把自己加入 AUTHORS 文件——格式为 * 姓名 <邮箱>,并且要作为一个单独的 commit 提交("you deserve it")。这是 Hy 给每位贡献者的署名仪式。

提交 PR:分支、关联 Issue 与合入规则

分支策略

PR 应请求将一个为它新建的分支合入 master,且该分支应尽量基于最新的 commit 创建。

"Fixes #123" 精确措辞

如果 PR 解决了一个或多个 issue,应在 PR 正文(或其中某个 commit 的 message)中逐条写明 Fixes #123 或 Closes #123(大小写不敏感)。这是有实际作用的:这类文本随 PR 合入后,GitHub 会自动关闭被提及的 issue。反过来,如果你只想"提及"某个 issue 而不想关闭它(例如只修复了部分 bug),就应刻意避免使用这个精确措辞。

两条合入通道

PR 只有满足以下任一条件才允许被合入:

  1. 获得除作者外 两位 Hy 核心团队成员批准;文档改动或琐碎代码改动只需 一位 批准;
  2. 或 PR 已存在 至少三天,且没有任何核心团队成员对当前状态的 PR 表示反对。

任何核心团队成员都可以执行合入操作。

合入方式与典型工作流

合入应当创建 merge commit:既不要不必要地 squash(那会抹掉逻辑上相互独立的 commit 之间的区分),也不要 fast-forward(那会丢掉"这些 commit 曾是一个独立分支"的历史)。merge commit 的 message 中应包含 PR 编号。文档给出的典型合入工作流如下(在自己的机器上执行后,再到平台上点合并按钮):

$ git checkout master
$ git pull
$ git checkout $PR_BRANCH
$ git fetch
$ get reset --hard $REMOTE/$PR_BRANCH   # 原文如此,应为 git reset
$ git rebase master
$ git push -f

需要注意的是,文档原文中第五行写作 get reset --hard $REMOTE/$PR_BRANCH,从上下文看显然是 git reset 的笔误。

行为准则(Contributor Code of Conduct)

作为贡献者与维护者,Hy 项目承诺尊重所有通过报告 issue、发布特性请求、更新文档、提交 PR 或补丁等方式参与项目的人;并承诺让参与过程对所有人都是无骚扰的体验,不论其经验水平、性别、性别认同与表达、性取向、残疾、外貌、体型、种族、民族、年龄或宗教。

被明确视为不可接受的行为包括:使用性语言或性意象、贬损性评论或人身攻击、trolling、公开或私下骚扰、侮辱以及其他不专业的行为。项目维护者有权且负有责任移除、编辑或拒绝与行为准则不符的评论、commit、wiki 编辑、issue 及其他贡献;违反准则的维护者也可能被移出项目团队。准则既适用于项目空间,也适用于个人代表项目时的公共空间。遇到虐待、骚扰或其他不可接受的行为,可以通过开 issue 或联系一位或多位维护者举报。该准则改编自 Contributor Covenant 1.1.0。

小结

纵观整份贡献指南,Hy 刻意维持着"低门槛 + 明确规则"的平衡:任何形式的贡献都受欢迎,拿不准的问题可以直接提 issue;而一旦提交 PR,就必须满足测试全绿、Commit 规范、NEWS/AUTHORS 登记、双人批准或三天静默期等明确要求。这套流程既保证了 Lisp 方言这门"嵌入 Python 的语言"在语法、语义演进上的审慎(重大变更先讨论),又通过 xfail 标记、pytest --ignore 等机制让贡献者能快速迭代。如果你准备为 Hy 贡献第一个补丁,按本文顺序走一遍:查 issue → 讨论 → 写测试 → 跑 pytest → 建 PR → 等合入,即可完整体验这套开源协作流程。

登录后查看全文
hy