Contributing

Thank you for your interest in contributing to QPanda3 Runtime MCP Server!

Getting Started

Prerequisites

• Python 3.10 or higher
• Git
• uv (recommended) or pip

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server

3. Install development dependencies:

uv sync --all-extras

Development Setup

Code Style

We use the following tools for code quality:

• Ruff for linting and formatting
• mypy for type checking

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type check
uv run mypy src/

Pre-commit Hooks

Install pre-commit hooks:

uv run pre-commit install

Making Changes

Branch Naming

• feature/your-feature for new features
• fix/your-fix for bug fixes
• docs/your-docs for documentation changes

Commit Messages

Follow conventional commits:

• feat: add new feature
• fix: resolve bug
• docs: update documentation
• test: add tests
• refactor: improve code structure

Testing

Test Categories

Category	Location	Description
Unit Tests	tests/	Individual function/class tests with mocks
E2E Tests	tests/e2e/	End-to-end MCP protocol and workflow tests
Integration	tests/	Tests with external services (requires credentials)

Running Tests

# Run all tests
uv run pytest

# Run with coverage (target: 80%+)
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py

# Run E2E tests only
uv run pytest tests/e2e/ -v

# Run with markers
uv run pytest -m e2e -v          # E2E tests
uv run pytest -m "not e2e" -v    # Unit tests only

Writing Tests

• Place unit tests in the tests/ directory
• Place E2E tests in the tests/e2e/ directory
• Use pytest fixtures from conftest.py
• Aim for 80%+ test coverage
• Follow TDD: write tests first, then implement

For detailed E2E testing guide, see E2E Testing.

Documentation

Building Documentation

This project uses MkDocs with the Material theme for documentation.

# Install documentation dependencies
uv sync --extra docs

# Build documentation (English + Chinese)
./scripts/build-docs.sh

# Local preview (with language switching)
mkdocs serve

Documentation Structure

docs/              # English documentation (default)
docs/zh/           # Chinese documentation
mkdocs.yml         # MkDocs configuration with i18n plugin

Adding New Documentation Pages

1. Create the page as a Markdown file in docs/ (English)
2. Create the corresponding Chinese version in docs/zh/
3. Add it to the nav section in mkdocs.yml
4. Add the Chinese nav label in nav_translations.zh in mkdocs.yml
5. For untranslated Chinese pages, copy the English version with a "not yet translated" banner:

!!! warning
    此页面尚未翻译。[English version](../../page.md).

(English content follows)

Documentation Style

• Use Markdown (.md) for all documentation
• API reference is auto-generated from docstrings using mkdocstrings
• Include code examples where helpful
• Use MkDocs Material admonitions for notes and warnings

Pull Request Process

1. Create a feature branch from main
2. Make your changes
3. Add tests for new functionality
4. Update documentation
5. Run all tests and linting
6. Submit a pull request

PR Checklist

• Code follows project style guidelines
• All tests pass
• New code has appropriate test coverage
• Documentation is updated
• Commit messages follow conventions

Code of Conduct

Please be respectful and inclusive in all interactions.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.