企业官网建设流程全解析

CANN HIXL 社区贡献指南：从 Issue 提交、Commit 规范到 PR 合入的完整协作流程

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl

本篇指南面向希望参与 CANN / HIXL 开源仓库（昇腾单边通信库，提供集群场景下简单、可靠、高效的点对点数据传输能力）贡献的开发者，系统讲解从贡献前置条件、Issue 方案讨论、Commit Message 规范、本地代码合规检查到提交 PR 的完整流程。读完本文，你将掌握 HIXL 仓库贡献的规范要求（含 commit 类型表、PR 模板要点）、四大贡献场景的操作路径，以及如何借助仓库内置的 pre-commit / OAT 能力在本地提前发现并修复合规问题，提升代码合入效率。

一、参与贡献的前置条件

在动手提交代码之前，HIXL 社区要求开发者先完成以下前置准备（详见仓库根目录的 CONTRIBUTING.md）：

1. 了解行为准则：参与社区前应先阅读 CANN 社区的行为准则，确保交流与协作方式符合社区预期；
2. 签署 CLA 协议：代码贡献前需完成 CLA 签署，这是开源合规的必要前提；
3. 了解源码仓贡献流程：包括如何提交 PR、gitcode 工作流、流水线触发命令、代码检视要求以及其他注意事项。

其中，「如何提交 PR（代码贡献流程：从 0 开始合入代码）」在仓库 Wiki 中有从零开始的完整说明，首次贡献者建议先通读一遍再进入实操。

说明：上述前置流程由 CANN 社区统一维护（cann-community 仓库），HIXL 作为 CANN 生态的一员沿用同一套规范，本文不再展开社区层面的操作细节，重点聚焦 HIXL 仓库自身的提交要求。

二、提交 PR 前的五项重点关注

在准备本地代码与提交 PR 时，HIXL 仓库明确要求开发者重点关注以下 5 点（对应 CONTRIBUTING.md）：

2.1 认真填写 PR 模板

提交 PR 时，请按照仓库内置的 PR 模板 仔细填写本次 PR 的业务背景、目的、方案等信息。该模板包含以下关键区块：

• 类型标签：勾选本次 PR 的类型（Bug 修复 / 新特性 / 代码重构 / 文档更新 / 其他并描述）；
• 描述：简要描述改动背景，包括改动原因、解决的问题等；
• 测试项：说明进行了哪些测试来验证本次改动，或新增了哪些测试用例；
• 测试结果：通过表格、图片等形式展示测试结果；
• Checklist：确认代码风格与项目一致、代码经过充分验证、相关文档已更新、标题正确使用类型标签（如 feat/bugfix/refactor/docs/test 等）；
• 其它（可选）：补充与本次 PR 相关的任何说明。

模板开头还会引导提交者先阅读贡献指南与 PR 提交方式，确保提交前已熟悉规范。

2.2 使用 pre-commit 工具保证提交合规

使用 git 进行代码提交前，建议参考仓库内的 pre-commit 工具使用说明 完成本地合规检查，使代码提交更合规高效。核心步骤如下：

# 1. 安装 pre-commit 框架（确保已安装 python 和 pip） pip install pre-commit pre-commit --version # 输出：pre-commit 3.x.x # 2. 进入项目目录后安装 Git Hooks pre-commit install # 3.（可选）验证 hook 是否生效（不会真正提交） git commit --allow-empty -m "test pre-commit"

安装后，git commit会自动触发代码格式化处理、单词拼写扫描及 OAT 检查；合规性问题会阻止提交并提示修改（阻止并非强制，可忽略修改继续提交）。

日志规范检查

pre-commit 还会对本次修改的 C/C++ 文件执行日志规范检查，覆盖日志宏的格式化参数数量、非法占位符、非英文字符或符号，以及向*_NOLOG宏传入无效日志参数等确定性问题。检查失败时会输出文件名和行号，修复后重新提交即可：

# 检查指定文件 python3 scripts/check_log_spec.py src/hixl/cs/endpoint.cc # 扫描 src 和 include 目录 python3 scripts/check_log_spec.py # 只执行 pre-commit 中的日志规范检查 pre-commit run log-spec-check --all-files

外部 API 失败日志的上下文完整性、日志级别和性能敏感路径的打印频率，仍需按照 docs_specification.md 进行人工检视。

GitCode 镜像仓库说明

由于国内网络环境访问 GitHub 可能受限，CANN 社区已将常用的 pre-commit hooks 仓库镜像到 GitCode（pre-commit-hooks、mirrors-clang-format、ruff-pre-commit、codespell、typos等均有对应镜像），国内开发时推荐使用 GitCode 镜像仓库，避免网络访问问题。

OAT 开源合规检查

OAT（Open Source Audit Tool）自动集成到 git 提交流程中，核心检查内容包括：

• 文件类型检查：禁止提交二进制文件（.so、.dll、.exe 等）；
• 许可证头检查：验证源代码文件包含合规的许可证声明。

其特点为：增量检查（仅检查待提交文件，速度快）、自动触发（每次git commit自动运行）、详细报告（自动生成oat_reports/single/result.txt摘要报告）、零配置（Linux/macOS 上 Java 与 Maven 可自动安装）、跨平台（Windows/Linux/macOS 全支持）。依赖软件版本要求如下：

环境问题自动跳过：如果无法安装 Java/Maven 或遇到环境问题，OAT 检查会自动跳过，提交仍会继续（如 Windows 无法自动安装 Java、自动安装失败、Maven 打包失败、OAT 扫描执行失败等场景均跳过检查并给出提示与手动安装指引）。但发现二进制文件、许可证头缺失/错误属于真正的合规性问题，会阻止提交。配置好环境后也可手动运行检查：

pre-commit run oat-check # 推荐方式 bash scripts/oat_check.sh # 或直接运行脚本

合规性问题的处理：当提交包含二进制文件（如lib/libtest.so）时，提交会被阻止并生成oat_reports/single/result.txt摘要，可执行git reset HEAD lib/libtest.so移除，或将二进制文件加入.gitignore后重新提交；当源文件缺少或许可证头格式不正确（如MISSING_LICENSE_HEADER）时，需要在文件顶部添加 CANN-2.0 许可证头后重新提交。

从源码实现看，scripts/oat_check.sh 为 Python 版（oat-py）实现，要求 Python 3.7+，具备 CRLF 自修复、flock串行化 pip 安装、按 PR 分支与暂存区两种模式做增量扫描、以 HEAD SHA 建立 done-marker 去重等能力；扫描命令会读取仓库根目录的 OAT.xml，其中声明了CANN-2.0许可证策略（license 类型，path 为.*）与Huawei Technologies Co., Ltd.版权策略，并对*.png、*.xml、*.yaml、*.csv、LICENSE等文件做了过滤豁免，与实际检查行为完全对应。

2.3 非简单 Bug 修复先走 Issue 方案讨论

若修改不是简单的 bug 修复，而是涉及新增特性、新增接口、新增配置参数或修改代码流程等，请务必先通过 Issue 进行方案讨论，以避免代码被拒绝合入。若不确定修改是否可归为「简单的 bug 修复」，同样建议提交 Issue 进行方案讨论。

仓库在 .gitcode/ISSUE_TEMPLATE 提供了多套 Issue 模板，便于按场景规范化描述：

• bug-report.yml：缺陷反馈模板，要求提供问题描述、环境信息、重现步骤、预期结果、日志/截图等，并引导先搜索现有/历史 issues 与常见问题定位手册；
• feature-request.yml：需求反馈模板，要求说明背景信息、需求来源、价值/作用与设计方案（可使用伪代码）；
• documentation.yml：文档反馈模板，要求给出文档链接、问题文档片段及存在的问题描述；
• question.yml 与 request-for-comments.yml：分别用于提问与 RFC 方案评审。

2.4 遵守项目代码规范

提交 PR 时，请确保代码符合项目的代码规范，具体参考 Google 开源代码规范，覆盖（但不限于）：

• 代码格式化
• 注释规范
• 变量命名规范
• 函数命名规范
• 类命名规范
• 接口命名规范
• 配置参数命名规范
• 代码流程规范

HIXL 仓库在 docs/zh/contributions/coding_standards 下维护了针对本项目的中文细化规范文档，包括cpp-abi.md（ABI 兼容）、cpp-general.md（C++ 通用规范）、cpp-param-validation.md（参数校验）、cpp-secure.md（安全）、cpp-style.md（代码风格）、docs_specification.md（文档规范）与python-secure.md（Python 安全），提交前建议结合这些文档自查。

2.5 提交前 rebase 合并 commit

提交 PR 时若存在多个无效 commit，建议提交前先执行git rebase操作，将多个 commit 合并为一个，保持代码的简洁性和可读性。同时，commit message 需要符合项目规范，能够清晰描述变更意图与内容，格式为：<类型>: <简短描述>。

三、Commit Message 类型规范

HIXL 仓库要求 commit message 使用<类型>: <简短描述>的统一格式，支持的类型及示例如下（与 CONTRIBUTING.md 完全一致）：

从仓库源码结构看，该规范与 PR 模板 Checklist 中「标题中正确使用了类型标签（feat/bugfix/refactor/docs/test 等）」的要求相互呼应，共同保证提交信息的可检索性与可读性。

四、四大贡献场景与操作路径

开发者贡献场景主要包括 Bug 修复、贡献新功能、文档纠错与帮助解决他人 Issue 四类，每类场景的标准化操作路径如下。

4.1 Bug 修复

若在本项目中发现了某些 Bug 并希望修复，欢迎新建 Issue 进行反馈和跟踪处理。操作路径：

1. 按指引新建Bug-Report|缺陷反馈类 Issue（见 bug-report.yml），描述 Bug 现象、环境与复现步骤；
2. 在评论框中输入/assign或/assign @yourself，将该 Issue 分配给自己处理；
3. 完成修复后提交 PR，并在 PR 中关联对应 Issue。

4.2 贡献新功能

若发现功能缺失并希望新增，欢迎新建 Issue 进行反馈和跟踪处理。操作路径：

1. 按指引新建Requirement|需求建议类 Issue（见 feature-request.yml），说明新增功能的背景、来源、价值与设计方案；
2. 在评论框中输入/assign或/assign @yourself，将该 Issue 分配给自己跟踪实现；
3. 结合 2.3 节，功能类改动务必先完成方案讨论再进入编码与提 PR 阶段。

4.3 文档纠错

若发现文档描述错误，欢迎新建 Issue 进行反馈和修复。操作路径：

1. 按指引新建Documentation|文档反馈类 Issue（见 documentation.yml），指出对应文档链接、问题片段及存在的问题；
2. 在评论框中输入/assign或/assign @yourself，将该 Issue 分配给自己纠正对应文档描述。

4.4 帮助解决他人 Issue

若社区中他人遇到的问题你恰好有解决方案，欢迎在 Issue 中发表评论交流，帮助他人解决问题和痛点，共同优化易用性。若对应 Issue 需要代码修改，可以在 Issue 评论框中输入/assign或/assign @yourself，将该 Issue 分配给自己，跟踪协助解决。

五、从流水线到合入：PR 触发与检视机制

提交 PR 后，CI 流水线会自动执行一系列检查（对应 .gitcode/workflows/hixl_action.yml，PR 评论中以/compile等关键词触发）：

1. PreBuild 阶段：准备测试镜像，并执行 PreBuild 前置检查；
2. Compile 阶段：执行 CodeCheck 静态检查、x86/ARM 双架构编译（含 Ubuntu 24 变体）以及 Markdown 静态检查（staticcheck_action.yml的md_check），产出cann-hixl_linux-x86_64.run、cann-hixl_linux-aarch64.run等安装包；
3. UT 阶段：执行 API 一致性检查（api-check）与 C++/Python 单元测试（ut_action.yml），产出覆盖率文件；
4. PreSmoke 阶段（目标分支为 master 时）：在 A2/A3 真实昇腾环境上运行预冒烟测试（见 scripts/pre_smoke.sh），失败日志以slog*.tar.gz形式归档。

因此，本地提前跑通 pre-commit / OAT / 单测（仓库测试位于 tests 目录），可以显著减少流水线返工次数。整个过程中，请随时回到 CONTRIBUTING.md 对照检查：PR 模板是否填写完整、commit message 是否符合<类型>: <简短描述>格式、是否已先通过 Issue 完成方案讨论、本地代码是否通过 pre-commit 与 OAT 合规检查——满足这些条件后，你的贡献将更高效地进入代码检视与合入环节。

六、小结

HIXL 仓库的贡献流程可以浓缩为一条主线：签 CLA 与熟悉社区流程 → 复杂改动先建 Issue 讨论方案 → 本地用 pre-commit 完成格式化、日志规范与 OAT 合规检查 → 按<类型>: <简短描述>规范提交 commit（必要时 rebase 合并）→ 按 PR 模板 填写背景、方案、测试结果 → 触发 CI 流水线完成编译、静态检查、单测与冒烟 → 通过代码检视后合入。无论是修复 Bug、贡献新功能、文档纠错还是帮助他人解决 Issue，遵循这一流程都能让你的贡献更顺畅、更合规。

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl