📝 贡献指南

July 8, 2026 · View on GitHub

非常感谢您对 ncmm 项目的关注和贡献！

为了确保项目的健壮性与高质量演进，在您提交贡献之前，请花几分钟阅读以下指南。

🏗️ 透明的开发

  • ncmm 的所有工作均在 GitHub 上公开进行。
  • 无论是核心团队成员还是外部贡献者的 Pull Request，都将经历相同的 Review 和自动化 CI 流程。

🐛 提交 Issue

我们使用 GitHub Issues 进行 Bug 反馈和新特性建议。

在提交 Issue 前，请遵循以下步骤：

  1. 搜索已有问题：检查是否已经有类似或已被解答的 Issue。
  2. 提供复现细节：对于 Bug 报告，请提供完整的运行环境信息（Go 版本、Docker 部署版本等）以及重现 Bug 的最简运行命令或配置文件。
  3. 清晰描述期望：对于新功能建议，请清晰指出您想要的变更以及期望的最终行为。

🚀 提交 Pull Request

共建流程

  1. 认领或创建 Issue：在 GitHub 上创建 Issue 并认领，或在已有的 Issue 中留言表明您正在着手处理，以避免多人重复劳动。
  2. 本地分支开发：从 dev 分支拉取新分支进行开发（命名推荐：feat/xxx 或 fix/xxx）。
  3. 完成代码与测试：编写代码，并为新功能补充必要的单元测试。
  4. 提交 PR：将分支推送到您的 Fork 仓库，并向官方仓库的 dev 分支提交 Pull Request。

开发准备工作

要进行本地开发和调试，您需要准备以下环境：

  • Go 语言环境：项目需要 Go 1.25.0 及以上版本。
  • 依赖项获取： 
    go mod download

本地测试与运行

  • 本地编译运行： 
    go run main.go --help
  • 执行单元测试： 在提交 PR 之前，请确保本地所有测试均已成功通过： 
    go test ./...

🎨 代码开发规范

为了保持代码库的整洁和高可读性，请遵守以下 Go 编码规范：

  1. 格式化与 Linter：

    • 所有的代码必须在提交前使用 gofmt 进行格式化。
    • 建议在 IDE 中开启 goimports 自动清理无用导入。

  2. 注释规范：

    • 所有的公共结构体、接口和函数必须附带清晰的中文注释，解释其入参、返回值和核心设计逻辑。

  3. 本地数据库 (BadgerDB) 使用原则：

    • 鉴于多进程或多实例并发执行的场景，任何对本地进度数据库的操作必须遵守“随用随开、即用即关”的细粒度生命周期管理原则。
    • 禁止在包含网络请求或 time.Sleep 挂起的长时间任务里独占或持有 database.Database 实例。

  4. 提交信息规范：

    • 我们推崇使用 Conventional Commits 规范来书写提交信息。
    • 常用前缀示例：
      • feat: 新增功能
      • fix: 修复 Bug
      • refactor: 代码重构（无功能、Bug 变更）
      • perf: 性能或体验优化
      • docs: 仅文档更新
      • bump: 版本号升级或依赖库更新