Skip to content

copilot-instructions.md

Latest commit

 

History

History
155 lines (123 loc) · 8.5 KB

copilot-instructions.md

File metadata and controls

155 lines (123 loc) · 8.5 KB
Raw

feincms3 - Django CMS Building Toolkit

feincms3 is a Django-based content management system building toolkit that provides tools and building blocks for creating versatile, powerful, and tailor-made CMS solutions for each project.

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.

Working Effectively

Bootstrap and Setup

  • Install dependencies:
    • python -m pip install --upgrade pip tox -- installs build tools. NEVER CANCEL: May take 2-3 minutes.
    • pip install -e '.[all,tests]' -- installs feincms3 in development mode with all optional dependencies and test dependencies. NEVER CANCEL: May take 5-10 minutes.
  • CRITICAL NETWORK ISSUE: pip install commands frequently fail due to network timeouts (ReadTimeoutError from pypi.org). This is an infrastructure limitation, not a code issue. If installations fail:
    • Retry with longer timeout: pip install --timeout=300 <package>
    • Document as "pip install fails due to firewall/network limitations"
    • Continue with code analysis and basic Python validation

Testing

  • CHECK TEST ENVIRONMENTS: tox --listenvs -- shows all available test combinations (verified working)
  • PRIMARY TEST COMMAND: python -m tox -e py312-dj50 -- runs tests with Python 3.12 and Django 5.0. Takes 5-10 minutes. NEVER CANCEL. Set timeout to 15+ minutes.
    • FREQUENT FAILURE: This often fails during dependency installation due to network timeouts. If it fails, note "tox test fails due to network limitations during pip install phase"
  • ALTERNATIVE TEST METHODS (when network issues prevent tox):
    • Basic import validation: python -c "import sys; sys.path.insert(0, '.'); import feincms3; print('Import successful, version:', feincms3.__version__)"
    • Direct Django tests: cd tests && DJANGO_SETTINGS_MODULE=testapp.settings python manage.py test (requires Django installation)
  • Run slow tests: python -m tox -e slowtests -- takes 15+ minutes. NEVER CANCEL. Set timeout to 30+ minutes.

Code Quality and Linting

  • CRITICAL: Always run these before committing or CI will fail:
    • python -m tox -e style -- reformats code using ruff and runs linting checks
    • Alternative: ruff check . and ruff format . if available
  • Pre-commit hooks: pre-commit run --all-files -- runs all code quality checks
  • RUFF CONFIG: Project uses ruff for both linting and formatting (configured in pyproject.toml)

Documentation

  • Build docs: python -m tox -e docs -- builds HTML docs into docs/build/html/. Takes 3-5 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
  • Alternative: cd docs && make html -- if tox fails
  • Documentation uses Sphinx with furo theme

Development Workflow Commands

  • ALWAYS CHECK: Git status and branch before making changes: git status --porcelain && git branch -a (verified working)
  • BASIC CODE VALIDATION: python -c "import sys; sys.path.insert(0, '.'); import feincms3; print('✓ Import successful, version:', feincms3.__version__)" (verified working)
  • EXPLORE PROJECT STRUCTURE: Key directories to examine:
    • ls -la feincms3/ -- main package modules
    • ls -la tests/testapp/ -- test application structure
    • ls -la docs/ -- documentation files
    • find . -name "*.py" -path "*/tests/*" | wc -l -- count test files (should show ~27 test files)
  • Run tests after changes: Use pytest with Django settings: DJANGO_SETTINGS_MODULE=testapp.settings python -m pytest tests/testapp/ (requires Django installation)

Validation Scenarios

After making changes to feincms3, ALWAYS validate these scenarios:

  • Core CMS functionality: Test page creation, plugin integration, and content rendering
  • Admin interface: Verify Django admin integration works correctly
  • Plugin system: Test that content plugins (richtext, image, etc.) function properly
  • Tree queries: Validate hierarchical page structure operations work correctly

Build and Test Timing Expectations

  • CRITICAL TIMEOUT VALUES:
    • Full test suite: 10 minutes, set timeout to 15+ minutes
    • Style/linting: 2 minutes, set timeout to 5+ minutes
    • Documentation build: 5 minutes, set timeout to 10+ minutes
    • Slow tests: 15 minutes, set timeout to 30+ minutes
    • NEVER CANCEL any build or test command - wait for completion

Project Structure and Key Files

Core Modules

  • feincms3/ -- main package directory
    • __init__.py -- version info (currently 5.4.2)
    • pages.py -- core page model and functionality
    • applications.py -- application integration and URL handling
    • admin.py -- Django admin integration
    • plugins/ -- content plugins (richtext, image, html, etc.)
    • renderer.py -- content rendering system
    • mixins.py -- reusable model mixins

Test Suite

  • tests/testapp/ -- test Django application
    • settings.py -- test configuration
    • models.py -- test models
    • test_*.py -- test files for different components
    • manage.py -- Django management script for tests

Documentation

  • docs/ -- Sphinx documentation
    • build-your-cms.rst -- main tutorial
    • installation.rst -- installation guide
    • project/contributing.rst -- contribution guidelines

Configuration Files

  • pyproject.toml -- main project configuration, dependencies, build settings
  • tox.ini -- test environment configuration
  • .pre-commit-config.yaml -- code quality hooks
  • .github/workflows/tests.yml -- CI configuration

Common Command Reference

Frequently Referenced Files and Commands

The following are verified working commands and file locations:

# Repository structure exploration
ls -la  # Shows: pyproject.toml, tox.ini, .github/, docs/, feincms3/, tests/, README.rst
ls -la feincms3/  # Core modules: __init__.py, pages.py, applications.py, admin.py, plugins/, etc.
ls -la tests/testapp/  # Test suite: models.py, settings.py, test_*.py files (~17 test modules)

# Version and import verification
python -c "import sys; sys.path.insert(0, '.'); import feincms3; print('Version:', feincms3.__version__)"  # Shows: 5.4.2

# Git status checking
git status --porcelain && git branch -a  # Check current branch and uncommitted changes

# Available test environments
tox --listenvs  # Shows all Python/Django combinations (py310-dj32 through py313-djmain)

# Project dependency checking
cat pyproject.toml | grep -A 20 "dependencies"  # Shows core requirements
cat pyproject.toml | grep -A 10 "optional-dependencies"  # Shows [all] and [tests] extras

Important Development Notes

  • Django Version Support: Supports Django 3.2+ (check pyproject.toml for current matrix)
  • Python Version Support: Python 3.10+ (currently tested on 3.10-3.13)
  • Database Support: PostgreSQL, SQLite3 (>3.8.3), MariaDB (>10.2.2), MySQL 8.0
  • Architecture: Uses django-tree-queries for hierarchical page structure
  • Plugin System: Based on django-content-editor for flexible content plugins

Common Troubleshooting

  • CRITICAL: Network timeouts during pip install: This is the most common issue. PyPI connections frequently timeout with "ReadTimeoutError: HTTPSConnectionPool(host='pypi.org', port=443): Read timed out." This is an infrastructure limitation, not a code problem.
    • Retry with: pip install --timeout=300 <package>
    • If persistent, document command as "fails due to network limitations"
    • Continue development with basic Python validation instead
  • Import errors: Ensure Python path includes project root: sys.path.insert(0, '.')
  • Django not configured: Tests need DJANGO_SETTINGS_MODULE=testapp.settings
  • Missing dependencies: Install with specific extras: pip install -e '.[all,tests]' (when network allows)
  • Tox environment failures: Usually caused by pip network timeouts during virtual environment setup

Workflow Validation Steps

  1. Always run style checks: python -m tox -e style or ruff check . && ruff format .
  2. Run relevant tests: python -m tox -e py312-dj50 or specific test file
  3. Check documentation builds: python -m tox -e docs if making doc changes
  4. Verify admin functionality: Check Django admin still works with model changes
  5. Test plugin integration: Ensure content plugins render correctly after changes

Expected CI Behavior

The GitHub Actions workflow (.github/workflows/tests.yml) runs:

  • Tests across Python 3.10-3.13 and Django versions 3.2-5.2
  • Each test run takes 5-15 minutes depending on environment
  • Style checks and linting must pass or builds fail
  • NEVER CANCEL CI builds as they may take 20+ minutes for full matrix