Contributing Guide | 贡献指南

English

Thank you for your interest in contributing to cocos-cli! This guide will help you get started with development, testing, and submitting changes.

📋 Table of Contents

Prerequisites
Getting Started
Development Workflow
Testing
Code Style
Debugging
Submitting Changes

Prerequisites

Before you begin, ensure you have:

Node.js >= 16.x
npm >= 8.x
Git

Getting Started

Fork and Clone

git clone https://github.com/YOUR_USERNAME/cocos-cli.git
cd cocos-cli

Install Dependencies

npm install

Build the Project

npm run build

This will:

Clear previous build artifacts
Compile TypeScript to JavaScript
Copy .d.ts declaration files
Generate JSON schemas

Development Workflow

1. Build and Compile

Full Build (recommended for first build or after major changes):

npm run build
# or
npm run compile

Watch Mode (for active development):

npm run build:watch

This will automatically recompile TypeScript files when you make changes.

Clear Build Cache:

npm run build:clear

2. Generate Type Definitions

After modifying MCP API schemas or tools:

npm run generate:mcp-types

This generates type-safe definitions for E2E tests in e2e/types/mcp-tools.generated.ts.

Testing

Unit Tests

Run all unit tests:

npm test

Run tests in watch mode (for active development):

npm run test:watch

Run tests with coverage report:

npm run test:coverage

Run tests silently (minimal output):

npm run test:quiet

E2E Tests

Full E2E test suite:

npm run test:e2e

E2E tests with debug mode (preserves test workspace):

npm run test:e2e:debug

The test workspace will be preserved at .test-workspace for inspection.

Check E2E test coverage:

# Console output
npm run check:e2e-coverage

# Generate HTML report
npm run check:e2e-coverage:report

The coverage report will be saved to e2e/server/reports/.

Run All Tests

npm run test:all

This runs both unit tests and E2E tests.

Code Style

This project uses ESLint and Prettier for code formatting.

Check for linting errors:

# Check specific files
npx eslint src/**/*.ts

# Check all TypeScript files
npx tsc --noEmit

Auto-fix formatting (if configured):

npx eslint --fix src/**/*.ts

Debugging

1. Debug MCP Server

Start the MCP server with a test project:

npm run start:mcp-debug

This starts the MCP server using the test project at ./tests/fixtures/projects/asset-operation.

2. MCP Inspector

Use the MCP Inspector to interact with the server:

npm run start:mcp-inspector

This opens a web interface for testing MCP tools.

3. Debug E2E Tests

Method 1: Preserve Test Workspace

npm run test:e2e:debug

The test workspace will be kept after tests finish, allowing you to inspect the state.

Method 2: Debug in VS Code

Add this configuration to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug E2E Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test:e2e", "--", "--runInBand"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Unit Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

Method 3: Debug Specific Test File

npx jest path/to/test.test.ts --runInBand

4. Debug CLI Commands

node --inspect-brk ./dist/cli.js [command] [options]

Then attach your debugger to the Node.js process.

Submitting Changes

1. Create a Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

Write clear, concise commit messages
Follow the existing code style
Add tests for new features
Update documentation as needed

3. Test Your Changes

# Run all tests
npm run test:all

# Check E2E coverage if you modified APIs
npm run check:e2e-coverage:report

4. Commit and Push

git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name

5. Create a Pull Request

Go to the repository on GitHub
Click "New Pull Request"
Fill in the PR template with:
- Description of changes
- Related issues
- Test results
- Screenshots (if UI changes)

Commit Message Guidelines

Follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat: add assets-create-asset MCP tool
fix: resolve null reference in asset query
docs: update E2E testing guide
test: add E2E tests for builder API

Additional Resources

E2E Testing Guide: See e2e/README.md
Type Inference Guide: See e2e/docs/TYPE-INFERENCE-EXAMPLE.md
Test Coverage Report: See e2e/scripts/README.md

中文

感谢您对 cocos-cli 项目的关注！本指南将帮助您开始开发、测试和提交代码变更。

前置要求

开始之前，请确保安装：

Node.js >= 16.x
npm >= 8.x
Git

开始使用

Fork 并克隆仓库

git clone https://github.com/YOUR_USERNAME/cocos-cli.git
cd cocos-cli

安装依赖

npm install

构建项目

npm run build

这将：

清理之前的构建产物
编译 TypeScript 到 JavaScript
复制 .d.ts 类型声明文件
生成 JSON schemas

开发流程

1. 构建和编译

完整构建（推荐用于首次构建或重大更改后）：

npm run build
# 或
npm run compile

监听模式（用于活跃开发）：

npm run build:watch

这会在你修改文件时自动重新编译 TypeScript 文件。

清理构建缓存：

npm run build:clear

2. 生成类型定义

修改 MCP API schemas 或工具后：

npm run generate:mcp-types

这会在 e2e/types/mcp-tools.generated.ts 中生成 E2E 测试的类型安全定义。

测试

单元测试

运行所有单元测试：

npm test

监听模式运行测试（用于活跃开发）：

npm run test:watch

运行测试并生成覆盖率报告：

npm run test:coverage

静默运行测试（最小输出）：

npm run test:quiet

E2E 测试

完整 E2E 测试套件：

npm run test:e2e

E2E 测试调试模式（保留测试工作区）：

npm run test:e2e:debug

测试工作区将保留在 .test-workspace 目录中以供检查。

检查 E2E 测试覆盖率：

# 控制台输出
npm run check:e2e-coverage

# 生成 HTML 报告
npm run check:e2e-coverage:report

覆盖率报告将保存到 e2e/server/reports/ 目录。

运行所有测试

npm run test:all

这会同时运行单元测试和 E2E 测试。

代码风格

本项目使用 ESLint 和 Prettier 进行代码格式化。

检查 lint 错误：

# 检查特定文件
npx eslint src/**/*.ts

# 检查所有 TypeScript 文件
npx tsc --noEmit

自动修复格式（如果已配置）：

npx eslint --fix src/**/*.ts

调试

1. 调试 MCP 服务器

使用测试项目启动 MCP 服务器：

npm run start:mcp-debug

这会使用 ./tests/fixtures/projects/asset-operation 测试项目启动 MCP 服务器。

2. MCP 检查器

使用 MCP Inspector 与服务器交互：

npm run start:mcp-inspector

这会打开一个 Web 界面用于测试 MCP 工具。

3. 调试 E2E 测试

方法 1：保留测试工作区

npm run test:e2e:debug

测试完成后将保留工作区，允许你检查状态。

方法 2：在 VS Code 中调试

在 .vscode/launch.json 中添加以下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "调试 E2E 测试",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test:e2e", "--", "--runInBand"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "调试单元测试",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

方法 3：调试特定测试文件

npx jest path/to/test.test.ts --runInBand

4. 调试 CLI 命令

node --inspect-brk ./dist/cli.js [command] [options]

然后将调试器附加到 Node.js 进程。

提交变更

1. 创建分支

git checkout -b feature/your-feature-name

2. 进行修改

编写清晰、简洁的提交信息
遵循现有代码风格
为新功能添加测试
根据需要更新文档

3. 测试你的修改

# 运行所有测试
npm run test:all

# 如果修改了 API，检查 E2E 覆盖率
npm run check:e2e-coverage:report

4. 提交和推送

git add .
git commit -m "feat: 添加新功能"
git push origin feature/your-feature-name

5. 创建 Pull Request

前往 GitHub 上的仓库
点击 "New Pull Request"
在 PR 模板中填写：
- 变更描述
- 相关 issues
- 测试结果
- 截图（如果有 UI 变更）

提交信息规范

遵循 Conventional Commits：

feat: 新功能
fix: Bug 修复
docs: 文档变更
style: 代码风格变更（格式化等）
refactor: 代码重构
test: 添加或更新测试
chore: 维护任务

示例：

feat: 添加 assets-create-asset MCP 工具
fix: 修复资源查询中的空引用问题
docs: 更新 E2E 测试指南
test: 添加构建器 API 的 E2E 测试

额外资源

E2E 测试指南：查看 e2e/README.md
类型推断指南：查看 e2e/docs/TYPE-INFERENCE-EXAMPLE.md
测试覆盖率报告：查看 e2e/scripts/README.md

🤝 Questions and Support | 问题和支持

If you have questions or need help:

Open an issue on GitHub
Check existing documentation in the docs/ directory
Review E2E testing guides in e2e/docs/

如果您有问题或需要帮助：

在 GitHub 上提出 issue
查看 docs/ 目录中的现有文档
查看 e2e/docs/ 中的 E2E 测试指南

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History