Language: 简体中文 English

感谢你对 Mini-Inference Engine 的兴趣！本文档详细说明如何为项目做出贡献。

目录 (Table of Contents)

行为准则

  • 尊重所有贡献者
  • 保持专业和建设性的讨论
  • 接受建设性的批评
  • 以项目最佳利益为出发点

如何贡献

报告 Bug

  1. 检查 Issues 是否已有相关问题
  2. 创建新 issue，包含以下信息：
    • 问题描述：清晰描述问题
    • 复现步骤：如何复现问题
    • 预期行为：应该发生什么
    • 实际行为：实际发生了什么
    • 环境信息：GPU 型号、CUDA 版本、操作系统

提交功能请求

  1. 描述功能需求和使用场景
  2. 说明为什么这个功能对项目有价值
  3. 提供可能的实现方案（可选）

提交代码

1. Fork 仓库 

1
2
3

git clone https://github.com/<your-username>/mini-inference-engine.git
cd mini-inference-engine
git remote add upstream https://github.com/LessUp/mini-inference-engine.git

2. 创建分支 

1
2
3
4
5

# 功能分支
git checkout -b feature/my-feature

# 或修复分支
git checkout -b fix/bug-description

3. 编写代码

遵循 代码规范。

4. 测试 

1
2
3
4
5
6
7
8

# Debug + tests
cmake --preset default
cmake --build --preset default
ctest --preset default

# Release 构建
cmake --preset release
cmake --build --preset release

5. 提交 

1
2

git add .
git commit -m "feat: add new feature"

提交信息格式遵循 Conventional Commits：

类型 说明
feat: 新功能
fix: Bug 修复
docs: 文档更新
perf: 性能优化
refactor: 代码重构
test: 测试相关
chore: 构建/工具变更

6. 推送并创建 PR 

1

git push origin feature/my-feature

然后在 GitHub 上创建 Pull Request。

开发环境设置

环境要求

依赖 最低版本 推荐版本
CUDA Toolkit 11.0 12.0+
CMake 3.18 3.25+
C++ 编译器 GCC 9 / Clang 10 GCC 11+
GPU 计算能力 7.0+ 8.0+

验证环境 

1
2
3
4
5
6
7
8
9

# 检查 CUDA
nvcc --version
nvidia-smi

# 检查 CMake
cmake --version

# 检查编译器
gcc --version

代码规范

C++ 代码风格 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 命名规范
class ClassName;           // 类名: PascalCase
void function_name();      // 函数名: snake_case
int variable_name;         // 变量名: snake_case
const int CONSTANT_NAME;   // 常量: UPPER_SNAKE_CASE
int member_variable_;      // 成员变量: snake_case + 下划线后缀

// 缩进: 4 空格
void function() {
    if (condition) {
        // code
    }
}

// 大括号: 同行
if (condition) {
    // code
} else {
    // code
}

CUDA 代码风格 

1
2
3
4
5
6
7
8
9
10
11
12

// Kernel 命名: snake_case
__global__ void my_kernel(...);

// 模板参数: UPPER_SNAKE_CASE
template<int BLOCK_SIZE, bool USE_SHARED>
__global__ void templated_kernel(...);

// 共享内存: 前缀 s_
__shared__ float s_data[256];

// 寄存器变量: 前缀 r_
float r_sum = 0.0f;

文件组织 

1
2
3
4
5
6
7
8
9
10
11
12
13
14

include/
├── common.h          # 通用定义
├── kernels.cuh       # Kernel 声明
├── feature.h         # 功能模块头文件
└── ...

src/
├── kernel_name.cu    # Kernel 实现
├── feature.cpp       # 功能模块实现
└── ...

tests/
├── test_feature.cpp  # 功能测试
└── ...

代码格式化

使用 clang-format 格式化代码：

1

clang-format --style=file -i <file>

测试要求

单元测试

每个新功能都需要测试：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

#include <gtest/gtest.h>
#include "feature.h"

class FeatureTest : public ::testing::Test {
protected:
    void SetUp() override {
        CUDA_CHECK(cudaSetDevice(0));
    }
};

TEST_F(FeatureTest, BasicFunctionality) {
    // 测试基本功能
    EXPECT_EQ(expected, actual);
}

TEST_F(FeatureTest, EdgeCases) {
    // 测试边界情况
}

性能测试

对于性能相关的更改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

TEST_F(FeatureTest, Performance) {
    GpuTimer timer;
    
    // Warmup
    for (int i = 0; i < 5; i++) {
        function_under_test();
    }
    
    // Benchmark
    timer.start();
    for (int i = 0; i < 20; i++) {
        function_under_test();
    }
    timer.stop();
    
    float avg_time = timer.elapsed_ms() / 20;
    printf("Average time: %.3f ms\n", avg_time);
}

文档要求

代码注释 

1
2
3
4
5
6
7
8
9
10

/// @brief 执行优化的 GEMM 运算
/// @param A 输入矩阵 A (M x K)
/// @param B 输入矩阵 B (K x N)
/// @param C 输出矩阵 C (M x N)
/// @param M 矩阵 A 的行数
/// @param N 矩阵 B 的列数
/// @param K 矩阵 A 的列数 / 矩阵 B 的行数
/// @param stream CUDA 流（可选）
void launch_optimized_gemm(const float* A, const float* B, float* C,
                           int M, int N, int K, cudaStream_t stream = 0);

README 更新

如果添加新功能，更新 README.md：

  • 功能列表
  • 使用示例
  • API 说明

提交流程

审查流程

  1. 自动检查
    • 编译通过
    • 测试通过
    • 代码风格检查
  2. 人工审查
    • 代码质量
    • 设计合理性
    • 文档完整性
  3. 性能验证（如适用）
    • 不引入性能回归
    • 新优化有效

合并要求

  • 所有 CI 检查通过
  • 至少 1 个审查者批准
  • 无未解决的审查意见

联系方式

相关链接

*最后更新：2025-04-16 文档版本：v1.1.0*

Back to top

MIT License | A learning project for the CUDA community