如何给OpenMMO贡献代码？CLA签署与CI检查新手完整指南

如何给OpenMMO贡献代码？CLA签署与CI检查新手完整指南

【免费下载链接】OpenMMO项目地址: https://gitcode.com/GitHub_Trending/open/OpenMMO

OpenMMO 是一个用 Rust 构建、AI 智能体与人类玩家平等游玩的开源 3D MMORPG。新手给 OpenMMO 贡献代码时，最容易卡住的两关是CLA 签署（首个 PR 必须完成）和CI 检查（Rust + 前端多组检查）。本文带你从拉取仓库、选任务、本地自查，到提交 PR 并签署 CLA，一次走通整个贡献流程。

认识OpenMMO：你的代码会改到哪？

OpenMMO 是一个 Cargo Workspace + 两个 Svelte 前端的应用结构，贡献前先知道各模块职责，选任务会快很多：

第一步：克隆仓库并跑通本地环境

git clone https://gitcode.com/GitHub_Trending/open/OpenMMO cd OpenMMO

环境要求：Rust & Cargo、Node.js & npm；Linux 上还需要flock（util-linux提供），用于串行化 WASM 构建。

关键一步——二进制资源（3D 模型、音乐、音效）不在 git 里，先拉取一次：

bash tools/fetch-assets.sh

然后在client/下执行npm install。完整步骤见 README.md 的 Development Setup 章节。

⚠️ 地形数据需要本地烘焙（约 73 GB 磁盘占用）。如果你只改前端 UI 或 agent-client，可以先跳过；但涉及世界渲染的功能验证必须烘焙，否则世界会是黑的。

选任务：先翻 TODO 待办清单，再看进行中的 PR

选错任务是新手最常见的浪费：

1. doc/TODO.md是维护者的 backlog，也是"最想要的工作"来源——列表更新很快，动手前先对照当前代码确认条目还没被做掉；
2. 动手前检查开放的 PR：多位贡献者并行开发，一个任务可能在一天之内被别人认领；
3. 较大的改动（新系统、UI、设计决策）建议先开一个 issue 描述方案，再动手写代码。

CI 会跑的 3 组检查：推送前本地自查一遍

CI 配置在 .github/workflows/ci.yml，每个 PR 都会自动运行。提前在本地跑同样的命令，可以省掉一轮"推送—失败—修复"的往返：

① Rust（在仓库根目录）

cargo fmt --all --check cargo clippy --workspace --all-targets --locked -- -D warnings cargo test --workspace --locked

-D warnings表示任何警告都会导致 CI 失败，这是新手 PR 最常见的挂法。

② Client（在client/目录）

npm run build:wasm # WASM 绑定 + 生成数据（必需，见下方说明） npm test # vitest 单元测试 npm run check # svelte-check + tsc npm run lint # eslint npm run format:check # prettier（可用 npm run format 自动修复）

③ Dashboard（在dashboard/目录）

npm ci后依次跑check/lint/test/build，只在你改了 dashboard/ 时才需要关心。

一个容易踩的坑：WASM 产物不存入 git。修改了shared/里的 Rust 代码后，必须重新npm run build:wasm，CI 也会先构建再跑客户端检查。

第一个 PR 的必过关卡：CLA 签署流程

首次提交 PR 时，机器人会自动留言要求你签署 贡献者许可协议。流程很短，但必须先签才能合并：

1. 打开 CLA.md 通读条款（核心是：你授予维护者对贡献内容的版权与专利许可，以保护你自己和项目的用户）；

2. 在 PR 评论区原样输入下面这句话（机器人靠精确匹配识别）：

   I have read the CLA Document and I hereby sign the CLA

3. 机器人会在cla-signatures分支记录你的签名，CLA 检查变绿即可等待合并。

机器人逻辑见 .github/workflows/cla.yml——如果状态一直不更新，可以再评论recheck触发复查。

PR 规范（来自 CONTRIBUTING.md）：

• 分支名短小、kebab-case（如fix-chip-through-floor）
• commit message 用祈使句、说明意图，与现有历史风格一致
• PR 描述写清楚改了什么、怎么测的；任务来自 TODO 清单时，引用对应条目

特殊提醒：二进制资产走另一条路

3D 模型、音乐、音效不进 git，托管在外部数据集并由 assets.lock 锁定版本；只有client/public下的图标等图片是直接进 PR 的。如果要提交二进制资产，请按 doc/ASSETS.md 的数据集 PR 流程走，并在doc/assets/对应文件中记录资源来源与许可证。

常见问题速答

• PR 卡在 CLA 检查不动？检查评论是否一字不差，或补一条recheck评论。
• clippy 挂了但我本地没报错？本地确认用的是--locked和-D warnings，与 CI 完全一致。
• 改了 shared/ 客户端没反应？忘了npm run build:wasm。
• 不知道做什么？回到 doc/TODO.md 挑一个未勾选项，先确认没有人在做。

关键文件速查

照着"选任务 → 本地跑通 CI 同款检查 → 提交 PR → 签署 CLA"四步走，你的第一个 OpenMMO PR 就能顺利合并。🎉

【免费下载链接】OpenMMO项目地址: https://gitcode.com/GitHub_Trending/open/OpenMMO