Skip to content

contributing.md

Latest commit

 

History

History
185 lines (126 loc) · 3.73 KB

contributing.md

File metadata and controls

185 lines (126 loc) · 3.73 KB

贡献指南

感谢您对 QPanda3 Runtime MCP Server 的贡献兴趣！

快速开始

前置条件

  • Python 3.10 或更高版本
  • Git
  • uv（推荐）或 pip

Fork 和克隆

  1. 在 GitHub 上 Fork 本仓库
  2. 在本地克隆您的 Fork：
git clone https://github.com/YOUR_USERNAME/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
  1. 安装开发依赖：
uv sync --all-extras

开发设置

代码风格

我们使用以下工具保证代码质量：

  • Ruff 用于代码检查和格式化
  • mypy 用于类型检查
# 格式化代码
uv run ruff format .

# 代码检查
uv run ruff check .

# 类型检查
uv run mypy src/

Pre-commit 钩子

安装 pre-commit 钩子：

uv run pre-commit install

提交更改

分支命名

  • feature/your-feature 用于新功能
  • fix/your-fix 用于 Bug 修复
  • docs/your-docs 用于文档变更

提交消息

遵循 Conventional Commits 规范：

  • feat: add new feature — 新功能
  • fix: resolve bug — Bug 修复
  • docs: update documentation — 文档更新
  • test: add tests — 添加测试
  • refactor: improve code structure — 代码重构

测试

测试类别

类别 位置 说明
单元测试 tests/ 使用 Mock 的函数/类测试
E2E 测试 tests/e2e/ 端到端 MCP 协议和工作流测试
集成测试 tests/ 与外部服务的交互测试（需要凭据）

运行测试

# 运行所有测试
uv run pytest

# 运行覆盖率测试（目标：80%+）
uv run pytest --cov=src --cov-report=html

# 运行特定测试文件
uv run pytest tests/test_server.py

# 仅运行 E2E 测试
uv run pytest tests/e2e/ -v

# 使用标记运行
uv run pytest -m e2e -v          # E2E 测试
uv run pytest -m "not e2e" -v    # 仅单元测试

编写测试

  • 将单元测试放在 tests/ 目录
  • 将 E2E 测试放在 tests/e2e/ 目录
  • 使用 conftest.py 中的 pytest fixtures
  • 目标为 80%+ 的测试覆盖率
  • 遵循 TDD：先写测试，再实现功能

详细的 E2E 测试指南请参阅 E2E 测试。

文档

构建文档

本项目使用 MkDocs 和 Material 主题构建文档。

# 安装文档依赖
uv sync --extra docs

# 构建文档（英文 + 中文）
./scripts/build-docs.sh

# 本地预览（支持语言切换）
mkdocs serve

文档结构

docs/              # 英文文档（默认）
docs/zh/           # 中文文档
mkdocs.yml         # 含 i18n 插件的 MkDocs 配置

添加新文档页面

  1. 在 docs/ 中创建 Markdown 文件（英文）
  2. 在 docs/zh/ 中创建对应的中文版本
  3. 在 mkdocs.yml 的 nav 部分添加条目
  4. 在 mkdocs.yml 的 nav_translations.zh 中添加中文导航标签
  5. 对于未翻译的中文页面，复制英文版本并添加"尚未翻译"横幅：
!!! warning
    此页面尚未翻译。[English version](../../page.md).

(英文内容如下)

文档风格

  • 所有文档使用 Markdown (.md) 格式
  • API 参考通过 mkdocstrings 从 docstring 自动生成
  • 在有帮助的地方包含代码示例
  • 使用 MkDocs Material 的 admonition 语法添加提示和警告

Pull Request 流程

  1. 从 main 创建功能分支
  2. 进行更改
  3. 为新功能添加测试
  4. 更新文档
  5. 运行所有测试和代码检查
  6. 提交 Pull Request

PR 检查清单

  • 代码遵循项目风格指南
  • 所有测试通过
  • 新代码具有适当的测试覆盖率
  • 文档已更新
  • 提交消息遵循规范

行为准则

请在所有交流中保持尊重和包容。

许可证

通过贡献，您同意您的贡献将以 Apache License 2.0 许可。