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

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

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers

本篇技术指南基于 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 git@github.com:<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。

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers