CANN 社区 Pull Request 全流程操作指南：从环境准备到代码合入的贡献实战

CANN 社区 Pull Request 全流程操作指南从环境准备到代码合入的贡献实战【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community导读本文基于 CANN 社区管理仓库 contributor/pull_request_operation.md 编写系统讲解向 CANN 社区各开源项目提交 PRPull Request的完整操作链路——从开发环境准备、编码与版权规范、Fork 与本地分支管理到触发门禁、代码审查直至代码合入并结合 GitCode 工作流说明、代码仓门禁与版本集成流程指导 及仓库内规范文档进行源码级佐证。读完本文你将掌握一套可复制、可落地的 CANN 社区贡献流程能够独立完成一次高质量的代码合入。1. ️ 准备开发环境参与 CANN 社区项目贡献代码、文档等的第一步是准备对应的开发环境。CANN 社区下辖大量 SIG 组如 ops-basic、ops-nn、ascendc、hccl、ge 等不同项目使用的编程语言、框架和编译工具链各不相同环境配置要求也因此存在差异。请先查阅您感兴趣的开源项目中的README.md文件按其中的说明完成环境配置。例如算子类项目如 ops-basic、ops-nn、ops-transformer通常需要 CANN 工具链与对应平台的构建脚本可参考各 SIG 目录下的 README.md基础设施相关项目如 infrastructure则涉及流水线、机器人等配置可参考 SIG组织信息。在开始之前请确保本地已安装 Git并掌握基本的使用方法。2. 了解开发注意事项2.1 项目特定要求CANN 社区不同项目可能使用不同的编程语言、开发框架和编译环境请在贡献前仔细阅读对应项目的README.md了解具体的编码规范和开发要求。仓库内为开发者提供了统一的基础规范建议逐项阅读并遵照执行类别规范及要求设计安全设计指南编码C编程规范编码安全编码规范编码片段引用指导编译安全编译选项.md)文档文档写作规范这些规范是 PR 门禁检查的重要依据提前阅读可显著降低评审返工概率。其中几个关键点值得重点关注安全编码规范涵盖内存与指针安全、数值运算安全如有符号整数溢出、输入与数据验证、资源管理、并发与数据一致性等主题是 C 代码静态检查的主要依据安全编译选项.md)要求打开地址随机化ASLR、栈保护、GOT 表重定位只读、堆栈不可执行等编译选项PR 门禁会校验这些安全编译配置是否生效片段引用指导规范第三方开源代码片段的引入行为PR 合入时会自动触发开源代码片段引入检查SCA不鼓励但允许以声明合规的方式引入片段文档写作规范为项目文档规定了统一的内容要素概述、编译安装、本地验证、贡献指南、许可证与目录结构docs下区分zh/en文档类 PR 需遵循该规范。2.2 版权声明在参与项目贡献前请务必仔细阅读项目根目录下的LICENSE文件确保您的所有贡献符合该许可证的要求。版权声明要求请在所有新建的源代码文件如.cpp、.h、.py等头部添加规范的版权声明。对于 Apache 2.0、MIT 等常见开源协议建议从官方渠道获取标准的版权声明头并严格遵循该许可证官方文本的表述不要自行改写。对于 CANN Open Software License Agreement Version 2.0注意以下模板中的yyyy、[name of copyright owner]需要更改为首次创建年份和贡献者信息组织或个人。Copyright (c) yyyy [name of copyright owner]. This program is free software, you can redistribute it and/or modify it under the terms and conditions of CANN Open Software License Agreement Version 2.0 (the License). Please refer to the License for details. You may not use this file except in compliance with the License. THIS SOFTWARE IS PROVIDED ON AN AS IS BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. See LICENSE in the root of the software repository for the full text of the License.在 安全编码规范 中还给出了 C 文件头的对应声明示例含块注释形式新建源码文件时可参考/* * Copyright (c) 2025 Huawei Technologies Co., Ltd. * This file is a part of the CANN Open Software. * Licensed under CANN Open Software License Agreement Version 1.0 (the License). * Please refer to the License for details. You may not use this file except in compliance with the License. * THIS SOFTWARE IS PROVIDED ON AN AS IS BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. * See LICENSE in the root of the software repository for the full text of the License. */版权与 CLA 的关系CANN 社区通过机器人自动检查您 commits 中的邮箱是否已签署 CLA贡献者许可协议若已签署则自动添加cann-cla/yes标签否则添加cann-cla/no标签并留言提示。因此请务必使用与 CLA 签署邮箱一致的 Git 邮箱提交代码相关协议文本可在仓库 cla 目录下获取。3. 贡献提交流程CANN 社区的贡献提交流程整体如下图所示从 Fork 仓库开始依次经过本地验证、提交 PR、门禁检查、代码审查最终代码合入项目主线。3.1 Fork 仓库打开目标项目首页点击右上角的Fork按钮按照指引创建属于个人的云端 Fork 分支详见 GitCode 工作流说明 的 Fork 章节克隆个人仓库到本地环境# 创建本地工作目录 mkdir ${your_working_dir} cd ${your_working_dir} # 配置 Git 用户信息如已配置可跳过邮箱建议与 CLA 签署邮箱保持一致 git config --global user.name your_GitCode_Name git config --global user.email emailyour_GitCode_email # 克隆个人 Fork 仓库 git clone gitgitcode.com:${user_name}/${repository_name}.git # 设置上游仓库被 Fork 的原始仓库 git remote add upstream gitgitcode.com:cann/${repository_name}.git在本地分支进行代码、文档等修改。建议先同步上游最新代码再创建独立的功能分支git fetch upstream git checkout master git rebase upstream/master git checkout -b myfeature # myfeature 为个人开发分支名称提示若希望避免每次操作都输入账户密码可提前注册 SSH 公钥——使用ssh-keygen -t rsa -C emailyour_GitCode_email生成密钥将~/.ssh/id_rsa.pub内容添加到 GitCode个人设置 → 安全设置 → SSH 公钥中然后通过ssh -T gitgitcode.com验证连接。3.2 本地验证参考项目说明文档进行本地构建确保代码可编译通过依据 安全编译选项.md)、C编程规范 等规范自查代码质量如涉及文档修改遵循 文档写作规范若引入第三方代码片段按 片段引用指导 完成合规声明。3.3 提交 Pull Request代码验证通过后即可提交 PR 到目标项目。提交本地变更# 单人提交 git add . git commit -m 提交说明 # 若在前次提交基础上继续增量修改 git commit --amend将分支推送到 GitCode 上的 Fork 分支git push -f origin myfeature然后在 GitCode 进入目标项目的 Pull Requests 标签页点击新建 Pull Request确认源分支您的功能分支与目标分支通常为 master后创建 PR。提交 PR 后在评论中输入/compile即可触发门禁测试具体命令见 代码仓门禁与版本集成流程指导 与 GitCode 工作流说明。注意若涉及多人合作提交可在git commit时追加联合作者信息详见下方多人协作提交章节及 GitCode 工作流详细说明 5.2 章节。3.4 代码审查PR 提交后进入审查流程分为两种情况测试未通过根据门禁反馈修改代码修复后重新推送并在评论区触发门禁测试通过PR 将分配给 Committer 进行审查。您可以在 PR 评论区通过committer_gitcode_id提醒 Committer 进行审查然后及时关注审查意见并进行相应调整。3.5 代码合入PR 审查通过后代码将合入项目主线完成本次贡献。4. 门禁检查与版本集成CANN 社区通过持续集成CI及时发现代码问题确保代码质量可靠和功能稳定。据 代码仓门禁与版本集成流程指导主要包括两种集成场景代码门禁检查开发者提交代码合入申请后通过在评论中输入特定命令建议统一使用/compile触发门禁检查包括静态检查、病毒扫描、成分扫描、功能测试等门禁通过后方可合入代码主要关注增量代码的质量风险每日版本构建每日自动触发的流水线对整体代码进行安全扫描、病毒扫描、成分扫描和功能测试识别全量风险确保版本质量。门禁的各个环节由基础设施团队默认配置代码下载、编译构建、代码检查和测试用例等。若您所在的仓库需要新接入持续集成流程可在基础设施仓提交 Issue并提供代码编译指导如bash build.sh --pkg与 UT 运行指导如bash build.sh -u --ophost等配置信息。5. 保持分支同步与多人协作5.1 保持分支与 Master 同步在长期开发过程中建议定期将个人分支与上游 master 同步避免合入时出现大量冲突# 在 myfeature 分支上执行 git fetch upstream git rebase upstream/master重要建议不建议使用git pull代替fetch/rebase因为git pull会产生合并提交使提交历史变得混乱。可通过git config branch.autoSetupRebase always改变默认行为。5.2 多人协作提交多人合作时可通过追加联合作者信息Co-authored-by的方式在提交中记录所有贡献者以下为除自己外添加 2 个联合作者的示例git add . git commit -m 提交说明 -m Co-authored-by: zhangsan zhangsanexample.com -m Co-authored-by: lisi lisiexample.com6. 常用 Git 操作回退、冲突处理与提交整理6.1 回退提交如需回退某个提交请按以下步骤操作创建回退分支并同步git checkout -b myrevert git fetch upstream git rebase upstream/master执行回退操作# 回退合并提交SHA 为要回退的合并提交哈希值 git revert -m 1 SHA # 回退单个提交SHA 为要回退的单个提交哈希值 git revert SHA推送到远程回退分支git push ${your_remote_name} myrevert6.2 处理提交冲突如果 PR 显示冲突标记说明存在代码冲突需要解决切换到 master 分支并同步git checkout master git fetch upstream git rebase upstream/master切换回个人分支并变基git checkout yourbranch git rebase master解决冲突使用编辑器查看并解决所有冲突文件完成变基并推送git add . git rebase --continue git push -f origin yourbranch6.3 合并提交压缩提交历史如果多次提交后希望整理提交历史可以使用交互式变基压缩提交git log # 查看提交日志 git rebase -i HEAD~n # n 为要合并的提交数量在编辑界面中将需要压缩的提交前的pick改为squash或s保留至少一个pick随后保存ESC后输入:wq并编辑合并后的提交信息最后强制推送git push -f origin yourbranch完成后再到 GitCode PR 页面即可看到提交已合并。 扩展资源GitCode 工作流详细说明—— 完整的代码贡献流程指南含 SSH 配置、分支管理、回退、冲突处理等全部命令代码仓门禁与版本集成流程指导—— 门禁检查与每日版本构建的流水线机制说明CANN 社区组织管理—— 了解 SIG 组、maintainer、committer 的任免机制与 PR 标签cann-cla/yes、lgtm、approved的自动合入规则安全设计指南—— 模块设计阶段的安全要求身份认证、安全传输、敏感数据保护、加密算法等片段引用指导—— 第三方开源代码片段引入的合规整改指南文件头部声明 Third_Party_Open_Source_Software_Notice 声明。如您在贡献过程中遇到任何问题欢迎通过社区渠道ISSUE、邮件等寻求帮助。PR 是向项目分支的一次合入操作请谨慎操作以确保代码质量。【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考