Enhance GitHub Copilot instructions with django-dbbackup best practices

Co-authored-by: Archmonger <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -4,6 +4,10 @@ ReactPy is a Python library for building user interfaces without JavaScript. It
 
 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.
 
+**IMPORTANT**: This package uses modern Python tooling with Hatch for all development workflows. Always use Hatch commands for development tasks.
+
+**BUG INVESTIGATION**: When investigating whether a bug was already resolved in a previous version, always prioritize searching through `docs/source/about/changelog.rst` first before using Git history. Only search through Git history when no relevant changelog entries are found.
+
 ## Working Effectively
 
 ### Bootstrap, Build, and Test the Repository
@@ -40,7 +44,8 @@ pip install flask sanic tornado
 - `hatch build --clean` -- takes 10 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
 
 **Run Python Tests:**
-- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite.
+- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite. **All tests must always pass - failures are never expected or allowed.**
+- `hatch test --cover` -- run tests with coverage reporting (used in CI)
 - `hatch test -k test_name` -- run specific tests
 - `hatch test tests/test_config.py` -- run specific test files
 - Note: Some tests require Playwright browser automation and may fail in headless environments
@@ -57,6 +62,11 @@ pip install flask sanic tornado
 - `hatch run javascript:fix` -- Format JavaScript code
 - `hatch run javascript:test` -- Run JavaScript tests (note: may fail in headless environments due to DOM dependencies)
 
+**Interactive Development Shell:**
+- `hatch shell` -- Enter an interactive shell environment with all dependencies installed
+- `hatch shell default` -- Enter the default development environment
+- Use the shell for interactive debugging and development tasks
+
 ## Validation
 
 Always manually validate any new code changes through these steps:
@@ -125,39 +135,44 @@ print(f"✓ Hook-based component: {type(counter)}")
 ```
 
 **Always run these validation steps before completing work:**
-- `hatch fmt --check` -- Ensure code is properly formatted
-- `hatch run python:type_check` -- Ensure no type errors  
-- `hatch run javascript:check` -- Ensure JavaScript passes linting
+- `hatch fmt --check` -- Ensure code is properly formatted (never expected to fail)
+- `hatch run python:type_check` -- Ensure no type errors (never expected to fail)
+- `hatch run javascript:check` -- Ensure JavaScript passes linting (never expected to fail)
 - Test basic component creation and rendering as shown above
 - Test server creation if working on server-related features
+- Run relevant tests with `hatch test` -- **All tests must always pass - failures are never expected or allowed**
 
 **Integration Testing:**
 - ReactPy can be deployed with FastAPI, Flask, Sanic, Tornado via ASGI
 - For browser testing, Playwright is used but requires additional setup
 - Test component VDOM rendering directly when browser testing isn't available
 - Validate that JavaScript builds are included in Python package after changes
 
-## Repository Structure
+## Repository Structure and Navigation
 
 ### Key Directories:
 - `src/reactpy/` -- Main Python package source code
+  - `core/` -- Core ReactPy functionality (components, hooks, VDOM)
+  - `web/` -- Web module management and exports
+  - `executors/` -- Server integration modules (ASGI, etc.)
+  - `testing/` -- Testing utilities and fixtures
+  - `pyscript/` -- PyScript integration
+  - `static/` -- Bundled JavaScript files
+  - `_html.py` -- HTML element factory functions
 - `src/js/` -- JavaScript packages that get bundled with Python
+  - `packages/event-to-object/` -- Event serialization package
+  - `packages/@reactpy/client/` -- Client-side React integration
+  - `packages/@reactpy/app/` -- Application framework
 - `src/build_scripts/` -- Build automation scripts
-- `tests/` -- Python test suite
-- `docs/` -- Documentation source (currently transitioning to MkDocs)
+- `tests/` -- Python test suite with comprehensive coverage
+- `docs/` -- Documentation source (MkDocs-based, transitioning setup)
 
 ### Important Files:
-- `pyproject.toml` -- Python project configuration and build scripts
+- `pyproject.toml` -- Python project configuration and Hatch environments
 - `src/js/package.json` -- JavaScript development dependencies
-- `src/js/packages/` -- Individual JavaScript packages
 - `tests/conftest.py` -- Test configuration and fixtures
-
-### Key Components:
-- `src/reactpy/core/` -- Core ReactPy functionality (components, hooks, VDOM)
-- `src/reactpy/web/` -- Web module management and exports
-- `src/reactpy/widgets/` -- Built-in UI components
-- `src/reactpy/pyscript/` -- PyScript integration
-- `src/reactpy/_html.py` -- HTML element factory functions
+- `docs/source/about/changelog.rst` -- Version history and changes
+- `.github/workflows/check.yml` -- CI/CD pipeline configuration
 
 ## Common Tasks
 
@@ -169,14 +184,6 @@ print(f"✓ Hook-based component: {type(counter)}")
 - Type checking: 10 seconds
 - Full CI pipeline: 5-10 minutes
 
-### Development Workflow:
-1. Make code changes
-2. Run `hatch fmt` to format code (~1 second)
-3. Run `hatch run python:type_check` for type checking (~10 seconds)
-4. Run `hatch run javascript:check` if JavaScript was modified (~10 seconds)
-5. Run relevant tests with `hatch test`
-6. Validate component functionality manually using validation tests above
-
 ### Running ReactPy Applications:
 
 **ASGI Standalone (Recommended):**
@@ -229,6 +236,60 @@ def my_component(initial_value=0):
 - Built JavaScript gets bundled into `src/reactpy/static/`
 - Always rebuild JavaScript after changes: `hatch run javascript:build`
 
+## Common Hatch Commands
+
+The following are key commands for daily development:
+
+### Development Commands
+```bash
+hatch test                          # Run all tests (**All tests must always pass**)
+hatch test --cover                  # Run tests with coverage (used in CI)
+hatch test -k test_name             # Run specific tests
+hatch fmt                           # Format code with all formatters
+hatch fmt --check                   # Check formatting without changes
+hatch run python:type_check         # Run Python type checker
+hatch run javascript:build          # Build JavaScript packages (15 seconds)
+hatch run javascript:check          # Lint JavaScript code (10 seconds)
+hatch run javascript:fix            # Format JavaScript code
+hatch build --clean                 # Build Python package (10 seconds)
+```
+
+### Environment Management
+```bash
+hatch env show                      # Show all environments
+hatch shell                         # Enter default shell
+hatch shell default                 # Enter development shell
+```
+
+### Build Timing Expectations
+- **NEVER CANCEL**: All commands complete within 60 seconds in normal operation
+- **JavaScript build**: 15 seconds (hatch run javascript:build)
+- **Python package build**: 10 seconds (hatch build --clean)
+- **Python linting**: 1 second (hatch fmt)
+- **JavaScript linting**: 10 seconds (hatch run javascript:check)
+- **Type checking**: 10 seconds (hatch run python:type_check)
+- **Unit tests**: 10-30 seconds (varies by test selection)
+- **Full CI pipeline**: 5-10 minutes
+
+## Development Workflow
+
+Follow this step-by-step process for effective development:
+
+1. **Bootstrap environment**: Ensure you have Python 3.9+ and run `pip install hatch`
+2. **Make your changes** to the codebase
+3. **Run formatting**: `hatch fmt` to format code (~1 second)
+4. **Run type checking**: `hatch run python:type_check` for type checking (~10 seconds)
+5. **Run JavaScript linting** (if JavaScript was modified): `hatch run javascript:check` (~10 seconds)
+6. **Run relevant tests**: `hatch test` with specific test selection if needed. **All tests must always pass - failures are never expected or allowed.**
+7. **Validate component functionality** manually using validation tests above
+8. **Build JavaScript** (if modified): `hatch run javascript:build` (~15 seconds)
+9. **Update documentation** when making changes to Python source code (required)
+10. **Add changelog entry** for all significant changes to `docs/source/about/changelog.rst`
+
+**IMPORTANT**: Documentation must be updated whenever changes are made to Python source code. This is enforced as part of the development workflow.
+
+**IMPORTANT**: Significant changes must always include a changelog entry in `docs/source/about/changelog.rst` under the appropriate version section.
+
 ## Troubleshooting
 
 ### Build Issues:
@@ -255,14 +316,53 @@ def my_component(initial_value=0):
 - For Flask integration: `pip install flask` (requires additional backend package)
 - For development servers, use ReactPy ASGI standalone for simplest setup
 
+## Package Dependencies
+
+Modern dependency management via pyproject.toml:
+
+**Core Runtime Dependencies:**
+- `fastjsonschema >=2.14.5` -- JSON schema validation
+- `requests >=2` -- HTTP client library  
+- `lxml >=4` -- XML/HTML processing
+- `anyio >=3` -- Async I/O abstraction
+- `typing-extensions >=3.10` -- Type hints backport
+
+**Optional Dependencies (install via extras):**
+- `asgi` -- ASGI server support: `orjson`, `asgiref`, `asgi-tools`, `servestatic`, `pip`
+- `jinja` -- Template integration: `jinja2-simple-tags`, `jinja2 >=3`
+- `uvicorn` -- ASGI server: `uvicorn[standard]`
+- `testing` -- Browser automation: `playwright`
+- `all` -- All optional dependencies combined
+
+**Development Dependencies (managed by Hatch):**
+- **JavaScript tooling**: Bun runtime for building packages
+- **Python tooling**: Hatch environments handle all dev dependencies automatically
+
 ## CI/CD Information
 
 The repository uses GitHub Actions with these key jobs:
-- `test-python-coverage` -- Python test coverage
-- `lint-python` -- Python linting and type checking
-- `test-python` -- Cross-platform Python testing
+- `test-python-coverage` -- Python test coverage with `hatch test --cover`
+- `lint-python` -- Python linting and type checking via `hatch fmt --check` and `hatch run python:type_check`
+- `test-python` -- Cross-platform Python testing across Python 3.10-3.13 and Ubuntu/macOS/Windows
 - `lint-javascript` -- JavaScript linting and type checking
 
 The CI workflow is defined in `.github/workflows/check.yml` and uses the reusable workflow in `.github/workflows/.hatch-run.yml`.
 
-Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
+**Build Matrix:**
+- **Python versions**: 3.10, 3.11, 3.12, 3.13
+- **Operating systems**: Ubuntu, macOS, Windows
+- **Test execution**: Hatch-managed environments ensure consistency across platforms
+
+Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
+
+## Important Notes
+
+- **This is a Python-to-JavaScript bridge library**, not a traditional web framework - it enables React-like components in Python
+- **Component rendering uses VDOM** - components return virtual DOM objects that get serialized to JavaScript
+- **All builds and tests run quickly** - if something takes more than 60 seconds, investigate the issue
+- **Hatch environments provide full isolation** - no need to manage virtual environments manually  
+- **JavaScript packages are bundled into Python** - the build process combines JS and Python into a single distribution
+- **Browser automation tests may fail in headless environments** - this is expected behavior for Playwright tests
+- **Documentation updates are required** when making changes to Python source code
+- **Always update this file** when making changes to the development workflow, build process, or repository structure
+- **All tests must always pass** - failures are never expected or allowed in a healthy development environment