Skip to content

Commit 49615f8

Browse files
gonzalocasasgonzalocasas
authored
Merge pull request #21 from compas-dev/copilot/fix-20
Add comprehensive .github/copilot-instructions.md for development workflow guidance
2 parents c8d09c4 + f2bf9b6 commit 49615f8

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# COMPAS EVE
2+
Event-based communication framework for the COMPAS ecosystem, providing publisher/subscriber messaging with support for in-memory, MQTT, and Rhino/Grasshopper integrations.
3+
4+
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.
5+
6+
## Working Effectively
7+
- Bootstrap and install development dependencies:
8+
- `pip install -e .[dev]` -- installs all dev tools and the package in editable mode. Takes ~60 seconds with good network.
9+
- **NOTE**: May fail in environments with restricted network access. If pip times out, dependencies may need manual installation.
10+
- **NEVER CANCEL**: Set timeout to 300+ seconds for dependency installation in case of slow network.
11+
- `invoke clean` -- clean all generated artifacts. Takes ~1 second.
12+
- `invoke lint` -- run flake8 and black linters. Takes ~1 second.
13+
- `invoke format` -- reformat code with black. Takes ~1 second.
14+
- `invoke check` -- comprehensive style and metadata checks. Takes ~2 seconds.
15+
- `invoke docs` -- build HTML documentation with Sphinx. Takes ~7 seconds.
16+
- **Unit tests only**: `pytest tests/unit` -- run core unit tests. Takes ~0.5 seconds.
17+
- **Full tests**: `invoke test` or `pytest` -- runs ALL tests including integration tests. Integration tests will FAIL without MQTT broker setup.
18+
19+
## Testing Requirements
20+
- **Unit tests**: Work immediately after installation. Test core event messaging functionality.
21+
- **Integration tests**: Require MQTT broker running on localhost:1883.
22+
- Set up MQTT broker: `docker run -d --name nanomq -p 1883:1883 emqx/nanomq:latest`
23+
- **IMPORTANT**: Change `HOST = "broker.hivemq.com"` to `HOST = "localhost"` in `tests/integration/test_mqtt.py`
24+
- Run tests: `pytest tests/integration` -- takes ~4 seconds with local broker
25+
- Clean up: `docker rm -f nanomq`
26+
- Integration tests validate MQTT transport functionality
27+
- **NEVER CANCEL**: Integration tests may take 5+ seconds to start broker and run tests.
28+
29+
## Validation
30+
- Always run `invoke clean && invoke lint && invoke format && invoke check` before committing changes.
31+
- **VALIDATION SCENARIOS**: Test basic functionality after changes:
32+
- `python -m compas_eve` -- should print "COMPAS EVE v1.0.0 is installed!"
33+
- `python docs/examples/01_hello_world.py` -- should print publisher/subscriber message exchange
34+
- Always manually test examples in `docs/examples/` when changing core functionality.
35+
- The CI will run tests on Windows, macOS, Linux with Python 3.9, 3.10, 3.11 AND IronPython 2.7.
36+
37+
## Installation & Dependencies
38+
- **Python Requirements**: Python 3.8+ (supports CPython and IronPython)
39+
- **Core Dependencies**: compas>=1.17.6, paho-mqtt
40+
- **Development Tools**: invoke, pytest, black, flake8, sphinx
41+
- **Development Installation**: `pip install -e .[dev]` (installs package in editable mode)
42+
43+
## Code Style & Documentation
44+
- **Docstring Style**: Use numpy-style docstrings for all functions, classes, and methods
45+
- **Code Formatting**: Use `invoke format` to automatically format code with black
46+
- **Linting**: Use `invoke lint` to check code style with flake8 and black
47+
- **Type Hints**: Include type hints where appropriate for better code clarity
48+
49+
## Build System
50+
- Uses **setuptools** with `setup.py` and modern `pyproject.toml`
51+
- **invoke** task runner for automation (replaces Make/scripts)
52+
- **pytest** for testing with doctest integration
53+
- **Sphinx** for documentation with `sphinx_compas2_theme`
54+
- No compiled components - pure Python package
55+
56+
## Common Tasks
57+
The following are outputs from frequently run commands. Reference them instead of running bash commands to save time.
58+
59+
### Repository root structure
60+
```
61+
├── .github/ # GitHub Actions workflows
62+
├── docs/ # Sphinx documentation
63+
├── src/compas_eve/ # Main package source
64+
│ ├── core.py # Core messaging classes
65+
│ ├── memory/ # In-memory transport
66+
│ ├── mqtt/ # MQTT transport
67+
│ ├── ghpython/ # Grasshopper components (not used in CI)
68+
│ └── rhino/ # Rhino integration (not used in CI)
69+
├── tests/
70+
│ ├── unit/ # Fast unit tests (no external deps)
71+
│ └── integration/ # MQTT integration tests
72+
├── requirements.txt # Runtime dependencies
73+
├── requirements-dev.txt # Development dependencies
74+
├── setup.py # Package configuration
75+
├── pyproject.toml # Modern Python project config
76+
└── tasks.py # Invoke task definitions
77+
```
78+
79+
### Key source files
80+
- `src/compas_eve/core.py` -- Main Message, Publisher, Subscriber, Topic classes
81+
- `src/compas_eve/memory/` -- InMemoryTransport for single-process messaging
82+
- `src/compas_eve/mqtt/` -- MqttTransport for distributed messaging
83+
- `src/compas_eve/ghpython/` -- Grasshopper background task components (not used in CI)
84+
- `tests/unit/test_core.py` -- Core functionality unit tests
85+
- `tests/integration/test_mqtt.py` -- MQTT transport integration tests
86+
87+
### Package imports and usage
88+
```python
89+
import compas_eve as eve
90+
91+
# In-memory messaging (default)
92+
pub = eve.Publisher("/topic")
93+
sub = eve.EchoSubscriber("/topic")
94+
sub.subscribe()
95+
pub.publish({"message": "hello"})
96+
97+
# MQTT messaging
98+
from compas_eve.mqtt import MqttTransport
99+
eve.set_default_transport(MqttTransport("broker.hivemq.com"))
100+
```
101+
102+
## Special Features
103+
- **Multiple Transports**: In-memory (default), MQTT for distributed systems
104+
- **IronPython Support**: Full compatibility with IronPython 2.7 for legacy environments
105+
- **Cross-platform**: Windows, macOS, Linux support
106+
107+
## Timing Expectations
108+
- Package installation: ~60 seconds with good network, may timeout in restricted environments (**NEVER CANCEL** - set 300+ second timeout)
109+
- Unit tests: ~0.5 seconds
110+
- Integration tests: ~4 seconds (including MQTT broker communication)
111+
- Linting/formatting: ~1 second each
112+
- Documentation build: ~7 seconds
113+
- **NEVER CANCEL any build or test commands** - they are generally fast but may have network or startup overhead
114+
115+
## CI/CD Integration
116+
- GitHub Actions workflows in `.github/workflows/`
117+
- Tests run on multiple OS/Python combinations
118+
- **Always run** `invoke lint` before pushing - CI enforces code style
119+
- Uses `compas-dev/compas-actions.build@v4` for standard COMPAS project workflows

0 commit comments

Comments
 (0)