Burn项目示例贡献指南：如何规范提交新案例

在开源深度学习框架Burn的协作开发中，为项目贡献高质量的示例代码是开发者参与的重要方式之一。本文将系统性地介绍如何遵循项目规范提交新示例，帮助开发者快速融入贡献流程。

项目结构认知

Burn采用Cargo工作区(workspace)架构，这意味着：

1. 顶层目录的Cargo.toml定义了工作区级别的配置
2. 所有依赖锁统一由顶层的Cargo.lock管理
3. 示例项目作为工作区成员存在，共享基础配置

创建新示例的标准流程

1. 初始化项目结构

cd examples
cargo new --lib <示例名称>

2. 关键目录规范

• src/：存放核心实现代码
• examples/：包含可执行训练/推理的二进制文件
• README.md：必须包含示例说明和运行指令

3. 依赖管理原则

• 公共依赖（如serde）应继承工作区版本：

serde = { workspace = true }

• Burn框架本身通过相对路径引用
• 示例特有依赖可直接声明

内容编写规范

1. 代码实现要求

• 训练/推理功能应根据示例目标灵活实现
• 资源文件应通过运行时下载获取（模型权重等特殊情况除外）
• 二进制文件命名需语义明确

2. 文档标准

• README需包含：
  • 示例的简要技术说明
  • 可复制的运行代码块
  • 预期输出效果描述

3. 测试验证

• 确保示例能通过cargo run正常执行
• 复杂示例应包含基础单元测试
• 输出结果需符合技术预期

最佳实践建议

1. 避免提交非代码资源文件（如图片数据集），改为运行时下载
2. 保持与现有示例的风格统一
3. 复杂示例建议分步骤实现（如先训练后推理）
4. 提交前在工作区根目录测试运行

通过遵循这些规范，开发者可以确保贡献的示例既能正确展示Burn框架特性，又能与其他组件良好集成。项目维护团队将持续完善贡献指南，降低新成员的参与门槛。