如何参与 DM Note 开源贡献：开发环境搭建、代码规范与 CI 流程完整指南

如何参与 DM Note 开源贡献：开发环境搭建、代码规范与 CI 流程完整指南

【免费下载链接】DmNoteMake it yours. A customizable key viewer for DJMAX RESPECT V and any game.项目地址: https://gitcode.com/gh_mirrors/dm/DmNote

DM Note 是一款专为 DJMAX RESPECT V 及各类音游打造的可自定义按键可视化桌面工具，采用 Rust + React 的 Tauri 架构。本文将带你用最短路径完成 DM Note 开源贡献的全流程：从零搭建开发环境、掌握项目代码规范，到理解 PR 提交后的 CI 自动检查机制，适合第一次参与该项目贡献的新手。

一、先了解：哪些贡献方式都欢迎 🎯

DM Note 的官方贡献指南是 CONTRIBUTING.md，其中明确了两大类贡献方向，新手可以从门槛最低的方式入手：

小贴士：新增功能或较大改动前，请先开 Issue 讨论，避免重复劳动。

二、5 分钟搭建 DM Note 开发环境

1. 安装三个前置依赖

项目对工具链版本有精确要求（CI 也使用同样版本），建议本地保持一致：

• Node.js：版本以 .node-version 为准（22.23.2）
• Rust：版本锁定在 rust-toolchain.toml（1.93.0，含 clippy、rustfmt）
• Tauri v2 平台依赖（如 Windows 的 WebView2、macOS 的 Xcode 命令行工具）

2. 克隆仓库并启动

git clone https://gitcode.com/gh_mirrors/dm/DmNote cd DmNote npm install npm run tauri:dev

启动成功后会看到主编辑窗口，包含按键画布、图层面板与属性面板，这就是你要贡献的核心界面：

3. Windows 贡献者必读：ASIO 音频后端

Windows 下tauri:dev默认启用 ASIO 键音输出，需要额外安装 LLVM 并配置LIBCLANG_PATH。如果你只是做普通贡献（不涉及音频代码），直接使用无 ASIO 模式更省事：

npm run tauri:dev:no-asio

详细说明见 README.md 的 "Windows ASIO 빌드" 章节。

三、项目结构导航：代码在哪里 📂

理解目录划分是写出"合群"代码的前提。项目分为 React 前端与 Rust 后端两大块：

更深入的模块边界规则（新功能放哪个文件夹、测试跟实现走等）写在 AGENTS.md，贡献前建议通读一遍。

四、代码规范速查：命名与风格

DM Note 采用强约束的命名与导出风格，PR 检查（CI 快速检验）会盯住这些细节。

文件与组件命名

关键风格约定（节选自 AGENTS.md）

• TypeScript/React：新文件必须用 TS；组件用箭头函数 + Props 内联解构；组件export default，Hook/工具 named export
• Rust：#[tauri::command]不写 permission 属性（build.rs自动生成）；默认同步fn，确需 await 才用async fn
• 注释：除技术术语外使用韩文，采用关键词/名词风格（如// 카운터 초기화）
• API 文档同步：改动插件 API（dmn.*）或 Tauri 命令时，必须同步更新 docs/content/ 下en/与ko/双语 MDX 文档
• 严格类型：tsconfig.strict.json 对共享契约、编辑模型、提交引擎等核心区域开启 strict 检查，禁止用非空断言或any掩盖错误

五、PR 提交前检查清单 ✅

在本地把下面两组命令跑通，PR 就能少踩很多 CI 的坑。

前端改动时：

npm run type-check # 全量类型检查 + 核心区域 strict 检查 npm run lint # ESLint npm run format # Prettier npm test # Vitest 单元测试

后端改动时：

cd src-tauri cargo check cargo clippy --all-targets -- -D warnings cargo fmt

另外两点容易漏掉的兼容性要求：

1. 改dmn.*插件 API 或 Tauri 命令时，确认向后兼容（存量插件不能被打破）；设置文件结构变化需评估迁移逻辑
2. 新增/删除 Tauri 命令后，src-tauri/permissions/dmnote-allow-all.json的变更要一并提交（CI 会 diff 检查）

测试配置见 vitest.config.ts，文档代码块校验等契约测试位于 tests/。

六、CI 流程：你的 PR 会被检查什么 🛡️

CI 运营细节完整记录在 docs/ci-operations.md。PR 工作流由6 个 Job组成，前两个串行、中间三个并行：

几个值得知道的机制：

• Draft 状态只跑快速检验，切到 Ready 后会自动触发全量检验并取消旧的运行
• 纯文档 PR（只改README.md、docs/**/*.md等）会跳过前端/平台重型 Job，所以提交文档翻译类贡献合得非常快，是新手最友好的入口
• 每周还有 Weekly Validation 做覆盖率、npm audit / cargo-audit 依赖审计

自定义 CSS 是社区最活跃的生态之一——玩家通过 CSS 变量重按键配色、制作霓虹主题，这类主题/插件代码同样遵循上述规范：

七、标准贡献流程（4 步走）📨

1. 开 Issue讨论你想做的变更
2. Fork 仓库并创建功能分支
3. 本地跑通第四节的检查清单 + 手动回归受影响功能
4. 提交 PR，等待 CI Gate 全绿后由维护者合入

AI 辅助编码（Vibe Coding）的贡献同样欢迎，但提交前请务必亲自理解并审查代码行为与质量。

参考资料

• 贡献指南：CONTRIBUTING.md / docs/contributing_en.md
• 项目规则与模块边界：AGENTS.md
• CI 运营说明：docs/ci-operations.md、docs/ci-adoption-plan.md
• 交互性能基准：benchmarks/results/
• 多语言翻译资源：src/renderer/locales/

【免费下载链接】DmNoteMake it yours. A customizable key viewer for DJMAX RESPECT V and any game.项目地址: https://gitcode.com/gh_mirrors/dm/DmNote