docs: Refresh .github/copilot-instructions.md with comprehensive repository review

Co-authored-by: ggorman <5394691+ggorman@users.noreply.github.com>

Author: Copilot

.github/copilot-instructions.md

@@ -5,12 +5,13 @@
 Devito is a Python package for implementing optimized stencil computation (finite differences, image processing, machine learning) from high-level symbolic problem definitions. It builds on SymPy and employs automated code generation and just-in-time compilation to execute optimized computational kernels on CPUs, GPUs, and clusters.
 
 **Key Facts:**
-- Production-stable package (Development Status 5) for scientific computing
-- Python 3.10-3.13 support (current development uses 3.12.3)
-- ~50MB repository with extensive test coverage
+- Production-stable package (Development Status :: 5 - Production/Stable)
+- Python 3.10-3.13 support with comprehensive CI testing
+- ~290MB repository with extensive test coverage and benchmarking
 - Primary languages: Python (core), C/C++ (generated code)
 - Main dependencies: NumPy, SymPy, cgen, codepy, psutil
 - Supports multiple compilation backends: C, OpenMP, OpenACC, MPI
+- Active development with 600+ stars, 238+ forks, and regular releases
 
 ## Build and Development Environment
 
@@ -91,16 +92,21 @@ devito/                 # Main source package
 ├── __init__.py        # Package initialization, configuration setup
 ├── arch/              # Architecture-specific compilation backends
 ├── builtins/          # Built-in mathematical functions
+├── checkpointing/     # Checkpointing and reverse-mode functionality
 ├── core/              # Core IR (Intermediate Representation) classes
 ├── data/              # Data structures and memory management
 ├── finite_differences/# Finite difference operators and stencils
 ├── ir/                # Intermediate representation passes
+├── mpatches/          # Memory patches and optimizations
 ├── mpi/               # MPI parallelization support
+├── operations/        # Mathematical operations and transformations
 ├── operator/          # Operator compilation and generation
 ├── passes/            # Compiler optimization passes
 ├── symbolics/         # Symbolic computation utilities
 ├── tools/             # Utility functions and helpers
-└── types/             # Core types (Grid, Function, Equation, etc.)
+├── types/             # Core types (Grid, Function, Equation, etc.)
+├── deprecations.py    # Deprecation warnings and legacy support
+└── warnings.py        # Warning system and configuration
 
 tests/                 # Test suite (comprehensive coverage)
 examples/              # Tutorials and demonstrations
@@ -110,26 +116,35 @@ examples/              # Tutorials and demonstrations
 └── userapi/          # User API demonstrations
 
 scripts/               # Utility scripts
-docker/               # Docker configurations
-benchmarks/           # Performance benchmarks
+docker/               # Docker configurations  
+benchmarks/           # Performance benchmarks and ASV configuration
+binder/               # Jupyter Binder configuration
 ```
 
 ### Key Configuration Files
-- `pyproject.toml`: Build configuration, dependencies, flake8 settings
+- `pyproject.toml`: Build configuration, dependencies, flake8 settings (max-line-length=90)
 - `pytest.ini`: Test configuration and options
-- `requirements*.txt`: Dependency specifications for different environments
-- `environment-dev.yml`: Conda environment specification
-- `.github/workflows/`: CI/CD pipelines
+- `requirements*.txt`: Dependency specifications for different environments (mpi, nvidia, testing, optional)
+- `environment-dev.yml`: Conda environment specification (recommended for development)
+- `.github/workflows/`: CI/CD pipelines (13 comprehensive workflows)
+- `MANIFEST.in`: Package distribution file inclusion/exclusion rules
 
 ## Continuous Integration and Validation
 
 ### GitHub Workflows (All Must Pass)
 1. **pytest-core-nompi.yml**: Core functionality tests across Python 3.10-3.13, multiple GCC versions
-2. **pytest-core-mpi.yml**: MPI parallel execution tests
+2. **pytest-core-mpi.yml**: MPI parallel execution tests  
 3. **pytest-gpu.yml**: GPU computation tests (OpenACC/CUDA)
-4. **flake8.yml**: Code style validation
+4. **flake8.yml**: Code style validation (90-char line limit, specific ignore rules)
 5. **examples.yml**: Integration tests via example execution
-6. **tutorials.yml**: Jupyter notebook validation
+6. **examples-mpi.yml**: MPI-based example validation
+7. **tutorials.yml**: Jupyter notebook validation
+8. **asv.yml**: Performance benchmarking and regression detection
+9. **docker-bases.yml**: Docker base image builds for testing environments
+10. **docker-devito.yml**: Devito-specific Docker image builds
+11. **pythonpublish.yml**: Package publishing to PyPI
+12. **release-notes.yml**: Automated release documentation
+13. **triggers.yml**: Workflow orchestration and triggers
 
 ### Pre-commit Validation Steps
 ```bash
@@ -156,12 +171,38 @@ python examples/seismic/acoustic/acoustic_example.py
 ## Development Guidelines
 
 ### Code Style (Enforced by CI)
-- **Line length**: 90 characters maximum
+- **Line length**: 90 characters maximum (configured in pyproject.toml)
 - **Indentation**: 4 spaces (no tabs)
 - **Imports**: Grouped (stdlib, third-party, devito) and alphabetically sorted
 - **Docstrings**: NumPy-style documentation required for public APIs
 - **Naming**: CamelCase classes, snake_case methods/variables
 
+### Commit Messages and PR Titles
+Use descriptive prefixes to categorize changes (based on recent repository patterns):
+- **compiler:** Changes to compilation system, IR passes, code generation
+- **mpi:** MPI-related functionality and parallel execution
+- **misc:** General improvements, cleanup, modernization
+- **docs:** Documentation updates, docstring fixes
+- **install:** Installation, packaging, dependencies
+- **bug-py:** Python code bug fixes
+- **bug-C:** Generated C code bug fixes
+
+**Examples:**
+- `compiler: Hotfix estimate memory for certain devices`
+- `misc: switch to f-string throughout`
+- `docs: fix mmin/mmax docstring`
+- `install: Remove files and directories not needed for install`
+
+### Common Labels (for PR categorization)
+- **bug-py**, **bug-py-minor**, **bug-C**: Bug fixes by category
+- **compiler**: Compilation system changes
+- **MPI**: MPI and parallel execution
+- **documentation**: Documentation improvements
+- **installation**: Package installation and setup
+- **misc**: General improvements
+- **dependencies**: Dependency updates
+- **python**: Python code changes
+
 ### Making Changes
 1. **Always run linting first**: `flake8 --builtins=ArgumentError .`
 2. **Test specific areas**: Run relevant tests before committing
@@ -170,15 +211,21 @@ python examples/seismic/acoustic/acoustic_example.py
 5. **Examples**: Add/update examples for new features
 
 ### Critical Dependencies
-- **SymPy**: Symbolic mathematics (versions 1.12-1.14 supported)
-- **NumPy**: Numerical arrays (version 2.x)
+- **SymPy**: Symbolic mathematics (versions 1.12+ supported)
+- **NumPy**: Numerical arrays (version 2.x compatible)
 - **cgen/codepy**: C code generation and compilation
 - **psutil**: System monitoring and resource management
+- **setuptools-scm**: Dynamic versioning from git tags
+
+### Flake8 Configuration and Common Workarounds
+The project uses flake8 with specific ignore rules (configured in pyproject.toml):
+- **F403/F405**: Star imports are expected in `__init__.py` files due to API design
+- **E731**: Lambda expressions are acceptable for configuration and simple cases
+- **W503**: Line breaks before binary operators (older style preference)
+- **E722**: Bare except clauses are sometimes necessary for compatibility
+- **W605**: Invalid escape sequences in docstrings (legacy patterns)
 
-### Common Workarounds
-- **Star imports**: F403/F405 warnings are expected in `__init__.py` due to API design
-- **Lambda expressions**: E731 warnings are sometimes acceptable for configuration
-- **Import order**: Follow the pattern in `devito/__init__.py`
+**Import order**: Follow the pattern in `devito/__init__.py` for consistency
 
 ## Agent-Specific Instructions
 
@@ -188,14 +235,18 @@ python examples/seismic/acoustic/acoustic_example.py
 3. Specific error messages require investigation
 
 **Time-saving tips:**
-1. Use Docker if pip installation fails due to network issues
+1. Use Docker if pip installation fails due to network issues  
 2. Set environment variables before running any compilation-dependent tests
-3. Start with small test files when debugging
+3. Start with small test files when debugging (e.g., `pytest tests/test_operator.py::test_specific`)
 4. Check configuration output to verify environment setup
 5. Use `--maxfail=5` to stop test runs early on systematic failures
+6. Use conda environment for full development workflow when possible
+7. Run flake8 first before making commits to catch style issues early
 
 **File modification priorities:**
 1. Core types and operators: `devito/types/`, `devito/operator/`
 2. Mathematical operations: `devito/finite_differences/`, `devito/symbolics/`
 3. Compilation backends: `devito/arch/`, `devito/passes/`
-4. Always update corresponding tests in `tests/`
+4. MPI functionality: `devito/mpi/`
+5. Always update corresponding tests in `tests/`
+6. Update documentation in examples/ if adding new features