如何给 transcribe.cpp 提 PR：CONTRIBUTING 规范与 CI 门禁完整清单-平芜编程栈

如何给 transcribe.cpp 提 PR：CONTRIBUTING 规范与 CI 门禁完整清单

【免费下载链接】transcribe.cppggml speech-to-text inference for 16+ model families项目地址: https://gitcode.com/GitHub_Trending/tr/transcribe.cpp

transcribe.cpp是基于 ggml 的 C/C++ 语音转写（speech-to-text）推理库，支持 16+ 模型家族、60+ 模型变体。想给这个项目提 PR？先读懂 CONTRIBUTING.md 和.github/workflows/下的 CI 门禁，你的 PR 才能一次过审。本文整理了提 PR 前的规范要点与 CI 检查清单。

一、开工前：3 分钟读懂项目规范

克隆仓库后，按顺序读这 3 份文件：

CONTRIBUTING.md —— 贡献规范、代码风格、审查门禁（本文核心依据）
docs/porting/0-porting.md —— 移植新模型家族的 8 阶段工作流：1-intake → 2-oracle → 3-convert → 4-cpp → 5-quants → 6-bench → 7-wer → 8-ship
.github/pull_request_template.md —— PR 模板的 4 个必填栏目

项目定位偏保守：它是一个库 + 运行时 + 打包产物，被用户嵌入到更大的进程中，所以改动必须"易审查、跨平台可移植、合并后可持续维护"。

💡 想移植新模型？规范明确要求先开 issue，写清上游模型仓库、family key、变体名和架构模式（encoder-transducer / encoder-decoder / audio-LLM / encoder-CTC），再按阶段顺序推进，不要跳过 intake 和 golden manifest 直接写 C++。

二、AI 辅助贡献：披露是硬性要求

可以用 AI 辅助写代码，但有两条红线：

必须在 PR 中披露AI 的使用，且人类作者要理解并拥有这部分改动；
禁止用 AI 写 PR 描述、issue、commit message 或回复 reviewer —— "一眼 AI 味"的 PR 描述几乎必被拒。

三、代码风格与格式门禁：动手前先跑一遍格式检查

CI 会用固定版本的 clang-format（脚本里 pin 住，本地输出与 CI 逐字节一致）检查你改动的 C/C++，用系统里的 clang-format 大概率过不了：

scripts/ci/clang-format.sh # 就地格式化 scripts/ci/clang-format.sh --check # 只检查不修改

几条高频踩坑点：

规范	要求
缩进/花括号	4 空格缩进，花括号与声明同行
命名	函数/变量用`snake_case`，公共符号带`transcribe_`前缀
注释	简短、只用 ASCII，解释 ABI 约定和数值选择，不写任务历史
重构	行为改动与批量重排代码必须分开提交
依赖	不加第三方依赖、新文件、新头文件，除非有充分理由

注意：ggml/、src/third_party/等 vendored 目录永远不要动格式。完整风格细则见 CONTRIBUTING.md 的 Coding style 一节，源头参考是 src/transcribe.cpp 与 CMakeLists.txt 周围的现有写法。

四、PR 门禁清单：合并前必须全绿

CONTRIBUTING.md 的 Review gates 一列出了合并前必过的 7 道门禁，本地命令直接照抄：

门禁	命令 / 责任人	通过标准
格式检查	`scripts/ci/clang-format.sh --check`	全部 C/C++ 匹配固定格式
Intake 签核	人工 review	intake schema 合法，reference_framework / architecture_pattern / known_risks 已审
Preflight A	`uv run scripts/preflight.py --family <f> --gate A`	通过，或警告对应已接受的 intake 缺口
Preflight B	`uv run scripts/preflight.py --family <f> --gate B`	转换器存在后通过
数值验证	`uv run scripts/validate.py all --family <f>`	容差文件内张量全部达标，转写与参考一致
默认测试	`ctest --test-dir build`	全部启用的默认测试通过
真实模型冒烟	`ctest --test-dir build -R <family>`（开启`TRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON`）	代表性精度 GGUF 上通过

另外两类内容严禁提交：GGUF 模型二进制、build/validate/下的重型张量 dump、每次运行的 preflight 输出、HF 凭证。候选 GGUF 只能作为 review 附件，附上 URL/路径、SHA256、源模型 revision 和转换命令。

五、CI 流水线里到底在查什么

每个 PR 会按改动路径触发对应工作流（定义在 .github/workflows/）：

clang-format 门禁（clang-format.yml）：固定版本 clang-format 全量检查，最常被 PR 卡住的一道。
native 库门禁（native-ci.yml）：改动src/、include/、tests/、ggml/、构建文件时触发，包含 4 条 lane：
- cpp-tests：Linux + macOS(arm64) 全量 C++ 白盒测试，cmake --install后用外部 C 消费者做链接冒烟；
- cpp-tests-sanitized：ASan+UBSan 跑同一套测试，验证 C 生命周期/ABI 契约；
- provider-dl-vulkan：验证无 Vulkan 加载器时静默降级到 CPU 的行为；
- posture-lint：校验 wheel preset 与 pyproject lane 的一致性镜像。
Python 绑定门禁（python-bindings.yml）：FFI 生成漂移检查 + Python 测试套件。
模型 catalog 门禁（catalog.yml）：改动 catalog/、scripts/hf_cards/、docs/models/ 或 README 时，强制校验模型元数据一致性。