Skip to content

Commit 71927ad

Browse files
Copilotgonzalocasas
Copilot
and
gonzalocasas
committed
Complete comprehensive .github/copilot-instructions.md with validated commands
Co-authored-by: gonzalocasas <[email protected]>
1 parent e139307 commit 71927ad

File tree

1 file changed

+115
-0
lines changed

1 file changed

+115
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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 -r requirements-dev.txt` -- 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 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 -r requirements-dev.txt` (installs package in editable mode)
42+
43+
## Build System
44+
- Uses **setuptools** with `setup.py` and modern `pyproject.toml`
45+
- **invoke** task runner for automation (replaces Make/scripts)
46+
- **pytest** for testing with doctest integration
47+
- **Sphinx** for documentation with `sphinx_compas2_theme`
48+
- No compiled components - pure Python package
49+
50+
## Common Tasks
51+
The following are outputs from frequently run commands. Reference them instead of running bash commands to save time.
52+
53+
### Repository root structure
54+
```
55+
├── .github/ # GitHub Actions workflows
56+
├── docs/ # Sphinx documentation
57+
├── src/compas_eve/ # Main package source
58+
│ ├── core.py # Core messaging classes
59+
│ ├── memory/ # In-memory transport
60+
│ ├── mqtt/ # MQTT transport
61+
│ ├── ghpython/ # Grasshopper components
62+
│ └── rhino/ # Rhino integration
63+
├── tests/
64+
│ ├── unit/ # Fast unit tests (no external deps)
65+
│ └── integration/ # MQTT integration tests
66+
├── requirements.txt # Runtime dependencies
67+
├── requirements-dev.txt # Development dependencies
68+
├── setup.py # Package configuration
69+
├── pyproject.toml # Modern Python project config
70+
└── tasks.py # Invoke task definitions
71+
```
72+
73+
### Key source files
74+
- `src/compas_eve/core.py` -- Main Message, Publisher, Subscriber, Topic classes
75+
- `src/compas_eve/memory/` -- InMemoryTransport for single-process messaging
76+
- `src/compas_eve/mqtt/` -- MqttTransport for distributed messaging
77+
- `src/compas_eve/ghpython/` -- Grasshopper background task components
78+
- `tests/unit/test_core.py` -- Core functionality unit tests
79+
- `tests/integration/test_mqtt.py` -- MQTT transport integration tests
80+
81+
### Package imports and usage
82+
```python
83+
import compas_eve as eve
84+
85+
# In-memory messaging (default)
86+
pub = eve.Publisher("/topic")
87+
sub = eve.EchoSubscriber("/topic")
88+
sub.subscribe()
89+
pub.publish({"message": "hello"})
90+
91+
# MQTT messaging
92+
from compas_eve.mqtt import MqttTransport
93+
eve.set_default_transport(MqttTransport("broker.hivemq.com"))
94+
```
95+
96+
## Special Features
97+
- **Rhino/Grasshopper Integration**: Install with `python -m compas_rhino.install -v 7.0`
98+
- **Background Tasks**: Grasshopper components for long-running background operations
99+
- **Multiple Transports**: In-memory (default), MQTT for distributed systems
100+
- **IronPython Support**: Full compatibility with IronPython 2.7 for Rhino
101+
- **Cross-platform**: Windows, macOS, Linux support
102+
103+
## Timing Expectations
104+
- Package installation: ~60 seconds with good network, may timeout in restricted environments (**NEVER CANCEL** - set 300+ second timeout)
105+
- Unit tests: ~0.5 seconds
106+
- Integration tests: ~4 seconds (including MQTT broker communication)
107+
- Linting/formatting: ~1 second each
108+
- Documentation build: ~7 seconds
109+
- **NEVER CANCEL any build or test commands** - they are generally fast but may have network or startup overhead
110+
111+
## CI/CD Integration
112+
- GitHub Actions workflows in `.github/workflows/`
113+
- Tests run on multiple OS/Python combinations
114+
- **Always run** `invoke lint` before pushing - CI enforces code style
115+
- Uses `compas-dev/compas-actions.build@v3` for standard COMPAS project workflows

0 commit comments

Comments
 (0)