English 中文

贡献指南

贡献指南#

前置准备#

  1. Fork 仓库到个人账号下，克隆到本地：

    git clone https://github.com/<你的用户名>/MindIE-SD.git

  2. 按 build_guide.md 完成源码编译。

  3. 安装 lint 依赖和 pre-commit hook：

    pip install -r requirements-lint.txt
pre-commit install

    pre-commit 详细说明见 dev_setup.md 的「Lint 与提交前检查」章节。

编码规范#

Ruff 配置#

Ruff 配置来自 pyproject.toml 的 [tool.ruff] 段：

配置项

值

说明

行长度

100

单行最大字符数

Python 版本

py310

目标版本

docstring 格式化

true

格式化 docstring 中的代码块

启用的 Lint 规则组：

规则组

含义

E

pycodestyle 错误（空白行、缩进等）

F

Pyflakes（未使用导入、未定义名称等）

I

isort 导入排序

N

pep8-naming 命名规范

W

pycodestyle 警告

UP

pyupgrade 语法现代化

B

flake8-bugbear 常见错误

C4

flake8-comprehensions 推导式优化

SIM

flake8-simplify 简化建议

G

flake8-logging-format 日志格式

Pre-commit 钩子#

pre-commit install 安装的钩子在每次 git commit 时自动运行：

钩子

行为

ruff-check

自动修复 Python lint 问题

ruff-format

自动格式化 Python 代码

pylint

Python 代码质量检查

bandit

Python 安全漏洞扫描

codespell

注释/文档拼写检查（跳过代码文件）

typos

代码标识符拼写检查

clang-format

C++ 代码格式化

markdownlint

Markdown 格式检查（手动模式）

trailing-whitespace

删除行尾空白字符

end-of-file-fixer

文件末尾添加换行符

check-yaml

YAML 格式检查

check-added-large-files

拦截大于 50MB 文件

check-merge-conflict

检测未解决的合并冲突

detect-private-key

检测硬编码密钥

Python 编码约定#

文件头模板：所有 .py 文件必须包含 Mulan PSL v2 许可证头。

导入顺序（Ruff I 规则强制执行）：

  1. 标准库（如 contextlib, dataclasses, typing）

  2. 第三方库（如 torch）

  3. 本地模块（如 from .compiliation_config import ...）

每组内部按字母序排列。

空白行：模块级函数/类定义前 2 个空白行，类内方法前 1 个空白行。

引号：统一使用双引号。

类型注解：目标 Python 3.10，可使用 X | Y 联合语法（PEP 604）。函数签名建议包含参数和返回值类型注解。

日志：使用标准 logging 模块，避免在日志字符串中使用 .format() 或 f-string，优先使用 % 风格参数：

logger = logging.getLogger(__name__)
logger.debug("...")
logger.warning("...")

C/C++#

使用 clang-format 做代码格式化，配置位于 .clang-format。

Markdown#

使用 markdownlint 做文档格式检查。手动运行方式见 dev_setup.md。

核心规则：

规则

说明

MD040

围栏代码块必须指定语言标记

MD009

禁止行尾空格

MD012

禁止连续多个空白行

MD031

围栏代码块前后需有空行

代码块语言选用：

内容类型

语言标记

Python 代码

python

Shell 命令

bash

目录/文件树

text

终端输出/日志

text

拼写与命名检查#

codespell + typos 对代码和文档做拼写检查。

提交前检查#

确保所有 pre-commit 检查通过后再提交：

pre-commit run --all-files

如需临时绕过（仅紧急情况）：

git commit --no-verify

运行测试#

CPU 友好单元测试#

bash tests/run_UT_test.sh

NPU 全量测试#

bash tests/run_test.sh --all

可选参数：--cpu_only、--npu_only。

测试详细说明见 test.md。

分支与提交规范#

  • 分支命名：feat/<功能名>、fix/<问题>、docs/<主题>、refactor/<范围>

  • 提交信息：首行简明（不超过 72 字符），可附带详细说明段落

Pull Request 流程#

  1. 从 main 创建新分支。

  2. 完成修改并确保 pre-commit + 测试通过。

  3. 提交 PR，关联 Issue（如有），描述变更内容与动机。

  4. Reviewer 给出技术评审意见。

  5. Approver 确认变更已具备合入条件。

  6. Branch keeper 或授权 maintainer 将变更合入受保护分支。

角色定义和决策流程详见 ../community/governance.md。

文档同步要求#

  • 用户可见的变更须同步更新 docs/zh/ 和 docs/en/ 下的对应文档。

  • 重要变更须更新 release_note.md 的版本说明。

  • 重大接口变更、行为变更应事先提交 RFC。

新手上路#

新手可从浏览仓库中所有开放的 Issue 开始，选择与自己能力匹配的任务。阅读 repo_structure.md 了解代码布局，有助于快速上手。

编码注意事项#

  • 避免重复代码，超过 5 行的重复片段应提取为公共函数。

  • 减少 NPU-CPU 同步操作（如 .item()、.cpu()），优先向量化。

  • 模型前向中的运行时检查应缓存为成员变量，避免每层重复计算。

  • 纯函数优先，避免对参数原地修改。

  • 单文件超过 2000 行时应拆分。

  • 工具类函数放在文件底部，核心数据结构放在顶部。

  • 禁止使用 pickle.loads() / pickle.load() 反序列化不可信数据。

  • 新增功能或适配新硬件时，尽量不改造现有代码，优先创建新文件引入独立模块。

  • 多分支判断时，确保默认路径/公共路径作为第一个分支。

目录