Transformers 贡献指南：从 Issue 到 Pull Request 的完整开源协作流程

本篇技术指南基于 Transformers 仓库的官方贡献文档（docs/source/de/contributing.md），系统讲解参与 Transformers 开源贡献的完整链路：如何规范地提交 Bug 报告与功能请求、如何实施一个新模型、如何配置可编辑开发环境、如何用 pytest/unittest 运行测试套件、如何用 make style 与 make check-repo 通过代码质量检查，以及如何正确同步 fork 仓库。读完本文，你将具备独立向 Transformers 提交可合并 Pull Request 所需的全部实操能力。

贡献方式总览：代码之外的价值同样重要

Transformers 的官方贡献文档开篇明确指出：任何人都可以贡献，且代码贡献不是唯一途径。回答社区问题、帮助他人、改进文档都是极具价值的贡献方式；甚至在博客中提及该项目、推荐该项目，也被视为对社区的一种支持。无论以何种方式参与，都需遵守仓库根目录的 行为准则。

文档同时说明，这份指南深受 scikit-learn 贡献指南的启发。具体到代码层面，主要有四条贡献路径：

• 修复现有代码中的已知问题——这是新手最推荐、风险最低的切入点；
• 创建 Issue——报告 Bug 或提出新功能请求；
• 实现新模型——为社区补充新的模型架构；
• 贡献示例与文档——改进 examples 与 docs 的内容。

如果不知道从哪里开始，官方推荐从"Good First Issue"列表入手：这类 Issue 面向初学者，通常会先创建 Pull Request 并关联 Issue，以便维护者追踪进度——如果贡献者中途没有时间继续，其他人也可以接手该 PR。想要更大挑战的，可以查看"Good Second Issue"标签。

规范地提交 Issue：Bug 报告与功能请求

报告 Bug 前必须完成的准备

Transformers 文档强调，报告的每一条新 Bug 都是库健壮性的来源。在创建 Issue 之前，需要做到：

1. 确认该 Bug 尚未被报告——使用 Issue 搜索功能排查重复项；
2. 确认问题出在库本身而非你自己的代码——如果不确定，官方建议先向社区论坛求助，以免 Issue 区被一般性问题淹没。

确认无误后，Issue 中必须包含以下信息，维护者才能快速复现和修复：

• 操作系统及版本，以及 Python、PyTorch、TensorFlow 的版本（如适用）；
• 一个简短、独立的代码片段，能在 30 秒内复现该 Bug；
• 抛出异常时的完整 Traceback；
• 其他有帮助的信息，例如截图。

为了自动输出操作系统与软件版本，文档提供了两条命令：

transformers env

也可以直接在仓库根目录运行：

python src/transformers/commands/transformers_cli.py env

从当前仓库源码看，env 命令的实际实现位于 src/transformers/cli/system.py 的 env() 函数（基于 typer 的 CLI 入口），它会收集并打印：transformers 版本、平台信息、Python 版本、huggingface_hub 版本、safetensors 版本、accelerate 版本及其配置文件、deepspeed 版本，以及 PyTorch 版本和加速器类型（CUDA / XPU / NPU / HPU）。因此 Issue 中贴出 transformers env 的完整输出，是帮助维护者快速定位环境问题的标准做法。

提交新功能请求的四要素

如果希望 Transformers 增加某项新功能，官方要求 Issue 包含：

1. 动机——这项功能对应什么痛点或项目需求，或者你是否已经尝试过实现；
2. 尽可能详细的描述——提供的信息越多，团队越能给出有效反馈；
3. 一个演示功能用法的代码片段；
4. 相关论文链接（如果功能基于某篇 Paper）。

文档中有一句很有启发性的总结："如果你的 Issue 写得足够好，那么在它创建的那一刻，工作就已经完成了 80%。"

实现一个新模型：需要先提供的信息

由于新模型不断涌现，文档要求有意实现新模型的贡献者，先在 Issue 中给出：

• 模型的简短描述与论文链接；
• 如果实现是开源的，附上实现代码链接；
• 如果模型权重可获取，附上权重链接。

当你准备亲自完成实现时，可以告知维护者，官方会协助将其加入 Transformers。文档同时指向一份专门的技术指南《如何向 Transformers 添加模型》（add_new_model 文档页）。仓库中 src/transformers/models/ 目录下已组织了几百个模型实现（每个模型一个子目录，包含 configuration_*、modeling_*、tokenization_* 等文件），新模型将遵循同样的目录结构规范。

文档扩展：低门槛的贡献入口

官方表示始终欢迎让文档更清晰、更精确的改进：错别字、缺失内容、表述不清或信息不准确的段落都可以反馈。如果自己没有兴趣动手，维护团队可以代为修改；如果有兴趣，他们会帮助你完成贡献。关于文档的生成、创建与书写规范，仓库中的 docs 目录说明 给出了完整指引（该目录下 source/en、source/zh 等按语言组织了数百篇文档源文件，docs/source/de 即本文所依据的德语文档所在目录）。

创建 Pull Request：完整开发工作流

前置要求与仓库准备

官方强烈建议：在写任何代码之前，先检索现有 PR 和 Issue，确认没有人正在处理同一主题；不确定时，先开一个新 Issue 征求反馈。此外需要基本的 git 知识。

Python 版本要求：文档原文要求 Python 3.9 或更高版本。需要注意，就当前仓库的实际代码而言，setup.py 中定义的 SUPPORTED_PYTHON_VERSIONS = (10, 14)，即当前开发版实际支持 Python 3.10 至 3.14，python_requires 会据此生成为 >=3.10.0。贡献时建议以仓库构建配置为准并选择支持范围内的 Python 版本。

准备工作分四步：

第 1 步：Fork 仓库。 点击仓库页面上的 Fork 按钮，将代码副本创建到你的 GitHub 账号下。

第 2 步：克隆你的 fork 并添加 upstream remote：

git clone [e-mail]:<your Github handle>/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git

第 3 步：创建新分支。

git checkout -b a-descriptive-name-for-my-changes

文档特别警告：不要在 main 分支上直接工作。

第 4 步：搭建开发环境。 在虚拟环境中以可编辑模式安装：

pip install -e ".[dev]"

如果虚拟环境中已经安装了 transformers，需先用 pip uninstall transformers 卸载，再用带 -e 标志的可编辑模式重新安装。文档还指出：由于可选依赖较多，该命令在某些操作系统上可能失败；此时可以先自行安装偏好的深度学习框架（PyTorch、TensorFlow 和/或 Flax），然后退而求其次执行：

pip install -e ".[quality]"

这对大多数使用场景已足够。

开发过程中的质量保障命令

开发功能的同时，要确保测试套件通过。运行受你改动影响的测试：

pytest tests/<TEST_TO_RUN>.py

关于测试的细节见本文后面的"测试"一节。

代码格式化：Transformers 依赖 ruff 保持源代码风格一致。改动后，用一条命令同时应用自动风格修正与静态检查：

make style

从当前仓库的 Makefile 看，style 目标实际执行 python utils/checkers.py ruff_check, ruff_format, init_isort, sort_auto_mappings --fix，即一次性完成 ruff 检查修复、ruff 格式化、__init__ 导入排序和 auto 映射排序，且该任务优化为只处理被 PR 修改过的文件。

代码质量与仓库一致性检查：CI 会做这些检查，但你也可以本地执行：

make check-repo

查看 Makefile 可知，check-repo 运行全部检查器（代码质量 + 仓库一致性）并带 --keep-going 参数继续收集所有错误；仓库还额外提供 fix-repo 目标，会对有自动修复手段的检查项（尤其是 modular 转换）直接执行 --fix。检查项清单在 Makefile 中有明确定义：风格类包括 ruff_check、ruff_format、init_isort、sort_auto_mappings；仓库一致性类则涵盖 auto_mappings、imports、copies、dummies、docstrings、doctest_list 等二十余项，与 utils/checkers.py 及 utils/ 下各检查脚本一一对应。

文档构建验证：如果你修改了 docs/source 下的文件，必须确认文档仍可正常生成——这项检查在你开 PR 时也会在 CI 中运行。本地验证需先安装文档构建依赖：

pip install ".[docs]"

然后在仓库根目录执行：

doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build

构建产物会写入 ~/tmp/test-build，可以用任意编辑器检查生成的 Markdown；此外，打开 PR 后也可以在 GitHub 上直接预览文档效果。（仓库 docker/transformers-doc-builder/ 下也提供了文档构建的 Docker 配置。）

提交与推送：

git add modified_file.py
git commit

文档提醒要写好提交信息，清晰传达你的改动内容。为了保持本地代码与上游同步，应在打开 PR 之前（或被维护者要求时）将分支 rebase 到 upstream/main：

git fetch upstream
git rebase upstream/main

然后推送你的分支：

git push -u origin a-descriptive-name-for-my-changes

注意：如果 PR 已经创建，rebase 后必须用 --force 强制推送；如果 PR 尚未创建，则正常推送即可。

创建 PR 与应对评审意见： 到 GitHub 上的 fork 页面点击"Pull Request"，逐项核对下面的检查清单后提交。维护者要求修改是常态——即使是核心成员也是如此。应对方式是在本地分支继续开发并 push 到你的 fork，新提交会自动出现在 PR 中。

Pull Request 检查清单

文档给出了一份逐项核对的清单（原文为复选框形式，此处完整保留）：

• ☐ PR 标题应概括你的贡献；
• ☐ 如果 PR 对应某个具体 Issue，在 PR 描述中提及该 Issue 编号，建立关联（也让阅读 Issue 的人知道有人在处理）；
• ☐ 表示持续开发中的 PR，标题加 [WIP] 前缀——这能避免重复劳动，并与可合并的 PR 区分开；
• ☐ 确保现有测试通过；
• ☐ 如果添加了新功能，也要为它编写测试；
  • 如果添加的是新模型，确保使用 ModelTester.all_model_classes = (MyModel, MyModelWithLMHead, ...) 以触发通用测试套件；
  • 如果添加了新的 @slow 测试，用 RUN_SLOW=1 python -m pytest tests/models/my_new_model/test_my_new_model.py 确认其通过；
  • 如果添加了新 Tokenizer，编写测试并用 RUN_SLOW=1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py 确认其通过；
  • CircleCI 不运行慢测试，但 GitHub Actions 每晚都会运行；
• ☐ 所有 public 方法必须有信息充分的 Docstring（可参考 modeling_bert.py 的写法）；
• ☐ 由于仓库体积增长很快，不要添加图片、视频或其他显著增大仓库的非文本文件；应使用 Hub 仓库托管此类文件并通过 URL 引用。文档配图推荐放入 Hugging Face 官方的 documentation-images 数据集仓库，并可通过 PR 请求官方成员合并。

关于 PR 会触发的 CI 检查的完整说明，官方另有专门的《PR 检查指南》（pr_checks 文档页）。

测试体系：pytest、慢测试与环境变量

运行测试的标准姿势

仓库附带了大量测试，用于验证库本身的行为以及多个示例脚本。库测试位于 tests 目录，示例测试位于 examples 目录（例如 examples/pytorch 下的测试脚本）。

官方偏好 pytest 与 pytest-xdist（并行执行更快）。从仓库根目录指定子目录或测试文件路径来运行测试：

python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model

examples 目录同理，例如运行 PyTorch 文本分类子目录的测试：

pip install -r examples/xxx/requirements.txt  # 仅首次需要
python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

文档特别说明：这正是 make test 与 make test-examples 的实现方式（不含 pip install 部分）。查看当前仓库的 Makefile 可以看到，实际命令在此基础上额外加了 pytest-random-order 插件（-p random_order --random-order-bucket=module）用于随机化测试顺序，以暴露测试间的隐藏依赖。

也可以指定更少的测试用例，只测你正在开发的那个功能。

慢测试与其他环境变量

慢测试默认被跳过，但可以通过将环境变量 RUN_SLOW 设为 yes 来启用。这会触发数 GB 模型权重的下载，请确保磁盘空间充足、网络连接良好：

注意：务必指定子目录或测试文件路径，否则会运行 tests 或 examples 下的全部测试，耗时极长！

RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model
RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

除 RUN_SLOW 外还有其他默认不启用的环境变量，例如：

• RUN_CUSTOM_TOKENIZERS：启用自定义 Tokenizer 相关测试。

这些变量的定义集中在 src/transformers/testing_utils.py：其中 RUN_SLOW 与 RUN_CUSTOM_TOKENIZERS 都通过 parse_flag_from_env(..., default=False) 读取，即默认关闭，设为真值才启用。更多环境变量说明见该文件。

unittest 完全兼容

Transformers 把 pytest 仅当作测试运行器，测试套件本身不使用任何 pytest 专属特性。这意味着 unittest 被完整支持，也可以这样运行测试：

python -m unittest discover -s tests -t . -v
python -m unittest discover -s examples -t examples -v

风格指南：Docstring 遵循 Google 风格

在 Docstring 方面，Transformers 遵循 Google Python Style Guide。关于文档书写的更多规范（Markdown 与 Sphinx 指令的使用方式等），参见 docs 目录中的编写规范说明。这也与上文 make check-repo 中的 docstrings 检查项呼应——CI 会对公共方法的 Docstring 质量做自动校验。

Windows 开发环境配置

在 Windows 上（非 WSL 环境）贡献时，需要两步额外配置：

1. 让 git 将 Windows 的 CRLF 转换为 Linux 的 LF 行尾：

git config core.autocrlf input

2. 通过 MSYS2 使用 make 命令：

1. 下载并安装 MSYS2 到 C:\msys64；
2. 打开命令行 C:\msys64\msys2.exe（安装后通常可在开始菜单中找到）；
3. 在 shell 中执行 pacman -Syu 更新包管理器，然后 pacman -S make 安装 make；
4. 将 C:\msys64\usr\bin 加入 PATH 环境变量。

完成后即可在 PowerShell、cmd.exe 等任意终端中使用 make，从而复用本文前述的 make style、make check-repo、make test 等全部工作流命令。

同步 fork 仓库：避免误触上游通知

更新 fork 的 main 分支时，直接 ping 上游仓库会在依赖它的 PR 中留下无谓的引用并通知相关开发者。文档给出了两种做法：

1. 首选：尽量避免通过 fork 内的分支 + PR 来同步，而是直接合并到 fork 自己的 main 分支；
2. 如果必须走 PR，在 checkout 自己的分支后执行：

git checkout -b your-branch-for-syncing
git pull --squash --no-commit upstream main
git commit -m '<your message without GitHub references>'
git push --set-upstream origin your-branch-for-syncing

--squash --no-commit 会把上游 main 的改动压缩成单次待提交的变更，提交信息中不写 GitHub 引用，从而避免误触上游通知。

结语：一条可验证的贡献路径

纵观这份贡献文档，Transformers 为贡献者设计了闭环且可自检的流程：从用 transformers env 收集环境信息的规范 Issue，到 fork → 分支 → pip install -e ".[dev]" 可编辑安装的准备工作流；从 make style 一次完成 ruff 格式修复与 auto 映射排序，到 make check-repo 本地复现 CI 的二十余项仓库一致性检查；从 pytest -n auto --dist=loadfile 并行测试到 RUN_SLOW、RUN_CUSTOM_TOKENIZERS 等环境变量控制的测试分层，每个环节都能在仓库内找到对应的实现依据（utils/checkers.py、Makefile、src/transformers/testing_utils.py）。对希望参与该项目的开发者而言，按本文清单逐项核对，即可产出一份符合 CI 要求、可被顺利评审合并的 Pull Request。