Skip to content

Latest commit

 

History

History
204 lines (137 loc) · 3.95 KB

CONTRIBUTING.md

File metadata and controls

204 lines (137 loc) · 3.95 KB

Contributing to xcodemcpwrapper

Thank you for your interest in contributing! This document outlines the development workflow and quality gates.

Development Setup

# Clone the repository
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper

# Create and activate a virtual environment (recommended on macOS/Homebrew Python)
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip

# Install in editable mode with dev dependencies
python3 -m pip install -e ".[dev]"

Quality Gates

All code must pass the following quality gates before being merged:

1. Tests (pytest)

Run all tests with coverage:

pytest tests/ -v --cov=src --cov-report=term

Requirements:

  • All tests must pass
  • Coverage must remain ≥90%

2. Linting (ruff)

Check for code issues:

ruff check src/ tests/

Auto-fix issues where possible:

ruff check src/ tests/ --fix

3. Formatting (ruff)

Check code formatting:

ruff format --check src/ tests/

Apply formatting:

ruff format src/ tests/

4. Type Checking (mypy)

mypy src/

5. Doc Sync Check

Ensure documentation changes are synced with DocC catalog:

make doccheck-all
# or
python scripts/check_doc_sync.py --all

This checks that changes to docs/*.md files are also reflected in the DocC catalog (Sources/XcodeMCPWrapper/Documentation.docc/) across unstaged, staged, and branch scopes.

6. Build Verification

Ensure the package builds correctly:

python -m build
twine check dist/*

Quick Check Script

Run all quality gates at once:

make test && make lint && make typecheck

Or use this bash script (save as check.sh):

#!/bin/bash
set -e

echo "=== Running Quality Gates ==="

echo "1. Running tests..."
pytest tests/ -v --cov=src --cov-report=term

echo "2. Running linter..."
ruff check src/ tests/

echo "3. Checking format..."
ruff format --check src/ tests/

echo "4. Running type checker..."
mypy src/

echo "5. Checking doc sync..."
python scripts/check_doc_sync.py --all

echo "6. Building package..."
python -m build && twine check dist/*

echo "=== All Quality Gates Passed ==="

Make it executable and run:

chmod +x check.sh
./check.sh

Adding New Features

When adding new features that require specific commands or dependencies:

Update the Makefile

Add relevant make targets for the new feature. For example:

# For optional features with extra dependencies
install-feature:
	python3 -m pip install -e ".[feature]"

# For feature-specific tests
test-feature:
	pytest tests/unit/feature/ tests/integration/feature/ -v

Then update the .PHONY line and help target to include the new commands.

Update pyproject.toml

If the feature has optional dependencies, add them to [project.optional-dependencies]:

[project.optional-dependencies]
feature = [
    "dependency1>=1.0",
    "dependency2>=2.0",
]

Workflow

We follow the FLOW.md workflow:

  1. BRANCH - Create a feature branch from main
  2. SELECT - Pick a task from the workplan
  3. PLAN - Create a PRD for the task
  4. EXECUTE - Implement and run quality gates
  5. ARCHIVE - Move completed task to archive

Pull Request Process

  1. Create a feature branch: git checkout -b feature/TASK-ID-description
  2. Make your changes and run quality gates
  3. Commit with clear messages
  4. Push to your fork
  5. Create a Pull Request against main

CI/CD

All PRs trigger GitHub Actions CI which runs:

  • Lint & Type Check (Python 3.11)
  • Tests (Python 3.9, 3.10, 3.11, 3.12)
  • Package Build

See .github/workflows/ci.yml for details.

Code Style

  • Follow PEP 8 guidelines
  • Use type hints where possible
  • Write docstrings for public functions
  • Keep functions focused and small

Questions?

Open an issue or check the troubleshooting guide.