WARP.md on Wagtail with AGENTS.md first draft

WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Commands

Development Setup

# Install development dependencies and build assets
make develop

# Alternative setup commands
pip install -e .[testing,docs] --config-settings editable-mode=strict
npm install --no-save && npm run build

Testing

# Run all Python tests
python runtests.py

# Run specific module tests
python runtests.py wagtail.tests.test_blocks

# Run specific test class
python runtests.py wagtail.tests.test_blocks.TestIntegerBlock

# Run with different database backends
python runtests.py --postgres
python runtests.py --elasticsearch8

# Run JavaScript unit tests
npm run test:unit

# Run JavaScript tests with watch mode
npm run test:unit:watch

# Run integration tests (requires separate terminal with test server)
export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
./wagtail/test/manage.py migrate
./wagtail/test/manage.py runserver 0:8000
# In separate terminal:
npm run test:integration

Code Quality

# Run all linting (Python, JS, CSS, docs)
make lint

# Run server-side linting only
make lint-server

# Run client-side linting only 
make lint-client

# Format all code
make format

# Format server-side code only
make format-server

# Format client-side code only
make format-client

Asset Building

# Build static assets for production
npm run build

# Watch and rebuild assets during development
npm start

# Run Storybook pattern library (requires Django server)
export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
./wagtail/test/manage.py runserver 0:8000
# In separate terminal:
npm run storybook

Documentation

# Build documentation
cd docs/
make html

# Auto-rebuild documentation on changes
make livehtml

# Clean and rebuild documentation
make clean && make html

Project Architecture

Core Structure

• wagtail/admin/ - Administrative interface and forms
• wagtail/blocks/ - StreamField block system for flexible content
• wagtail/models/ - Core page and content models
• wagtail/images/ - Image management and processing
• wagtail/documents/ - Document management
• wagtail/users/ - User management
• wagtail/sites/ - Multi-site support
• wagtail/contrib/ - Optional features and integrations
• wagtail/api/ - REST API framework
• wagtail/search/ - Search backends (Elasticsearch, PostgreSQL)

Frontend Architecture

• React components for interactive admin UI elements
• Stimulus controllers for progressive enhancement
• Webpack for asset bundling
• Storybook for component documentation
• Jest for JavaScript testing
• Sass/CSS with utility-first approach

Key Concepts

• StreamField: Flexible content blocks that can be composed by editors
• Page models: Django models that extend wagtail.models.Page
• Hooks: Extension points for customizing Wagtail behavior
• Panels: Admin interface components for editing content
• Telepath: Client-server communication for admin widgets

Development Practices

StreamField Template Access

In Wagtail templates, StreamField blocks require accessing the .value property:

<!-- Correct -->
{{ page.body.value }}

<!-- Wrong -->
{{ page.body }}

Django Version Compatibility

Always check Django version compatibility using explicit version checks:

from django import VERSION as DJANGO_VERSION

if DJANGO_VERSION >= (4, 2):
    # Use newer Django feature
else:
    # Use older approach

Test Structure

• Python tests use Django's test framework
• Tests are located alongside the code they test
• Frontend tests use Jest with jsdom environment
• Integration tests use Puppeteer for browser automation

Code Style

• Python: PEP8 via ruff formatter
• JavaScript/TypeScript: ESLint with Wagtail config
• CSS: Stylelint with Wagtail config
• Templates: djhtml for indentation

Pull Request Guidelines

• Describe the "why" behind changes, not just "what"
• Highlight areas requiring special review attention
• Always add AI agent disclosure when applicable:

  This pull request includes code written with the assistance of AI.
  The code has not yet been reviewed by a human.

Important Files

• runtests.py - Main test runner with various backend options
• pyproject.toml - Python packaging and dependency configuration
• package.json - Node.js dependencies and scripts
• Makefile - Common development commands
• client/webpack.config.js - Frontend build configuration