MoonRepo/moon 项目开发环境搭建与贡献指南

MoonRepo/moon 项目开发环境搭建与贡献指南

moon A task runner and repo management tool for the web ecosystem, written in Rust. 项目地址: https://gitcode.com/gh_mirrors/moo/moon

项目概述

MoonRepo/moon 是一个基于 Rust 构建的现代化构建工具和任务运行器，旨在为 JavaScript 和 TypeScript 项目提供高效的构建体验。该项目采用 Rust 作为核心实现，同时提供 Node.js 包以支持前端开发工作流。

开发环境准备

系统要求

在开始贡献代码前，需要确保开发环境满足以下基本要求：

1. Node.js：版本需不低于 v14.15
2. Rust：版本需不低于 1.61
3. Git：版本需不低于 2.28（主要用于测试覆盖率功能）
4. Just：一个现代化的命令行工具，用于简化常见开发任务

Rust 环境配置

由于 moon 的核心是用 Rust 编写的，因此需要配置完整的 Rust 开发环境：

1. 安装 Rust 工具链（推荐通过官方安装脚本）
2. 安装完成后，执行以下命令初始化开发环境：

   just init
   

3. 构建 Rust 二进制文件（这是后续开发的基础）：

   just build
   

Node.js 环境配置

对于前端相关功能的开发，需要配置 Node.js 环境：

1. 推荐使用 proto 工具管理 Node.js 和 Yarn 版本
2. 安装项目依赖：

   yarn install
   

开发工作流详解

Rust 开发相关命令

项目使用 Just 工具简化常见开发任务：

• 构建：just build - 将所有 crate 构建为单个 moon 二进制文件
• 代码格式化：just format - 自动格式化代码
• 代码检查：just lint - 运行 linter 检查代码质量
• 测试：just test - 运行单元测试和集成测试
• 覆盖率：just cov - 运行测试并生成代码覆盖率报告

代码覆盖率分析

项目使用 llvm-cov 进行基于源码的代码覆盖率分析：

1. 安装必要工具：

   rustup component add llvm-tools-preview
   cargo install cargo-llvm-cov
   

2. 运行 just cov 命令（此过程较耗时）
3. 生成 HTML 覆盖率报告：

   just gen-html
   

   报告将生成在 ./coverage 目录下

Node.js 开发相关命令

项目使用 moon 自身来管理各个 npm 包：

• 构建：yarn moon run <project>:build
• 格式化：yarn moon run <project>:format
• 代码检查：yarn moon run <project>:lint
• 测试：yarn moon run <project>:test
• 类型检查：yarn moon run <project>:typecheck

类型检查

使用 TypeScript 进行静态类型检查，建议在开发过程中优先运行类型检查。

测试规范

测试使用 Jest 框架编写，要求为每个函数或类编写对应的 *.test.ts 测试文件，且主要关注单元测试而非集成测试。

代码规范

使用 ESLint 进行代码质量检查，大多数规则设置为错误级别，少数警告级别的规则主要用于提示浏览器兼容性问题和可能需要 polyfill 的情况。

最佳实践建议

1. 代码提交前：确保本地构建通过，所有测试和 lint 检查都成功
2. 功能开发：遵循项目现有的代码风格和架构模式
3. 测试编写：为新功能编写全面的单元测试，保持高测试覆盖率
4. 类型安全：充分利用 TypeScript 的类型系统，避免使用 any 类型
5. 性能考量：特别是在 Rust 部分代码中，注意内存管理和性能优化

通过遵循这些指南，开发者可以高效地为 moon 项目做出贡献，同时保持代码库的一致性和质量。

moon A task runner and repo management tool for the web ecosystem, written in Rust. 项目地址: https://gitcode.com/gh_mirrors/moo/moon