公开 dbhoo-lpu开源版 v1.0.1 更新于 2026-07-21

贡献指南

版本: dbhoo-lpu v1.0.1 (Open Source)
最后更新: 2026-07-20

目录

1. 欢迎贡献

感谢你对 dbhoo-lpu 开源版的关注！我们欢迎各种形式的贡献，包括但不限于：

  • 🐛 报告 Bug
  • 💡 提出新功能建议
  • 📝 改进文档
  • 🔧 修复 Bug
  • ✨ 新增功能
  • 🧪 添加测试
  • 🚀 性能优化

无论你是新手还是资深开发者，都可以找到适合的贡献方式。

2. 如何贡献

2.1 贡献方式总览

贡献类型方式
Bug 报告提交 Issue
功能建议提交 Issue，标记为 enhancement
代码贡献Fork + Pull Request
文档改进Fork + Pull Request
问题讨论Issue 评论 / 社区讨论

2.2 从哪里开始

如果你是第一次贡献，可以从以下方面入手：

  • 好的入门问题: 查看带有 good first issue 标签的 Issue
  • 文档改进: 修复错别字、补充说明、完善示例
  • 测试补充: 为现有功能添加更多测试用例
  • 小 Bug 修复: 简单的 Bug 修复

3. 提 Issue 流程

3.1 提交前检查

在提交新 Issue 之前，请检查：

  1. 🔍 搜索现有 Issue，确认是否已有相同或类似的问题
  2. 📚 查看文档和 FAQ，确认不是已知问题
  3. 🔧 确认使用的是最新版本

3.2 Bug 报告模板

请使用以下格式提交 Bug 报告（越详细越好）：

**Bug 描述**
清晰简洁地描述 Bug 是什么。

**复现步骤**
1. 环境: (操作系统 / 编译器版本 / LPU 版本)
2. 最小复现代码:

c
// 贴出可以复现问题的最小代码

3. 运行命令:

bash

编译和运行命令

**预期行为**
描述你期望发生什么。

**实际行为**
描述实际发生了什么。

**错误信息/堆栈**
如果有报错，请贴出完整的错误信息。

**附加信息**
任何其他相关信息（截图、日志等）。

3.3 功能建议模板

**功能描述**
清晰简洁地描述你想要的功能。

**背景和动机**
为什么需要这个功能？它解决了什么问题？

**建议的实现方式**
（可选）你有什么实现思路？

**替代方案**
（可选）你考虑过哪些替代方案？

**附加信息**
任何其他相关信息。

4. 提交 PR 流程

4.1 开发工作流

我们使用标准的 GitHub Fork & Pull Request 工作流：

1. Fork 仓库到你的 GitHub 账号
2. 克隆你的 Fork 到本地
3. 创建新的功能分支
4. 在分支上进行开发
5. 提交更改，写好 commit message
6. 推送到你的 Fork
7. 在 GitHub 上提交 Pull Request

4.2 详细步骤

第一步：Fork 仓库

访问 dbhoo-lpu 仓库页面，点击右上角的 “Fork” 按钮。

第二步：克隆你的 Fork

git clone https://github.com/your-username/lpu-oss.git
cd lpu-oss
git remote add upstream https://github.com/original-org/lpu-oss.git

第三步：创建功能分支

git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

分支命名建议：

  • 新功能: feature/xxx
  • Bug 修复: fix/xxx
  • 文档: docs/xxx
  • 性能优化: perf/xxx
  • 重构: refactor/xxx

第四步：开发和提交

# 进行代码修改...

# 运行测试确保通过
mkdir build && cd build
cmake ..
make -j$(nproc)
./lpu_unit_tests

# 提交更改
git add .
git commit -m "简短描述你的更改"

第五步：推送并提交 PR

git push origin feature/your-feature-name

然后在 GitHub 上点击 “Compare & pull request” 按钮。

4.3 PR 描述模板

请在 PR 描述中包含以下信息：

## 描述
清晰简洁地描述这个 PR 做了什么。

## 关联的 Issue
Fixes #123 （如果修复了某个 Issue）

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 性能优化
- [ ] 文档更新
- [ ] 代码重构
- [ ] 其他（请说明）

## 测试
- [ ] 我已经添加了测试
- [ ] 所有现有测试通过
- [ ] 需要更新文档

## 截图/日志
（如果适用）

## 其他说明
任何其他需要注意的事项。

4.4 Code Review

PR 提交后，维护者会进行代码审查。可能会要求你做一些修改：

  1. 收到 review 意见后，在同一分支上修改
  2. 推送新的 commit
  3. 在 PR 中回复说明已完成修改
  4. 维护者会在通过后合并

4.5 Commit Message 规范

请遵循以下规范：

<type>(<scope>): <subject>

<body>

<footer>

Type:

  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档更新
  • style: 代码格式（不影响功能）
  • refactor: 重构（不是新功能也不是修 bug）
  • perf: 性能优化
  • test: 添加测试
  • chore: 构建过程或工具链变更

示例:

feat(attention): add support for GQA

Add grouped query attention support to lpu_attention module.
- Add num_kv_heads field to lpu_mha_config_t
- Implement GQA KV expansion logic
- Update tests for GQA configurations

Closes #42

5. 代码规范

5.1 C 代码风格

命名约定

类型规范示例
函数lpu_<module>_<name> (snake_case)lpu_gemm_f32, lpu_rmsnorm_f32_inplace
类型/结构体lpu_<name>_t (snake_case + _t)lpu_mha_config_t, lpu_kvcache_t
宏定义LPU_<NAME> (UPPER_SNAKE_CASE)LPU_OK, LPU_DTYPE_F32
枚举值LPU_<NAME> (UPPER_SNAKE_CASE)LPU_DEV_PREF_CPU
变量snake_casenum_heads, max_seq_len
指针* 靠近变量名float *x

缩进和空格

  • 使用 4 个空格 缩进，不使用 Tab
  • 每行不超过 100 个字符
  • 函数之间空 2 行
  • 函数内逻辑块之间空 1 行

大括号风格

使用 K&R 风格（左大括号不换行）：

// ✅ 正确
if (condition) {
    do_something();
} else {
    do_other();
}

// ❌ 错误
if (condition)
{
    do_something();
}

函数声明

返回类型单独一行：

lpu_status lpu_some_function(
    const float *input,
    float *output,
    size_t n,
    float param
) {
    // 函数体
}

5.2 头文件规范

  • 使用 #ifndef 头文件保护
  • 所有函数放在 #ifdef __cplusplus extern "C" { #endif 中
  • 使用 doxygen 风格注释
#ifndef LPU_ALGO_LPU_<MODULE>_H
#define LPU_ALGO_LPU_<MODULE>_H

#include "lpu_status.h"
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 简短描述
 *
 * 详细描述...
 *
 * @param param1 参数1 描述
 * @param param2 参数2 描述
 * @return 返回值描述
 */
lpu_status lpu_module_function(...);

#ifdef __cplusplus
}
#endif

#endif

5.3 错误处理

  • 所有函数返回 lpu_status 状态码
  • 入口处检查参数有效性
  • 遇到错误立即返回，不继续执行
lpu_status lpu_some_function(const float *x, float *out, size_t n) {
    // 参数检查
    if (x == NULL || out == NULL) {
        return LPU_ERR_NULL;
    }
    if (n == 0) {
        return LPU_ERR_INVALID_ARG;
    }

    // 正常逻辑
    // ...

    return LPU_OK;
}

5.4 安全规范

  • 不使用不安全的函数（如 strcpy, sprintf 等）
  • 所有数组访问做边界检查
  • 使用 lpu_safe_math.h 中的安全数学函数防止溢出
  • 内存分配前检查大小是否合理

6. 测试要求

6.1 测试框架

dbhoo-lpu 使用自定义的轻量测试框架，位于 tests/ 目录。

6.2 添加新测试

在 tests/lpu_unit_tests.c 中添加测试：

static int test_my_new_feature(void) {
    // 准备测试数据
    float input[] = {1.0, 2.0, 3.0};
    float expected[] = {2.0, 4.0, 6.0};
    float output[3] = {0};

    // 执行测试
    lpu_status status = lpu_my_new_feature(input, output, 3, 2.0f);

    // 验证结果
    if (status != LPU_OK) return 0;
    for (int i = 0; i < 3; i++) {
        if (fabsf(output[i] - expected[i]) > 1e-4f) {
            return 0;
        }
    }

    return 1;  // 测试通过
}

// 在 test_suites 数组中注册
static test_case_t test_suites[] = {
    // ... 其他测试 ...
    {"MyModule", "new feature", test_my_new_feature},
};

6.3 运行测试

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)
./lpu_unit_tests

6.4 测试原则

  • 每个新功能必须有测试
  • 测试要覆盖：正常情况、边界情况、错误情况
  • 测试用例要简洁明了
  • 不依赖外部数据或网络

7. 文档贡献

文档和代码同样重要！欢迎改进文档。

7.1 文档位置

  • docs/ – 主要文档
  • docs/tutorials/ – 教程
  • include/ – API 文档（头文件注释）
  • README.md – 项目说明

7.2 文档规范

  • 使用 Markdown 格式
  • 标题层级清晰
  • 代码示例使用正确的语言标记
  • 提供充分的示例
  • 保持简洁、准确、专业

7.3 API 文档

API 文档直接写在头文件中，使用 Doxygen 风格：

/**
 * @brief 执行 F32 矩阵乘法 C = A * B
 *
 * 使用分块优化的 GEMM 实现。
 * 矩阵布局为行主序。
 *
 * @param a 输入矩阵 A [M, K]
 * @param b 输入矩阵 B [K, N]
 * @param c 输出矩阵 C [M, N]
 * @param m M 维度
 * @param k K 维度
 * @param n N 维度
 * @param bm M 分块大小 (0 = 默认)
 * @param bk K 分块大小 (0 = 默认)
 * @param bn N 分块大小 (0 = 默认)
 * @return LPU_OK 成功，错误码失败
 *
 * @note 行主序布局
 * @warning 输出矩阵 C 的内容会被覆盖
 */
lpu_status lpu_gemm_f32(
    const float *a,
    const float *b,
    float *c,
    size_t m,
    size_t k,
    size_t n,
    size_t bm,
    size_t bk,
    size_t bn
);

8. 社区行为准则

8.1 我们的承诺

为了营造开放和友好的环境，我们承诺让每个人参与本项目和社区的体验都不受骚扰。

8.2 我们的标准

积极的行为包括：

  • 使用友好和包容的语言
  • 尊重不同的观点和经验
  • 优雅地接受建设性批评
  • 关注对社区最有利的事情
  • 对其他社区成员表示同理心

不可接受的行为包括：

  • 使用性化的语言或图像，以及不受欢迎的性关注或骚扰
  • 恶意评论、侮辱/贬损性评论以及个人或政治攻击
  • 公开或私下骚扰
  • 未经明确许可发布他人的私人信息，如物理地址或电子邮件地址
  • 在专业环境中可能被合理视为不当的其他行为

8.3 我们的责任

项目维护者有责任阐明可接受行为的标准，并应对任何不可接受的行为采取适当和公平的纠正措施。

9. 常见问题

Q: 我需要签署 CLA 吗？

目前 dbhoo-lpu 开源版不需要签署 CLA。你提交的代码将在 Apache 2.0 许可证下发布。

Q: 如何获得贡献者认可？

所有贡献者都会在 Git 历史中记录。重要贡献者会被添加到 THANKS 文件中。

Q: 我可以问问题吗？

当然可以！你可以：

  • 在 Issue 中提问（标记为 question）
  • 在讨论区发帖

Q: 贡献有报酬吗？

dbhoo-lpu 开源版是社区驱动的开源项目，贡献是自愿的、无偿的。

感谢你的贡献！🎉

© 2026 DBHOO. All rights reserved.

本文章著作权归 DBHOO 所有，未经书面授权，不得转载、摘编或利用其他方式使用本文内容。

文档版本：dbhoo-lpu开源版 v1.0.1