Skip to content

Commit 978a0b9

Browse files
SoundBlasterSoundBlaster
authored
Merge pull request #4 from SoundBlaster/feature/P6-T10-github-ci-workflow
Successfully completed P6-T10: Create GitHub CI Workflow
2 parents 052f0fe + 5dc9d24 commit 978a0b9

25 files changed

Lines changed: 1184 additions & 367 deletions

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
## Description
2+
3+
Brief description of the changes in this PR.
4+
5+
## Type of Change
6+
7+
- [ ] Bug fix
8+
- [ ] New feature
9+
- [ ] Documentation update
10+
- [ ] Refactoring
11+
- [ ] CI/CD improvement
12+
13+
## Quality Gates
14+
15+
Before submitting, ensure all quality gates pass:
16+
17+
```bash
18+
make check
19+
```
20+
21+
Or run individually:
22+
- [ ] `make test` - All tests pass with ≥90% coverage
23+
- [ ] `make lint` - No linting errors
24+
- [ ] `make format` - Code is properly formatted
25+
- [ ] `make typecheck` - Type checking passes
26+
- [ ] `make doccheck` - Documentation is synced with DocC (if docs changed)
27+
28+
## Documentation Sync
29+
30+
If you modified files in `docs/`, ensure corresponding DocC files are also updated:
31+
32+
| docs/ file | DocC file |
33+
|------------|-----------|
34+
| `docs/installation.md` | `mcpbridge-wrapper.docc/Installation.md` |
35+
| `docs/cursor-setup.md` | `mcpbridge-wrapper.docc/CursorSetup.md` |
36+
| `docs/claude-setup.md` | `mcpbridge-wrapper.docc/ClaudeCodeSetup.md` |
37+
| `docs/codex-setup.md` | `mcpbridge-wrapper.docc/CodexCLISetup.md` |
38+
| `docs/troubleshooting.md` | `mcpbridge-wrapper.docc/Troubleshooting.md` |
39+
| `docs/architecture.md` | `mcpbridge-wrapper.docc/Architecture.md` |
40+
| `docs/environment-variables.md` | `mcpbridge-wrapper.docc/EnvironmentVariables.md` |
41+
| `README.md` | `mcpbridge-wrapper.docc/mcpbridge-wrapper.md` |
42+
43+
- [ ] Documentation changes are synced with DocC catalog (or N/A)
44+
45+
## Testing
46+
47+
- [ ] Added/updated tests for new functionality
48+
- [ ] All tests pass locally
49+
- [ ] Manually tested the changes
50+
51+
## Checklist
52+
53+
- [ ] Code follows the project's style guidelines
54+
- [ ] Self-review completed
55+
- [ ] Comments added for complex code
56+
- [ ] Documentation updated (if needed)
57+
- [ ] No new warnings generated
58+
- [ ] PR title is descriptive

‎.github/workflows/ci.yml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch: # Allow manual trigger
11+
12+
jobs:
13+
doc-sync:
14+
name: Doc Sync Check
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0 # Need full history for branch comparison
21+
22+
- name: Check DocC sync
23+
run: python scripts/check_doc_sync.py --branch
24+
lint:
25+
name: Lint & Type Check
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout code
30+
uses: actions/checkout@v4
31+
32+
- name: Set up Python
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: "3.11"
36+
37+
- name: Install dependencies
38+
run: |
39+
python -m pip install --upgrade pip
40+
pip install ruff mypy
41+
42+
- name: Run ruff linter
43+
run: ruff check src/
44+
45+
- name: Run ruff formatter check
46+
run: ruff format --check src/ tests/
47+
48+
- name: Run mypy type checker
49+
run: mypy src/
50+
51+
test:
52+
name: Test (Python ${{ matrix.python-version }})
53+
runs-on: ubuntu-latest
54+
strategy:
55+
matrix:
56+
python-version: ["3.9", "3.10", "3.11", "3.12"]
57+
fail-fast: false
58+
59+
steps:
60+
- name: Checkout code
61+
uses: actions/checkout@v4
62+
63+
- name: Set up Python ${{ matrix.python-version }}
64+
uses: actions/setup-python@v5
65+
with:
66+
python-version: ${{ matrix.python-version }}
67+
68+
- name: Install dependencies
69+
run: |
70+
python -m pip install --upgrade pip
71+
pip install -e ".[dev]"
72+
73+
- name: Run tests with coverage
74+
run: |
75+
pytest tests/ -v --cov=src --cov-report=xml --cov-report=term
76+
77+
- name: Upload coverage to Codecov
78+
if: matrix.python-version == '3.11'
79+
uses: codecov/codecov-action@v4
80+
with:
81+
files: ./coverage.xml
82+
fail_ci_if_error: false
83+
verbose: true
84+
85+
build:
86+
name: Build Package
87+
runs-on: ubuntu-latest
88+
89+
steps:
90+
- name: Checkout code
91+
uses: actions/checkout@v4
92+
93+
- name: Set up Python
94+
uses: actions/setup-python@v5
95+
with:
96+
python-version: "3.11"
97+
98+
- name: Install build dependencies
99+
run: |
100+
python -m pip install --upgrade pip
101+
pip install build twine
102+
103+
- name: Build package
104+
run: python -m build
105+
106+
- name: Check package with twine
107+
run: twine check dist/*
108+
109+
- name: Upload build artifacts
110+
uses: actions/upload-artifact@v4
111+
with:
112+
name: dist
113+
path: dist/
114+
retention-days: 7

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,8 @@ Before submitting a PR, ensure:
342342
- Linting passes: `ruff check src/`
343343
- Type checking passes: `mypy src/`
344344

345+
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development setup and quality gate commands.
346+
345347
## References
346348

347349
- [Apple Official Documentation](https://developer.apple.com/documentation/xcode/giving-external-agentic-coding-tools-access-to-xcode)

‎CONTRIBUTING.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Contributing to mcpbridge-wrapper
2+
3+
Thank you for your interest in contributing! This document outlines the development workflow and quality gates.
4+
5+
## Development Setup
6+
7+
```bash
8+
# Clone the repository
9+
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
10+
cd XcodeMCPWrapper
11+
12+
# Install in editable mode with dev dependencies
13+
pip install -e ".[dev]"
14+
```
15+
16+
## Quality Gates
17+
18+
All code must pass the following quality gates before being merged:
19+
20+
### 1. Tests (pytest)
21+
22+
Run all tests with coverage:
23+
24+
```bash
25+
pytest tests/ -v --cov=src --cov-report=term
26+
```
27+
28+
Requirements:
29+
- All tests must pass
30+
- Coverage must remain ≥90%
31+
32+
### 2. Linting (ruff)
33+
34+
Check for code issues:
35+
36+
```bash
37+
ruff check src/ tests/
38+
```
39+
40+
Auto-fix issues where possible:
41+
42+
```bash
43+
ruff check src/ tests/ --fix
44+
```
45+
46+
### 3. Formatting (ruff)
47+
48+
Check code formatting:
49+
50+
```bash
51+
ruff format --check src/ tests/
52+
```
53+
54+
Apply formatting:
55+
56+
```bash
57+
ruff format src/ tests/
58+
```
59+
60+
### 4. Type Checking (mypy)
61+
62+
```bash
63+
mypy src/
64+
```
65+
66+
### 5. Doc Sync Check
67+
68+
Ensure documentation changes are synced with DocC catalog:
69+
70+
```bash
71+
make doccheck
72+
# or
73+
python scripts/check_doc_sync.py
74+
```
75+
76+
This checks that changes to `docs/*.md` files are also reflected in the DocC catalog (`mcpbridge-wrapper.docc/`).
77+
78+
### 6. Build Verification
79+
80+
Ensure the package builds correctly:
81+
82+
```bash
83+
python -m build
84+
twine check dist/*
85+
```
86+
87+
## Quick Check Script
88+
89+
Run all quality gates at once:
90+
91+
```bash
92+
make test && make lint && make typecheck
93+
```
94+
95+
Or use this bash script (save as `check.sh`):
96+
97+
```bash
98+
#!/bin/bash
99+
set -e
100+
101+
echo "=== Running Quality Gates ==="
102+
103+
echo "1. Running tests..."
104+
pytest tests/ -v --cov=src --cov-report=term
105+
106+
echo "2. Running linter..."
107+
ruff check src/ tests/
108+
109+
echo "3. Checking format..."
110+
ruff format --check src/ tests/
111+
112+
echo "4. Running type checker..."
113+
mypy src/
114+
115+
echo "5. Checking doc sync..."
116+
python scripts/check_doc_sync.py
117+
118+
echo "6. Building package..."
119+
python -m build && twine check dist/*
120+
121+
echo "=== All Quality Gates Passed ==="
122+
```
123+
124+
Make it executable and run:
125+
126+
```bash
127+
chmod +x check.sh
128+
./check.sh
129+
```
130+
131+
## Workflow
132+
133+
We follow the [FLOW.md](SPECS/COMMANDS/FLOW.md) workflow:
134+
135+
1. **BRANCH** - Create a feature branch from `main`
136+
2. **SELECT** - Pick a task from the workplan
137+
3. **PLAN** - Create a PRD for the task
138+
4. **EXECUTE** - Implement and run quality gates
139+
5. **ARCHIVE** - Move completed task to archive
140+
141+
## Pull Request Process
142+
143+
1. Create a feature branch: `git checkout -b feature/TASK-ID-description`
144+
2. Make your changes and run quality gates
145+
3. Commit with clear messages
146+
4. Push to your fork
147+
5. Create a Pull Request against `main`
148+
149+
## CI/CD
150+
151+
All PRs trigger GitHub Actions CI which runs:
152+
- Lint & Type Check (Python 3.11)
153+
- Tests (Python 3.9, 3.10, 3.11, 3.12)
154+
- Package Build
155+
156+
See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for details.
157+
158+
## Code Style
159+
160+
- Follow PEP 8 guidelines
161+
- Use type hints where possible
162+
- Write docstrings for public functions
163+
- Keep functions focused and small
164+
165+
## Questions?
166+
167+
Open an issue or check the [troubleshooting guide](docs/troubleshooting.md).

‎Makefile‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Makefile for mcpbridge-wrapper
22

3-
.PHONY: help install test lint format typecheck clean
3+
.PHONY: help install test lint format typecheck doccheck clean
44

55
help:
66
@echo "Available targets:"
@@ -9,7 +9,9 @@ help:
99
@echo " lint - Run ruff linter"
1010
@echo " format - Run ruff formatter"
1111
@echo " typecheck - Run mypy type checker"
12+
@echo " doccheck - Check docs/ are synced with DocC catalog"
1213
@echo " clean - Clean build artifacts"
14+
@echo " check - Run all quality gates (test, lint, format, typecheck, doccheck)"
1315

1416
install:
1517
pip install -e .
@@ -26,6 +28,11 @@ format:
2628
typecheck:
2729
mypy src/
2830

31+
doccheck:
32+
python scripts/check_doc_sync.py
33+
34+
check: test lint format typecheck doccheck
35+
2936
clean:
3037
rm -rf build/ dist/ *.egg-info/
3138
find . -type d -name __pycache__ -exec rm -rf {} +

0 commit comments

Comments
 (0)