Skip to content

Commit a418ea4

Browse files
CopilotCopilot
authored
Add comprehensive GitHub Copilot instructions and linting requirements for python-matter-server development (#1231)
1 parent 7624ea2 commit a418ea4

File tree

1 file changed

+252
-0
lines changed

1 file changed

+252
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Python Matter Server
2+
3+
Python Matter Server is an officially certified Software Component that provides Matter controller support. It serves as the foundation for Matter support in Home Assistant and other projects. The server implements a Matter Controller over WebSockets using the official Matter SDK.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Setup
10+
- **CRITICAL**: Matter Server requires Linux or macOS with specific IPv6 networking configuration. Windows/WSL is NOT supported.
11+
- Set up the complete development environment:
12+
```bash
13+
scripts/setup.sh
14+
```
15+
- Creates Python virtual environment in `.venv/`
16+
- Installs Python dependencies including Matter SDK components
17+
- Installs pre-commit hooks for code quality
18+
- **TIMING**: Typically takes 3-5 minutes. NEVER CANCEL - wait up to 10 minutes for completion.
19+
- **NETWORK ISSUE**: If pip install fails with timeout errors (common with Matter SDK dependencies), this is due to network limitations, not code issues.
20+
21+
### Python Server Development
22+
- **Always run the bootstrapping steps first before any Python development**
23+
- Start the Matter server:
24+
```bash
25+
# Basic server (info log level)
26+
python -m matter_server.server
27+
28+
# Debug mode
29+
python -m matter_server.server --log-level debug
30+
31+
# SDK debug mode
32+
python -m matter_server.server --log-level-sdk progress
33+
```
34+
- Create `/data` directory with proper permissions if it doesn't exist
35+
- Server runs on port 5580 by default (WebSocket endpoint)
36+
- Alternative entry point: `python main.py`
37+
38+
### Dashboard Development
39+
- **Dashboard setup** (requires Python dependencies to be available):
40+
```bash
41+
cd dashboard
42+
script/setup
43+
```
44+
- Runs `npm install` (~15 seconds)
45+
- Generates descriptions file from Python source
46+
- **TIMING**: ~30 seconds total. NEVER CANCEL - set timeout to 2+ minutes.
47+
48+
- **Development server**:
49+
```bash
50+
cd dashboard
51+
script/develop
52+
```
53+
- Starts TypeScript compiler in watch mode
54+
- Starts development server on http://localhost:5010
55+
- Live reload for development changes
56+
- **TIMING**: Starts in ~5 seconds
57+
58+
- **Production build**:
59+
```bash
60+
cd dashboard
61+
script/build
62+
```
63+
- Builds optimized TypeScript/JavaScript bundle
64+
- Copies build to `matter_server/dashboard/` directory
65+
- **TIMING**: ~10 seconds. NEVER CANCEL - set timeout to 2+ minutes.
66+
67+
### Testing and Code Quality
68+
- **Run complete test suite**:
69+
```bash
70+
scripts/run-in-env.sh pytest --durations 10 --cov-report term-missing --cov=matter_server --cov-report=xml tests/
71+
```
72+
- **TIMING**: Typically 2-3 minutes. NEVER CANCEL - set timeout to 10+ minutes.
73+
74+
- **Pre-commit validation** (REQUIRED before commits):
75+
```bash
76+
SKIP=no-commit-to-branch pre-commit run --all-files
77+
```
78+
- Runs ruff (linting + formatting), pylint, mypy, codespell, and other checks
79+
- **TIMING**: 1-2 minutes for all files. NEVER CANCEL - set timeout to 5+ minutes.
80+
81+
- **Individual linting tools**:
82+
```bash
83+
scripts/run-in-env.sh ruff check --fix
84+
scripts/run-in-env.sh ruff format
85+
scripts/run-in-env.sh pylint matter_server/ tests/
86+
scripts/run-in-env.sh mypy
87+
```
88+
89+
## Validation Scenarios
90+
91+
**ALWAYS manually validate changes using complete end-to-end scenarios:**
92+
93+
### Python Server Validation
94+
1. Start the server: `python -m matter_server.server --log-level debug`
95+
2. Verify WebSocket endpoint responds (server starts without errors)
96+
3. Check dashboard is accessible if built: verify `matter_server/dashboard/` contains files
97+
4. Test example client: `python scripts/example.py` (requires dependencies)
98+
99+
### Dashboard Validation
100+
1. Build dashboard: `cd dashboard && script/build`
101+
2. Verify build artifacts: check `matter_server/dashboard/js/` contains compiled JavaScript
102+
3. Start development server: `cd dashboard && script/develop`
103+
4. Access http://localhost:5010 and verify dashboard loads
104+
5. Test WebSocket connection input (should prompt for server URL)
105+
106+
### Pre-commit Validation
107+
**CRITICAL**: Always run before pushing changes or CI will fail:
108+
```bash
109+
SKIP=no-commit-to-branch pre-commit run --all-files
110+
```
111+
112+
## Repository Structure
113+
114+
### Key Directories
115+
```
116+
matter_server/ # Main Python package
117+
├── client/ # Matter client library
118+
├── server/ # Matter server implementation
119+
├── common/ # Shared utilities
120+
└── dashboard/ # Built web dashboard (auto-generated)
121+
122+
dashboard/ # Dashboard source code (TypeScript/Lit)
123+
├── src/ # TypeScript source files
124+
├── script/ # Build and development scripts
125+
└── public/ # Static assets
126+
127+
scripts/ # Development utilities
128+
├── setup.sh # Main environment setup
129+
├── example.py # Server/client example
130+
└── generate_descriptions.py # Generates dashboard type definitions
131+
132+
tests/ # Test suite (pytest-based)
133+
docs/ # Documentation
134+
├── os_requirements.md # Operating system setup requirements
135+
├── docker.md # Docker deployment guide
136+
└── websockets_api.md # WebSocket API documentation
137+
```
138+
139+
### Important Files
140+
- `pyproject.toml` - Python packaging and tool configuration
141+
- `main.py` - Alternative server entry point
142+
- `.pre-commit-config.yaml` - Code quality hooks configuration
143+
- `DEVELOPMENT.md` - Detailed development setup guide
144+
145+
## Common Issues and Solutions
146+
147+
### Network Timeouts During Setup
148+
**SYMPTOM**: `pip install` fails with `ReadTimeoutError` from PyPI
149+
**CAUSE**: Matter SDK dependencies are large and can timeout on slow connections
150+
**SOLUTION**:
151+
- Retry setup: `scripts/setup.sh`
152+
- Use `pip install --timeout 300` for extended timeout
153+
- **Document as known issue** if persistent
154+
155+
### IPv6/Networking Issues
156+
**SYMPTOM**: Matter devices not discoverable or connection failures
157+
**REFERENCE**: See `docs/os_requirements.md` for complete networking requirements
158+
**KEY REQUIREMENTS**:
159+
- IPv6 support enabled on host interface
160+
- No multicast filtering on network equipment
161+
- Proper ICMPv6 Router Advertisement processing
162+
- For Thread devices: specific kernel options and sysctl settings
163+
164+
### Pre-commit Hook Failures
165+
**SYMPTOM**: Git commits rejected due to formatting/linting issues
166+
**SOLUTION**:
167+
```bash
168+
SKIP=no-commit-to-branch pre-commit run --all-files
169+
scripts/run-in-env.sh ruff format # Fix formatting
170+
scripts/run-in-env.sh ruff check --fix # Fix linting issues
171+
```
172+
173+
### Dashboard Build Issues
174+
**SYMPTOM**: `script/setup` fails with "No module named 'chip'"
175+
**CAUSE**: Python Matter SDK dependencies not installed
176+
**SOLUTION**: Run `scripts/setup.sh` first to install Python dependencies
177+
178+
## Development Tips
179+
180+
- **Always** activate virtual environment: `source .venv/bin/activate`
181+
- Use `scripts/run-in-env.sh` for consistent tool execution across environments
182+
- Dashboard development can proceed independently once built once
183+
- Server requires `/data` directory for persistent storage
184+
- Matter protocol requires specific OS and network configuration (see `docs/os_requirements.md`)
185+
- Example usage patterns available in `scripts/example.py`
186+
- WebSocket API documentation in `docs/websockets_api.md`
187+
188+
## CI/CD Integration
189+
190+
The project uses GitHub Actions (`.github/workflows/test.yml`):
191+
- Linting: pre-commit hooks on Python 3.12
192+
- Testing: pytest on Python 3.12 and 3.13
193+
- **Always ensure pre-commit passes locally** before pushing to avoid CI failures
194+
195+
## Project Context
196+
197+
This project implements both server and client components:
198+
- **Server**: Runs Matter Controller with WebSocket API
199+
- **Client**: Python library for consuming the WebSocket API (used by Home Assistant)
200+
- **Dashboard**: Web-based debugging and testing interface
201+
- **Architecture**: Allows multiple consumers to connect to same Matter fabric
202+
- **Deployment**: Available as Home Assistant add-on, Docker container, or standalone
203+
204+
The separation enables scenarios where the Matter fabric continues running while consumers (like Home Assistant) restart or disconnect.
205+
206+
## Linting and Code Quality Requirements
207+
208+
**CRITICAL**: All code changes MUST pass linting checks before submitting PRs. The CI will fail if linting issues are present.
209+
210+
### Required Linting Steps Before PR Submission
211+
212+
Always run these commands before committing and pushing changes:
213+
214+
```bash
215+
# Run all pre-commit checks (REQUIRED)
216+
SKIP=no-commit-to-branch pre-commit run --all-files
217+
218+
# Individual linting tools for troubleshooting
219+
scripts/run-in-env.sh ruff check --fix # Fix linting issues
220+
scripts/run-in-env.sh ruff format # Fix formatting
221+
scripts/run-in-env.sh pylint matter_server/ tests/ # Check code quality
222+
scripts/run-in-env.sh mypy # Check type annotations
223+
```
224+
225+
### Linting Tools Used
226+
227+
The project uses multiple linting tools enforced via pre-commit hooks:
228+
229+
- **ruff**: Fast Python linter and formatter (replaces flake8, isort, etc.)
230+
- **pylint**: Static code analysis for code quality
231+
- **mypy**: Static type checking
232+
- **codespell**: Spell checking for code and documentation
233+
- **File format checks**: JSON, TOML validation, trailing whitespace, end-of-file fixers
234+
235+
### Common Linting Failures
236+
237+
**Trailing Whitespace**: Remove all trailing spaces from lines
238+
**Missing Newline**: Ensure files end with a single newline character
239+
**Import Order**: Use `ruff format` to fix import sorting
240+
**Type Annotations**: Add type hints where mypy reports missing annotations
241+
**Spelling**: Use `codespell` to check for typos in code and comments
242+
243+
### Automated Fixing
244+
245+
Most linting issues can be automatically fixed:
246+
247+
```bash
248+
scripts/run-in-env.sh ruff check --fix # Auto-fix many linting issues
249+
scripts/run-in-env.sh ruff format # Auto-format code
250+
```
251+
252+
**Always verify changes after auto-fixing and run the full pre-commit suite before submitting.**

0 commit comments

Comments
 (0)