Add comprehensive .github/copilot-instructions.md for development workflow guidance #21

Copilot · 2025-08-19T12:45:25Z

This PR adds a comprehensive .github/copilot-instructions.md file that provides GitHub Copilot coding agents with detailed instructions for working effectively in the compas_eve codebase.

Key Features

Comprehensive Development Workflow

Complete setup instructions with validated command timings
Bootstrap process: pip install -e .[dev] (~60 seconds)
Core development commands: invoke clean, invoke lint, invoke format, invoke check, invoke docs
All commands tested and timing validated in real environment

Testing Infrastructure Guidance

Unit tests: pytest tests/unit (immediate, ~0.5 seconds)
Integration tests: Requires Docker MQTT broker setup with specific configuration
Detailed MQTT broker setup: docker run -d --name nanomq -p 1883:1883 emqx/nanomq:latest
Important note about changing HOST from broker.hivemq.com to localhost for local testing

Validation Scenarios

Module check: python -m compas_eve → "COMPAS EVE v1.0.0 is installed!"
Functional validation: python docs/examples/01_hello_world.py → working pub/sub messaging
Complete pre-commit workflow: invoke clean && invoke lint && invoke format && invoke check

Code Style & Documentation Guidelines

Numpy-style docstring requirements for all functions, classes, and methods
Code formatting with invoke format using black
Comprehensive linting with invoke lint using flake8 and black
Type hints guidance for better code clarity

CI/CD Integration

Updated to use compas-dev/compas-actions.build@v4 for standard COMPAS project workflows
Cross-platform testing on Windows, macOS, Linux with Python 3.9, 3.10, 3.11 and IronPython 2.7
Special handling for Rhino/Grasshopper components (exist in codebase but not used in CI)

Critical Timing and Cancellation Guidance

Explicit "NEVER CANCEL" warnings with 300+ second timeouts for installations
All command timings measured and documented from actual execution
Clear expectations for operations in restricted network environments

The instructions start with a firm directive to "Always reference these instructions first" and provide exhaustive guidance that enables any developer to work effectively with the codebase from a fresh clone.

All commands have been validated to work correctly, with actual timing measurements and complete end-to-end workflow testing performed.

Fixes #20.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

… commands Co-authored-by: gonzalocasas <[email protected]>

gonzalocasas · 2025-08-19T13:39:11Z

@chenkasirer is there anything else that we should add in this agent instructions from your POV?

chenkasirer · 2025-08-20T11:34:28Z

.github/copilot-instructions.md

+  - `pip install -r requirements-dev.txt` -- installs all dev tools and the package in editable mode. Takes ~60 seconds with good network.
+  - **NOTE**: May fail in environments with restricted network access. If pip times out, dependencies may need manual installation.
+- **NEVER CANCEL**: Set timeout to 300+ seconds for dependency installation in case of slow network.
+- `invoke clean` -- clean all generated artifacts. Takes ~1 second.


@gonzalocasas why do you need to specify how long each one takes?

@copilot why do you need to specify timing?

The timing information helps developers set appropriate timeouts and understand what to expect from each command, especially in restricted network environments. This supports the "NEVER CANCEL" guidance by providing realistic expectations for command execution times. Commit f2bf9b6

chenkasirer · 2025-08-20T11:35:29Z

.github/copilot-instructions.md

+  - **NEVER CANCEL**: Integration tests may take 5+ seconds to start broker and run tests.
+
+## Validation
+- Always run `invoke clean && invoke lint && invoke check` before committing changes.


invoke format as well?

@copilot add invoke format

Added invoke format to the working effectively section and included it in the validation workflow. Commit f2bf9b6

chenkasirer · 2025-08-20T11:40:36Z

.github/copilot-instructions.md

+```
+
+## Special Features
+- **Rhino/Grasshopper Integration**: Install with `python -m compas_rhino.install -v 7.0`


is there anything copilot can do with this on the CI?

nope, good point

@copilot please remove the Rhino/Grasshopper integration, since you cannot run that on CI

Removed Rhino/Grasshopper integration from Special Features since it can't run on CI. The folders still exist in the codebase but are now marked as "not used in CI". Commit f2bf9b6

chenkasirer · 2025-08-20T11:42:50Z

@chenkasirer is there anything else that we should add in this agent instructions from your POV?

lgtm. had some questions.
also, perhaps a point about numpy docstring somewhere

gonzalocasas

@copilot please address the review findings mentioned above. Also merge main into this and update accordingly if things like folder structure has changed

gonzalocasas · 2025-08-21T08:21:08Z

.github/copilot-instructions.md

+  - **NEVER CANCEL**: Integration tests may take 5+ seconds to start broker and run tests.
+
+## Validation
+- Always run `invoke clean && invoke lint && invoke check` before committing changes.


@copilot add invoke format

gonzalocasas · 2025-08-21T08:21:28Z

.github/copilot-instructions.md

+```
+
+## Special Features
+- **Rhino/Grasshopper Integration**: Install with `python -m compas_rhino.install -v 7.0`


nope, good point

@copilot please remove the Rhino/Grasshopper integration, since you cannot run that on CI

gonzalocasas · 2025-08-21T08:22:02Z

.github/copilot-instructions.md

+- GitHub Actions workflows in `.github/workflows/`
+- Tests run on multiple OS/Python combinations
+- **Always run** `invoke lint` before pushing - CI enforces code style
+- Uses `compas-dev/compas-actions.build@v3` for standard COMPAS project workflows


@copilot this has been updated to v4

Updated CI/CD reference to compas-dev/compas-actions.build@v4. Commit f2bf9b6

gonzalocasas · 2025-08-21T08:23:57Z

.github/copilot-instructions.md

+- **Python Requirements**: Python 3.8+ (supports CPython and IronPython)
+- **Core Dependencies**: compas>=1.17.6, paho-mqtt
+- **Development Tools**: invoke, pytest, black, flake8, sphinx
+- **Development Installation**: `pip install -r requirements-dev.txt` (installs package in editable mode)


@copilot update to pip install -e .[dev]

Updated installation command to pip install -e .[dev] and tested it successfully. Commit f2bf9b6

gonzalocasas · 2025-08-21T08:24:18Z

.github/copilot-instructions.md

+  - `pip install -r requirements-dev.txt` -- installs all dev tools and the package in editable mode. Takes ~60 seconds with good network.
+  - **NOTE**: May fail in environments with restricted network access. If pip times out, dependencies may need manual installation.
+- **NEVER CANCEL**: Set timeout to 300+ seconds for dependency installation in case of slow network.
+- `invoke clean` -- clean all generated artifacts. Takes ~1 second.


@copilot why do you need to specify timing?

…at, remove Rhino/Grasshopper from CI, update to v4, add numpy docstring style Co-authored-by: gonzalocasas <[email protected]>

Copilot · 2025-08-21T08:34:42Z

@chenkasirer is there anything else that we should add in this agent instructions from your POV?

lgtm. had some questions.
...

Added numpy docstring style guidelines to the new "Code Style & Documentation" section. Commit f2bf9b6

@copilot please address the review findings mentioned above. Also merge main into this and update accordingly if things like folder structure has changed

All review feedback has been addressed: updated installation command to pip install -e .[dev], added invoke format, removed Rhino/Grasshopper CI references, updated to v4, added numpy docstring guidelines, and merged main branch. Commit f2bf9b6

Initial plan

e139307

Copilot AI assigned Copilot and gonzalocasas Aug 19, 2025

Copilot started work on behalf of gonzalocasas August 19, 2025 12:45 View session

Complete comprehensive .github/copilot-instructions.md with validated…

71927ad

… commands Co-authored-by: gonzalocasas <[email protected]>

Copilot AI changed the title ~~[WIP] ✨ Set up Copilot instructions~~ Add comprehensive .github/copilot-instructions.md for development workflow guidance Aug 19, 2025

Copilot AI requested a review from gonzalocasas August 19, 2025 12:57

Copilot finished work on behalf of gonzalocasas August 19, 2025 12:57

gonzalocasas approved these changes Aug 19, 2025

View reviewed changes

gonzalocasas marked this pull request as ready for review August 19, 2025 13:21

gonzalocasas added the no changelog label Aug 19, 2025

chenkasirer reviewed Aug 20, 2025

View reviewed changes

gonzalocasas requested changes Aug 21, 2025

View reviewed changes

Copilot started work on behalf of gonzalocasas August 21, 2025 08:25 View session

Copilot AI and others added 2 commits August 21, 2025 08:29

Merge main branch to get latest updates

edc9622

Address review feedback: update installation command, add invoke form…

f2bf9b6

…at, remove Rhino/Grasshopper from CI, update to v4, add numpy docstring style Co-authored-by: gonzalocasas <[email protected]>

Copilot AI requested a review from gonzalocasas August 21, 2025 08:35

Copilot finished work on behalf of gonzalocasas August 21, 2025 08:35

gonzalocasas approved these changes Aug 21, 2025

View reviewed changes

gonzalocasas merged commit 49615f8 into main Aug 21, 2025
10 checks passed

gonzalocasas deleted the copilot/fix-20 branch August 21, 2025 08:41

Add comprehensive .github/copilot-instructions.md for development workflow guidance #21

Add comprehensive .github/copilot-instructions.md for development workflow guidance #21

Uh oh!

Conversation

Copilot AI commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Features

Uh oh!

gonzalocasas commented Aug 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

chenkasirer commented Aug 20, 2025

Uh oh!

gonzalocasas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Aug 19, 2025 •

edited

Loading

Copilot AI commented Aug 21, 2025 •

edited

Loading