feat: Week 1 complete - Linux support + IPC API prep
🎉 Major v2.0 rebuild kickoff - Week 1 accomplished! ## Highlights ### Cross-Platform Support 🌍 - ✅ Linux primary platform (Ubuntu/Debian tested) - ✅ Windows fully supported - ✅ macOS experimental support - ✅ Platform-agnostic path handling (XDG spec) - ✅ Auto-detection of KiCAD installation ### Infrastructure 🏗️ - ✅ GitHub Actions CI/CD pipeline - ✅ Pytest framework with 20+ tests - ✅ Pre-commit hooks (Black, MyPy, ESLint) - ✅ Automated Linux installation script - ✅ Enhanced npm scripts ### IPC API Migration Prep 🚀 - ✅ Comprehensive migration plan (30 pages) - ✅ Backend abstraction layer (800+ lines) - ✅ Factory pattern with auto-detection - ✅ SWIG backward compatibility wrapper - ✅ IPC backend skeleton ready ### Documentation 📚 - ✅ Updated README (Linux installation) - ✅ CONTRIBUTING.md guide - ✅ Linux compatibility audit - ✅ IPC API migration plan - ✅ Session summaries - ✅ Platform-specific config templates ## Files Changed - 27 files created - ~3,000 lines of code/docs - 8 comprehensive documentation pages - 20+ unit tests - 5 abstraction layer modules ## Next Steps - Week 2: IPC API migration (project.py → component.py → routing.py) - Migrate from deprecated SWIG to official IPC API - JLCPCB/Digikey integration prep 🤖 Generated with Claude Code https://claude.com/claude-code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
KiCAD MCP Bot
397
CONTRIBUTING.md
Normal file
397
CONTRIBUTING.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Contributing to KiCAD MCP Server
|
||||
|
||||
Thank you for your interest in contributing to the KiCAD MCP Server! This guide will help you get started with development.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Development Environment Setup](#development-environment-setup)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Testing](#testing)
|
||||
- [Code Style](#code-style)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
- [Roadmap & Planning](#roadmap--planning)
|
||||
|
||||
---
|
||||
|
||||
## Development Environment Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **KiCAD 9.0 or higher** - [Download here](https://www.kicad.org/download/)
|
||||
- **Node.js v18+** - [Download here](https://nodejs.org/)
|
||||
- **Python 3.10+** - Should come with KiCAD, or install separately
|
||||
- **Git** - For version control
|
||||
|
||||
### Platform-Specific Setup
|
||||
|
||||
#### Linux (Ubuntu/Debian)
|
||||
|
||||
```bash
|
||||
# Install KiCAD 9.0 from official PPA
|
||||
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y kicad kicad-libraries
|
||||
|
||||
# Install Node.js (if not already installed)
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/kicad-mcp-server.git
|
||||
cd kicad-mcp-server
|
||||
|
||||
# Install Node.js dependencies
|
||||
npm install
|
||||
|
||||
# Install Python dependencies
|
||||
pip3 install -r requirements-dev.txt
|
||||
|
||||
# Build TypeScript
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
pytest
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
```powershell
|
||||
# Install KiCAD 9.0 from https://www.kicad.org/download/windows/
|
||||
|
||||
# Install Node.js from https://nodejs.org/
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/kicad-mcp-server.git
|
||||
cd kicad-mcp-server
|
||||
|
||||
# Install Node.js dependencies
|
||||
npm install
|
||||
|
||||
# Install Python dependencies
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Build TypeScript
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
pytest
|
||||
```
|
||||
|
||||
#### macOS
|
||||
|
||||
```bash
|
||||
# Install KiCAD 9.0 from https://www.kicad.org/download/macos/
|
||||
|
||||
# Install Node.js via Homebrew
|
||||
brew install node
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/kicad-mcp-server.git
|
||||
cd kicad-mcp-server
|
||||
|
||||
# Install Node.js dependencies
|
||||
npm install
|
||||
|
||||
# Install Python dependencies
|
||||
pip3 install -r requirements-dev.txt
|
||||
|
||||
# Build TypeScript
|
||||
npm run build
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
pytest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
kicad-mcp-server/
|
||||
├── .github/
|
||||
│ └── workflows/ # CI/CD pipelines
|
||||
├── config/ # Configuration examples
|
||||
│ ├── linux-config.example.json
|
||||
│ ├── windows-config.example.json
|
||||
│ └── macos-config.example.json
|
||||
├── docs/ # Documentation
|
||||
├── python/ # Python interface layer
|
||||
│ ├── commands/ # KiCAD command handlers
|
||||
│ ├── integrations/ # External API integrations (JLCPCB, Digikey)
|
||||
│ ├── utils/ # Utility modules
|
||||
│ └── kicad_interface.py # Main Python entry point
|
||||
├── src/ # TypeScript MCP server
|
||||
│ ├── tools/ # MCP tool implementations
|
||||
│ ├── resources/ # MCP resource implementations
|
||||
│ ├── prompts/ # MCP prompt implementations
|
||||
│ └── server.ts # Main server
|
||||
├── tests/ # Test suite
|
||||
│ ├── unit/
|
||||
│ ├── integration/
|
||||
│ └── fixtures/
|
||||
├── dist/ # Compiled JavaScript (generated)
|
||||
├── node_modules/ # Node dependencies (generated)
|
||||
├── package.json # Node.js configuration
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── pytest.ini # Pytest configuration
|
||||
├── requirements.txt # Python production dependencies
|
||||
└── requirements-dev.txt # Python dev dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Create a Feature Branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
### 2. Make Changes
|
||||
|
||||
- Edit TypeScript files in `src/`
|
||||
- Edit Python files in `python/`
|
||||
- Add tests for new features
|
||||
|
||||
### 3. Build & Test
|
||||
|
||||
```bash
|
||||
# Build TypeScript
|
||||
npm run build
|
||||
|
||||
# Run TypeScript linter
|
||||
npm run lint
|
||||
|
||||
# Run Python formatter
|
||||
black python/
|
||||
|
||||
# Run Python type checker
|
||||
mypy python/
|
||||
|
||||
# Run all tests
|
||||
npm test
|
||||
pytest
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_platform_helper.py -v
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=python --cov-report=html
|
||||
```
|
||||
|
||||
### 4. Commit Changes
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: Add your feature description"
|
||||
```
|
||||
|
||||
**Commit Message Convention:**
|
||||
- `feat:` - New feature
|
||||
- `fix:` - Bug fix
|
||||
- `docs:` - Documentation changes
|
||||
- `test:` - Adding/updating tests
|
||||
- `refactor:` - Code refactoring
|
||||
- `chore:` - Maintenance tasks
|
||||
|
||||
### 5. Push and Create Pull Request
|
||||
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
Then create a Pull Request on GitHub.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
pytest
|
||||
|
||||
# Unit tests only
|
||||
pytest -m unit
|
||||
|
||||
# Integration tests (requires KiCAD installed)
|
||||
pytest -m integration
|
||||
|
||||
# Platform-specific tests
|
||||
pytest -m linux # Linux tests only
|
||||
pytest -m windows # Windows tests only
|
||||
|
||||
# With coverage report
|
||||
pytest --cov=python --cov-report=term-missing
|
||||
|
||||
# Verbose output
|
||||
pytest -v
|
||||
|
||||
# Stop on first failure
|
||||
pytest -x
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
Tests should be placed in `tests/` directory:
|
||||
|
||||
```python
|
||||
# tests/test_my_feature.py
|
||||
import pytest
|
||||
|
||||
@pytest.mark.unit
|
||||
def test_my_feature():
|
||||
"""Test description"""
|
||||
# Arrange
|
||||
expected = "result"
|
||||
|
||||
# Act
|
||||
result = my_function()
|
||||
|
||||
# Assert
|
||||
assert result == expected
|
||||
|
||||
@pytest.mark.integration
|
||||
@pytest.mark.linux
|
||||
def test_linux_integration():
|
||||
"""Integration test for Linux"""
|
||||
# This test will only run on Linux in CI
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Style
|
||||
|
||||
### Python
|
||||
|
||||
We use **Black** for code formatting and **MyPy** for type checking.
|
||||
|
||||
```bash
|
||||
# Format all Python files
|
||||
black python/
|
||||
|
||||
# Check types
|
||||
mypy python/
|
||||
|
||||
# Run linter
|
||||
pylint python/
|
||||
```
|
||||
|
||||
**Python Style Guidelines:**
|
||||
- Use type hints for all function signatures
|
||||
- Use pathlib.Path for file paths (not os.path)
|
||||
- Use descriptive variable names
|
||||
- Add docstrings to all public functions/classes
|
||||
- Follow PEP 8
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
from pathlib import Path
|
||||
from typing import List, Optional
|
||||
|
||||
def find_kicad_libraries(search_path: Path) -> List[Path]:
|
||||
"""
|
||||
Find all KiCAD symbol libraries in the given path.
|
||||
|
||||
Args:
|
||||
search_path: Directory to search for .kicad_sym files
|
||||
|
||||
Returns:
|
||||
List of paths to found library files
|
||||
|
||||
Raises:
|
||||
ValueError: If search_path doesn't exist
|
||||
"""
|
||||
if not search_path.exists():
|
||||
raise ValueError(f"Search path does not exist: {search_path}")
|
||||
|
||||
return list(search_path.glob("**/*.kicad_sym"))
|
||||
```
|
||||
|
||||
### TypeScript
|
||||
|
||||
We use **ESLint** and **Prettier** for TypeScript.
|
||||
|
||||
```bash
|
||||
# Format TypeScript files
|
||||
npx prettier --write "src/**/*.ts"
|
||||
|
||||
# Run linter
|
||||
npx eslint src/
|
||||
```
|
||||
|
||||
**TypeScript Style Guidelines:**
|
||||
- Use interfaces for data structures
|
||||
- Use async/await for asynchronous code
|
||||
- Use descriptive variable names
|
||||
- Add JSDoc comments to exported functions
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Update Documentation** - If you change functionality, update docs
|
||||
2. **Add Tests** - All new features should have tests
|
||||
3. **Run CI Locally** - Ensure all tests pass before pushing
|
||||
4. **Create PR** - Use a clear, descriptive title
|
||||
5. **Request Review** - Tag relevant maintainers
|
||||
6. **Address Feedback** - Make requested changes
|
||||
7. **Merge** - Maintainer will merge when approved
|
||||
|
||||
### PR Checklist
|
||||
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] All tests pass locally
|
||||
- [ ] New tests added for new features
|
||||
- [ ] Documentation updated
|
||||
- [ ] Commit messages follow convention
|
||||
- [ ] No merge conflicts
|
||||
- [ ] CI/CD pipeline passes
|
||||
|
||||
---
|
||||
|
||||
## Roadmap & Planning
|
||||
|
||||
We track work using GitHub Projects and Issues:
|
||||
|
||||
- **GitHub Projects** - High-level roadmap and sprints
|
||||
- **GitHub Issues** - Specific bugs and features
|
||||
- **GitHub Discussions** - Design discussions and proposals
|
||||
|
||||
### Current Priorities (Week 1-4)
|
||||
|
||||
1. ✅ Linux compatibility fixes
|
||||
2. ✅ Platform-agnostic path handling
|
||||
3. ✅ CI/CD pipeline setup
|
||||
4. 🔄 Migrate to KiCAD IPC API
|
||||
5. ⏳ Add JLCPCB integration
|
||||
6. ⏳ Add Digikey integration
|
||||
|
||||
See [docs/REBUILD_PLAN.md](docs/REBUILD_PLAN.md) for the complete 12-week roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **GitHub Discussions** - Ask questions, propose ideas
|
||||
- **GitHub Issues** - Report bugs, request features
|
||||
- **Discord** - Real-time chat (link TBD)
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
|
||||
---
|
||||
|
||||
## Thank You! 🎉
|
||||
|
||||
Your contributions make this project better for everyone. We appreciate your time and effort!
|
||||
Reference in New Issue
Block a user