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

CANN HIXL 社区贡献指南从 Issue 提交、Commit 规范到 PR 合入的完整协作流程【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本篇指南面向希望参与 CANN / HIXL 开源仓库昇腾单边通信库提供集群场景下简单、可靠、高效的点对点数据传输能力贡献的开发者系统讲解从贡献前置条件、Issue 方案讨论、Commit Message 规范、本地代码合规检查到提交 PR 的完整流程。读完本文你将掌握 HIXL 仓库贡献的规范要求含 commit 类型表、PR 模板要点、四大贡献场景的操作路径以及如何借助仓库内置的 pre-commit / OAT 能力在本地提前发现并修复合规问题提升代码合入效率。一、参与贡献的前置条件在动手提交代码之前HIXL 社区要求开发者先完成以下前置准备详见仓库根目录的 CONTRIBUTING.md了解行为准则参与社区前应先阅读 CANN 社区的行为准则确保交流与协作方式符合社区预期签署 CLA 协议代码贡献前需完成 CLA 签署这是开源合规的必要前提了解源码仓贡献流程包括如何提交 PR、gitcode 工作流、流水线触发命令、代码检视要求以及其他注意事项。其中「如何提交 PR代码贡献流程从 0 开始合入代码」在仓库 Wiki 中有从零开始的完整说明首次贡献者建议先通读一遍再进入实操。说明上述前置流程由 CANN 社区统一维护cann-community 仓库HIXL 作为 CANN 生态的一员沿用同一套规范本文不再展开社区层面的操作细节重点聚焦 HIXL 仓库自身的提交要求。二、提交 PR 前的五项重点关注在准备本地代码与提交 PR 时HIXL 仓库明确要求开发者重点关注以下 5 点对应 CONTRIBUTING.md2.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 仓库镜像到 GitCodepre-commit-hooks、mirrors-clang-format、ruff-pre-commit、codespell、typos等均有对应镜像国内开发时推荐使用 GitCode 镜像仓库避免网络访问问题。OAT 开源合规检查OATOpen Source Audit Tool自动集成到 git 提交流程中核心检查内容包括文件类型检查禁止提交二进制文件.so、.dll、.exe 等许可证头检查验证源代码文件包含合规的许可证声明。其特点为增量检查仅检查待提交文件速度快、自动触发每次git commit自动运行、详细报告自动生成oat_reports/single/result.txt摘要报告、零配置Linux/macOS 上 Java 与 Maven 可自动安装、跨平台Windows/Linux/macOS 全支持。依赖软件版本要求如下软件版本要求用途安装方式JavaJRE 8运行 OAT自动安装Linux/macOS手动安装WindowsMaven3.5打包 OAT自动安装Linux/macOS手动安装WindowsGit2.0版本控制通常已安装pre-commit2.0Hook 框架pip install pre-commit环境问题自动跳过如果无法安装 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.mdABI 兼容、cpp-general.mdC 通用规范、cpp-param-validation.md参数校验、cpp-secure.md安全、cpp-style.md代码风格、docs_specification.md文档规范与python-secure.mdPython 安全提交前建议结合这些文档自查。2.5 提交前 rebase 合并 commit提交 PR 时若存在多个无效 commit建议提交前先执行git rebase操作将多个 commit 合并为一个保持代码的简洁性和可读性。同时commit message 需要符合项目规范能够清晰描述变更意图与内容格式为类型: 简短描述。三、Commit Message 类型规范HIXL 仓库要求 commit message 使用类型: 简短描述的统一格式支持的类型及示例如下与 CONTRIBUTING.md 完全一致类型说明示例feat新功能[feat]: 添加用户注册功能bugfix修复 bug[bugfix]: 修复登录态过期问题docs文档更新[docs]: 更新 API 使用说明style代码格式调整不影响逻辑[style]: 调整代码缩进refactor重构非功能新增/修复[refactor]: 优化用户服务类结构perf性能优化[perf]: 减少数据库查询次数test测试相关[test]: 添加登录功能单元测试chore构建/工具链变更[chore]: 更新 webpack 配置ciCI 配置相关[ci]: 添加自动化测试流程从仓库源码结构看该规范与 PR 模板 Checklist 中「标题中正确使用了类型标签feat/bugfix/refactor/docs/test 等」的要求相互呼应共同保证提交信息的可检索性与可读性。四、四大贡献场景与操作路径开发者贡献场景主要包括 Bug 修复、贡献新功能、文档纠错与帮助解决他人 Issue 四类每类场景的标准化操作路径如下。4.1 Bug 修复若在本项目中发现了某些 Bug 并希望修复欢迎新建 Issue 进行反馈和跟踪处理。操作路径按指引新建Bug-Report|缺陷反馈类 Issue见 bug-report.yml描述 Bug 现象、环境与复现步骤在评论框中输入/assign或/assign yourself将该 Issue 分配给自己处理完成修复后提交 PR并在 PR 中关联对应 Issue。4.2 贡献新功能若发现功能缺失并希望新增欢迎新建 Issue 进行反馈和跟踪处理。操作路径按指引新建Requirement|需求建议类 Issue见 feature-request.yml说明新增功能的背景、来源、价值与设计方案在评论框中输入/assign或/assign yourself将该 Issue 分配给自己跟踪实现结合 2.3 节功能类改动务必先完成方案讨论再进入编码与提 PR 阶段。4.3 文档纠错若发现文档描述错误欢迎新建 Issue 进行反馈和修复。操作路径按指引新建Documentation|文档反馈类 Issue见 documentation.yml指出对应文档链接、问题片段及存在的问题在评论框中输入/assign或/assign yourself将该 Issue 分配给自己纠正对应文档描述。4.4 帮助解决他人 Issue若社区中他人遇到的问题你恰好有解决方案欢迎在 Issue 中发表评论交流帮助他人解决问题和痛点共同优化易用性。若对应 Issue 需要代码修改可以在 Issue 评论框中输入/assign或/assign yourself将该 Issue 分配给自己跟踪协助解决。五、从流水线到合入PR 触发与检视机制提交 PR 后CI 流水线会自动执行一系列检查对应 .gitcode/workflows/hixl_action.ymlPR 评论中以/compile等关键词触发PreBuild 阶段准备测试镜像并执行 PreBuild 前置检查Compile 阶段执行 CodeCheck 静态检查、x86/ARM 双架构编译含 Ubuntu 24 变体以及 Markdown 静态检查staticcheck_action.yml的md_check产出cann-hixl_linux-x86_64.run、cann-hixl_linux-aarch64.run等安装包UT 阶段执行 API 一致性检查api-check与 C/Python 单元测试ut_action.yml产出覆盖率文件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遵循这一流程都能让你的贡献更顺畅、更合规。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考