English | 简体中文
HyperParallel 欢迎问题反馈、文档改进、测试、模型接入、性能优化和新并行能力贡献。无需上游仓库写权限,即可通过 Fork 参与开发。 请使用公开 Issue 和 Pull Request 记录方案、评审决定和验证结果,便于社区共同维护。
- 反馈问题:先搜索已有 Issue,再使用问题模板提交。
- 改进文档或测试:小范围修正可以直接提交聚焦的 PR。英文文档与同目录的
.zh.md中文版本同步更新。 - 提出新功能或框架接入:较大实现开始前,先提交 Feature Issue 或 RFC,说明使用场景、接口、兼容性影响、硬件范围和验收标准,并请相关模块维护者评审方案。
- 优化性能:说明工作负载和瓶颈,在相同模型、硬件、精度、并行配置及测量方法下,提供可复现的正确性与性能对比。
不确定修改归属时,可在 Issue 中描述需求,并参考 CODEOWNERS 联系模块维护者。 请保持尊重、回应技术意见,并将决定记录在 Issue 或 PR 中。
先在 GitHub 上 Fork HyperParallel,替换以下命令中的 YOUR_GITHUB_USERNAME,从目标上游分支创建开发分支。
普通开发面向 master;版本修复应先与发布维护者确认目标版本分支。
git clone https://github.com/YOUR_GITHUB_USERNAME/hyper-parallel.git
cd hyper-parallel
git remote add upstream https://github.com/mindspore-ai/hyper-parallel.git
git fetch upstream
git switch -c feat/your-change upstream/master使用自己习惯的工具(如 venv 或 Conda)创建并激活独立 Python 环境,Python 版本需符合安装指南要求,环境名称自行选择。
按照安装指南准备支持的 PyTorch 与硬件运行时组合,再在该环境中执行以下命令,以 editable 模式安装当前代码:
python -m pip install -e .
python -m pip install pytest
python -c "import hyper_parallel; print(hyper_parallel.__file__)"输出路径必须指向当前代码目录。若指向其他工作区或旧安装,请在目标仓库重新安装。 原生组件还需按照安装指南执行构建及环境激活,单独的 Python editable 安装不会构建这些组件。
依赖详情见开发环境,身份认证与账号配置见 GitHub 协作手册。 涉及 RL 的工作从 RL 入口规则开始,并完成其独立运行时配置。
修改前阅读 AGENTS.md 和编程规范。具体要求及例外以编程规范为准。
- Python 文件添加 Apache 2.0 头,遵循 PEP 8,行宽约 120 字符,公开 API 提供类型标注和 Google 风格文档字符串。C++ 遵循仓库
.clang-format及 C++ 规范。 - 默认在模块顶部导入,直接使用原生 PyTorch API。涉及分片、通信、流或内存管理时,遵循分布式实现规则。
- 保持修改聚焦。行为、公开接口、依赖和检查点兼容性变化需要配套测试与文档。
- 默认文档使用英文,同步修改对应
.zh.md。检查相对链接、锚点、示例命令和 API 签名。 - 修复 lint 和测试失败的根因;必要例外及未验证配置应在 PR 中说明。
在已激活的环境中安装本地提交钩子并执行检查:
bash scripts/pre-commit/install.sh
python .agent/skills/autogit/scripts/autogit.py check
python .agent/scripts/check_agents_catalog.py
git diff --check检查会根据文件类型选择 pylint、lizard、C++/Shell 检查器、codespell、markdownlint 等工具。
修改 Markdown 必须运行目录检查;该检查只校验技能与代理目录,因此文档链接需单独检查。
安装方式与工具覆盖见 pre-commit 指南。
autogit check 会临时暂存修改以识别检查范围,建议在只包含本次任务修改的工作区运行。
AutoGit 的远程 PR 流程面向 GitCode;提交 GitHub PR 时使用 Git 和 GitHub 工具。
根据变化的行为选择测试。目录、标记和启动方式见测试规则与测试指南。
| 修改类型 | 所需验证证据 |
|---|---|
| 纯文档 | Markdown lint、目录检查、修改的链接和锚点,以及适用的命令或示例验证。说明运行时测试不适用的原因。 |
| 可独立测试的逻辑 | tests/ut/ 中受影响的单元测试,问题修复应包含回归用例。 |
| 分片、集合通信、并行组合或检查点恢复 | 在受影响硬件上执行相关分布式 ST,并按场景验证数值与状态恢复。 |
| 性能或内存优化 | 正确性检查,以及相同配置下修改前后的对比;按场景记录吞吐、单步时间、峰值内存及测量条件。 |
| 安装包或依赖修改 | 在声明支持的组合上验证构建、干净环境安装、导入和相关示例。 |
例如执行受影响的 shard 单元测试;影响范围需要时再运行全量单元测试:
python -m pytest -vs tests/ut/core/shard/
python -m pytest -vs tests/ut/单元测试不能初始化分布式任务。分布式 ST 使用测试规则中指定的仓库启动器,遵循选定用例的设备要求,不要统一再套一层 torchrun。
RL ST 独立于主项目 PR 门禁运行,主项目 CI 通过不代表 RL ST 已完成验收。
在 PR 中记录被测提交、命令、模型与配置、Python 和 PyTorch 版本、设备型号与数量及结果。
Ascend 还需记录 torch-npu、CANN 和驱动版本;NVIDIA GPU 需记录 CUDA 和驱动版本。
明确列出缺少的硬件与未运行用例,并与维护者协调必要的硬件验证。跳过测试或仅成功解析配置不能记为硬件验证通过。
- 每个 PR 聚焦一个可独立评审的修改。使用 Conventional Commit,例如
docs: clarify installation,英文主题使用祈使句,长度约 80 字符。 - 每个 PR 保持一个提交。提交 PR 前压缩开发过程中的临时提交,后续修复 amend 到同一提交。改写历史前先备份;仅更新自己的 PR 源分支,并使用带预期远端 SHA 的
--force-with-lease。禁止强推共享主分支或版本分支。 - 推送至个人 Fork,并向正确的上游分支发起 PR。使用仓库默认模板或中文模板,说明问题、修改后行为、范围、兼容性影响与实际测试结果。关联真实 Issue;没有适用 Issue 时明确说明,如实填写自检项。
- 设计、实现或必要证据尚未完成时使用 Draft PR。准备好后,向 CODEOWNERS 中相关维护者请求评审。
- 回应评审意见,同步更新测试与中英文文档,并为最新提交取得有效 CI 和评审结果。相关问题得到处理后再解决评审讨论。
对于与 GitCode 配对的 PR,更新约定的源分支,由同步服务处理对应请求,避免在两端产生竞争修改。 遵循目标分支的实时仓库规则以及适用的身份与 CLA 检查。
Jenkins 执行项目流水线并向 PR 回报测试及构建结果。GitHub 工作流检查 CI 标签有效期和评审票数。
当前 master 门禁包括:
| 门禁 | 贡献者需要了解的要求 |
|---|---|
label-check |
CI 通过标签必须有效。ci-pipeline-passed 和 ci-pipeline-passed-but-overtime 在添加后 24 小时过期;新增提交需要新的 CI 结果。超时标签保留耗时异常信息。 |
all-reviewers-approved |
一名评审人时需一次批准;两名及以上评审人时需两名不同评审人批准。批准必须针对当前提交,作者本人不计入。未解决的修改请求或待处理团队评审仍会阻断。 |
| 原生分支规则 | 最新推送需要独立批准,推送后旧批准失效,评审讨论需解决。其他要求以目标分支实时规则为准。 |
详细策略见评审与合入规则。通过某一门禁不能替代其他门禁,维护者根据有效分支规则判断合入条件。
验证失败时先查看失败阶段与日志。代码回归由作者在模块维护者协助下修复,执行资源、环境和结果回报问题由 CI 维护者处理。 修复根因后,通过仓库支持的入口申请重测,确认结果对应当前提交。不要手工添加通过标签或关闭检查来促成合入。
社区计划约每月一个 Beta、每季度一个 Stable。Beta 用于提前试用和收集下游反馈,Stable 提供通过验收的部署基线。 实际时间与范围取决于候选版本验证和维护者评审。SemVer、打包、发布说明、文档、已知限制及升级指引见发布流程。
2026 年 Q4 CI/CD 计划将验证范围扩展到 Ascend NPU 与 NVIDIA GPU 上的 PyTorch 2.9 至最新稳定版本,并跟进最新两个 PyTorch 版本。
这是路线图目标,实际支持组合以已发布验证结果为准。运行时尚未适配的组合标记为待验证,并关联跟踪 Issue。
即使随 Stable 发布,标为 DEMO 的能力仍受其声明的限制约束。
下游以可选安装包依赖方式使用 HyperParallel,各项目独立发布。 接入 PR 应提供安装方式、用户配置、可运行示例、兼容边界及可复现的正确性与性能结果,并与适配代码同步更新下游使用指南。
计划中的 VeOmni 流水线每周更新固定的上游版本基线,在 HyperParallel 修改合入前执行验证。 新基线通过后再切换;失败则保留上一个通过组合并跟踪问题。必要接入用例需记录两个项目的提交及精确环境。 VeOmni 首版接入面向 Ascend,GPU 后续支持。这些计划中的检查在接入中启用后成为合入要求,未有运行证据前不能描述为已经执行。
可复现缺陷或跨 PR 问题通过公开 Issue提交,PR 特定问题保留在该 PR 中。 提供预期与实际行为、版本、设备、配置、最小复现和脱敏日志。数值或性能问题补充比较方法与基线,附件中移除凭据和私有训练数据。
模块维护者评审方案与实现,PR 作者处理其引入的回归,CI 维护者处理基础设施问题。 在原 Issue 中记录根因、受影响与修复版本以及回归结果。
对于拟接入的 VeOmni,HyperParallel 负责安装包、适配代码、VeOmni 仓内使用指南、Ascend 测试资源及每周兼容验证。 VeOmni 维护者保留其仓内评审、合入与发布决定权。
贡献遵循仓库的 Apache 2.0 许可证。引入第三方代码时,保留必要署名与许可信息,并按需更新第三方软件声明。