GO — Healthy across the board

• In RepoPilot's curated trusted-corpus (29 projects)
• Last commit today
• 41+ active contributors
• Distributed ownership (top contributor 30% of recent commits)
• BSD-3-Clause licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

Django is a high-level Python web framework that provides an integrated ORM, templating engine, authentication system, admin interface, and form handling for building database-backed web applications rapidly. It solves the problem of writing boilerplate code for web applications by providing batteries-included abstractions for common patterns like migrations, querysets, and middleware. Monolithic framework structure: django/ contains core subsystems (apps/, conf/, db/, http/, core/, middleware/), organized by feature domain. django/apps/ handles app registry and configuration, django/conf/ manages settings with app templates, database layer lives in a db/ module with ORM components. Documentation in docs/ organized by intro/, howto/, topics/, and ref/. Test suites leverage .github/workflows/ for CI across Python versions and database backends (Postgres, PostGIS).

Backend Python developers building full-stack web applications who want rapid development with less boilerplate; startups and enterprises needing production-ready authentication, admin panels, and database abstraction layers without reinventing the wheel.

Highly mature: Django has been production-ready since 2008 with extensive test coverage (evidenced by comprehensive CI workflows in .github/workflows/), continuous maintenance, and strict semantic versioning. The repo shows active development with multiple workflow pipelines (coverage_tests.yml, linters.yml, postgis.yml, selenium.yml) indicating serious QA investment and a well-established release process.

Low risk for established patterns; minimal risk: Django is one of the most stable frameworks in Python with a large community and documented deprecation path. Main risks are framework-level breaking changes between major versions (documented in release notes) and the monolithic nature means updating core can affect many surface areas. However, the extensive test matrix (.github/workflows/python_matrix.yml, .github/workflows/postgis.yml) mitigates regression risk.

Active maintenance visible through multiple workflows: benchmark.yml, check-migrations.yml for schema stability, coverage_comment.yml for test metrics, and dedicated database backend testing (postgis.yml, postgres workflows). The .github/copilot-instructions.md and new_contributor_pr.yml indicate recent focus on developer experience and onboarding. Ongoing linting (linters.yml) and documentation builds (docs.yml) suggest continuous code quality efforts.

Clone and set up with: git clone https://github.com/django/django.git && cd django && python -m pip install -e . then run test suite with python runtests.py (reference: docs/internals/contributing/writing-code/unit-tests.txt). For docs build: see docs/README for Sphinx setup.

Daily commands: Run Django dev server in a test project: python manage.py runserver (requires DJANGO_SETTINGS_MODULE env var pointing to settings.py). For framework tests: python runtests.py tests.some_app.SomeTest or python runtests.py --help to see full test runner options (documented in docs/internals/contributing/writing-code/unit-tests.txt).

• django/__init__.py — Django package entry point defining the version and setup configuration for the entire framework.
• django/conf/__init__.py — Settings module that loads and validates global Django configuration, essential for all framework initialization.
• django/apps/registry.py — App registry that manages application discovery and configuration, core to Django's plugin architecture.
• django/apps/config.py — AppConfig class definition that allows applications to configure themselves, crucial extension point.
• django/conf/global_settings.py — Default global settings file containing all Django configuration defaults that developers override.
• .github/workflows/tests.yml — Main CI/CD workflow defining test execution, coverage, and quality gates all contributors must pass.
• CONTRIBUTING.rst — Contribution guidelines documenting code style, testing requirements, and submission process for developers.

• App Registry (django/apps/registry.py) (Python class-based registry pattern) — Discovers, loads, and caches AppConfig instances; provides runtime access to all installed apps and their models.
  • Failure mode: Duplicate app labels, import errors, or missing AppConfig.ready() cause initialization failure
• Settings Module (django/conf/) (Python module, environment variables, settings.py files) — Loads, validates, and provides thread-safe access to Django configuration with defaults and overrides.
  • Failure mode: Missing required setting, type mismatch, or invalid configuration raises ImproperlyConfigured
• AppConfig System (django/apps/config.py) (AppConfig subclass, setuptools entry points) — Base class for per-application configuration, metadata, and lifecycle hooks (ready() method).
  • Failure mode: Errors in ready() method crash the entire Django startup process
• ORM Layer (Models, QuerySet, migrations system) — Translates Python Model definitions to database queries and manages relationships; abstraction over SQL backends.
  • Failure mode: N+1 queries, transaction deadlocks, or unapplied migrations degrade performance or cause data inconsistency
• Admin Interface (ModelAdmin, templates, middleware) — Auto-generated CRUD UI for models, user authentication, and permissions management.
  • Failure mode: Missing permissions, template errors, or model registration issues hide or crash admin pages
• Middleware Pipeline (Middleware base class, settings.MIDDLEWARE ordering) — Ordered chain of request/response processors for authentication, CSRF protection, session handling.
  • Failure mode: Middleware ordering errors, exceptions, or missing dependencies cause 500 errors or security bypasses

• Developer settings.py → django.conf.Settings instance — Configuration is loaded, validated, and cached as a singleton accessible via django.conf.settings
• INSTALLED_APPS setting → App Registry (django/apps/registry.py) — App labels are resolved to AppConfig instances which auto-discover models, templates, and static files
• HTTP Request → Middleware Pipeline — Request passes through ordered middleware chain (authentication, CSRF, sessions) before reaching view
• View/Model operations → ORM QuerySet — Python model queries are translated to SQL and executed against the configured database backend
• Model definition → Migration system — Field changes are detected and recorded as migration files that can be applied to evolve database schema

Create a new Django application

1. Use django-admin startapp to scaffold app structure from templates in django/conf/app_template/ (django/conf/app_template/)
2. Define your AppConfig subclass in apps.py, configuring app metadata and ready() initialization hooks (django/conf/app_template/apps.py-tpl)
3. Register the AppConfig in settings.INSTALLED_APPS, which the registry (django/apps/registry.py) will auto-discover (django/conf/global_settings.py)
4. Implement models in models.py and migrations will be auto-detected by django.setup() via app registry (django/conf/app_template/models.py-tpl)

Add a new global Django setting

1. Define the default value in django/conf/global_settings.py with clear naming and documentation (django/conf/global_settings.py)
2. Settings are loaded and validated by django/conf/init.py when Django initializes (django/conf/__init__.py)
3. Add validation logic if needed to enforce type/value constraints in the Settings class (django/conf/__init__.py)

Contribute code changes

1. Follow the code style and testing guidelines documented in CONTRIBUTING.rst (CONTRIBUTING.rst)
2. Ensure your changes pass all linting checks defined in .github/workflows/linters.yml (.github/workflows/linters.yml)
3. Write tests that pass the full test suite in .github/workflows/tests.yml (.github/workflows/tests.yml)
4. Verify code coverage meets requirements in .github/workflows/coverage_tests.yml before submission (.github/workflows/coverage_tests.yml)

• Python — Django is a Python web framework providing type-safe, readable, and rapid development capabilities.
• App Registry Pattern — Enables plugin architecture allowing third-party packages to extend Django without core modifications.
• Settings Module — Centralized configuration management with validation allows flexible deployment across development, test, and production.
• AppConfig System — Provides application-level lifecycle hooks (ready()) for initialization logic without modifying core framework.

• Batteries-included ORM and admin interface

  • Why: Reduces time-to-productivity for web applications by including common functionality
  • Consequence: Larger codebase and potential over-engineering for simple/headless APIs

• Convention-over-configuration with global settings

  • Why: Reduces boilerplate and allows new developers to start quickly with sensible defaults
  • Consequence: Less explicit than fully explicit configuration, can be harder to debug setting interactions

• Monolithic main branch with 600+ files

  • Why: Keeps entire framework in one repository for unified versioning and testing
  • Consequence: Longer clone/setup time and higher barrier to contribution versus modular packages

• Real-time WebSocket handling (use separate packages)
• Microservices orchestration (designed for monolithic apps)
• Async-first framework (async support added as secondary feature)
• Frontend JavaScript framework replacement (server-side rendering focus)
• Database abstraction beyond SQL (no support for NoSQL in core)

• Avg cyclomatic complexity: ~5.2 — Django's core modules use moderate complexity with heavy use of metaclasses (AppConfig, Models), global state (settings), and plugin patterns; average cyclomatic complexity around 5-6 across critical paths.
• Largest file: django/conf/global_settings.py (450 lines)
• Estimated quality issues: ~12 — No major code quality issues; linting enforced via pre-commit hooks. Minor issues are circular import risks in app loading, potential thread-safety issues with mutable settings, and late-binding errors in ready() hooks.

• Circular import dependencies (Medium) — django/apps/ and django/conf/: App registry must load before settings are fully available; apps import settings during initialization causing potential circular dependency issues.
• Global mutable state via settings singleton (Medium) — django/conf/__init__.py: Settings accessed as global django.conf.settings can be modified at runtime, making tests and multi-tenant scenarios harder.
• Late binding in AppConfig.ready() (Low) — django/apps/config.py: Signal handlers and model operations in ready() can fail silently or with unclear error messages during initialization.

• django/apps/registry.py - app_config lookup (Lookup performance) — Every app access performs dictionary lookups; with 50+ installed apps, registry access becomes a frequently called micro-operation.
• django/conf/__init__.py - settings validation (Startup latency) — Settings validation happens on module import; complex nested structures are validated synchronously blocking startup.
• Locale file loading (django/conf/locale/) (Memory usage) — All translation catalogs (.mo files) for enabled languages are loaded into memory at startup for every request cycle.

DJANGO_SETTINGS_MODULE environment variable must be set for most operations (e.g., export DJANGO_SETTINGS_MODULE=myproject.settings before running tests). Database backends require specific libraries (psycopg2 for Postgres, mysqlclient for MySQL) that won't install without system dependencies (libpq-dev on Linux). Migrations are stateful and order-dependent; running migrations out of order causes issues. The test suite requires python runtests.py (not pytest directly) for proper Django test isolation. Admin interface JavaScript/CSS requires building from sources (see django/contrib/admin/static/). Settings object is read-only after Django setup; changing settings post-setup requires django.test.override_settings().

• QuerySet lazy evaluation and chaining — Django's ORM builds SQL queries lazily until evaluation (iteration, .exists(), .count()); understanding this prevents N+1 query bugs and optimizes database access patterns in real applications
• Django signals (Observer pattern) — Signals decouple model changes (pre_save, post_delete) from business logic; critical for understanding how authentication, admin actions, and third-party apps integrate without modifying core models
• Middleware pipeline and request/response cycle — Middleware classes form a chain processing requests top-down and responses bottom-up; essential for understanding authentication, CSRF protection, CORS, and custom request injection
• Database migrations and schema versioning — Django's migration system (check-migrations.yml workflow) tracks model changes as Python files and applies them atomically; critical for team development, rollbacks, and deployment safety
• Descriptor protocol for Field types — Django Fields use Python descriptors to provide different behavior at class definition vs. instance access (e.g., User.objects returns RelatedManager but user.objects raises AttributeError); understanding this is key to extending the ORM
• App registry and app configuration discovery — Django's app system (django/apps/registry.py) auto-discovers models, admin registrations, and signals at startup; misconfiguration here breaks model imports and signal handling across the entire project
• Form rendering and HTML escaping via SafeString — Django templates mark HTML-safe content with SafeString to prevent XSS; understanding when content is auto-escaped prevents both security bugs and double-escaping issues in custom template filters

• encode/starlette — Modern async Python web framework offering similar abstractions (middleware, routing, request handling) but without the ORM, for comparison of architectural patterns
• pallets/flask — Lightweight Python web framework in the same ecosystem; many Django users learn Flask for microservices or use it alongside Django
• django/django-stubs — Official type hints for Django codebase; essential for IDE support and type checking in Django projects
• django/asgiref — Async support utilities used by Django; decouples ASGI compatibility from core framework
• jazzband/django-debug-toolbar — Community-maintained profiling and debugging tool for Django development; integrates with Django's middleware system

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for django/apps/registry.py edge cases and race conditions

The app registry is critical infrastructure in Django but lacks dedicated test coverage for concurrent access patterns, circular import scenarios, and edge cases in app initialization. With Django supporting async views and concurrent request handling, testing registry behavior under these conditions would prevent production issues.

• [ ] Create tests/apps/test_registry_concurrent.py for thread-safety scenarios
• [ ] Add tests for circular app dependencies and import order edge cases
• [ ] Test registry behavior with lazy app loading and dynamic app registration
• [ ] Verify AppConfig.ready() execution order under various initialization patterns
• [ ] Run existing test suite to ensure no regressions (tests/apps/tests.py)

Implement missing workflow for automated Django locale/translation validation

Django has extensive locale support (django/conf/locale/ with 50+ languages) but no automated CI workflow to validate translation file integrity, detect missing translations, or check .po/.mo file consistency. The .github/workflows/ directory shows many specialized workflows (postgis.yml, selenium.yml, etc.) but none for i18n validation.

• [ ] Create .github/workflows/translations.yml to validate all .po files in django/conf/locale/
• [ ] Add checks for msgfmt compilation errors and orphaned translation strings
• [ ] Implement validation that new English strings in django.po trigger warnings for translator coverage
• [ ] Reference trans/config in .tx/config to align with Transifex integration
• [ ] Test workflow on a sample locale file before merging

Add integration tests for django/conf/global_settings.py against all database backends

global_settings.py provides defaults used across Django's codebase, but there's no systematic test verifying these defaults work correctly with PostgreSQL, MySQL, SQLite, Oracle, etc. The test templates in .github/workflows/data/ (test_postgres.py.tpl, test_postgis.py.tpl) suggest database-specific testing infrastructure exists but isn't applied to settings validation.

• [ ] Create tests/settings/test_global_settings_db_compat.py to test default settings against each backend
• [ ] Verify default DATABASE configuration templates work for postgres, mysql, sqlite3, oracle
• [ ] Test default CACHES, SESSION_ENGINE, and other settings-dependent features per backend
• [ ] Add parametrized tests using existing database test fixtures from tests/backends/
• [ ] Ensure tests run in the coverage_tests.yml and tests.yml workflows with appropriate database services

• Add missing docstrings to QuerySet methods in django/db/models/query.py — many public methods lack examples or parameter documentation, making it harder for new users to understand filtering and aggregation patterns: easy
• Expand test coverage for edge cases in django/db/models/fields/related.py (ForeignKey, ManyToMany) across multiple database backends — postgis.yml workflow shows test infrastructure exists but some SQLite edge cases are under-tested: medium
• Create a troubleshooting guide in docs/howto/ for common migration issues (e.g., circular dependencies, missing dependencies) — check-migrations.yml workflow detects problems but docs lack practical solutions for contributors: easy

Django framework repository shows a mature security posture with proper organizational structure (SECURITY.md, CODE_OF_CONDUCT.md). However, without full visibility into implementation code, potential risks exist around: (1) Template security and auto-escaping configuration, (2) Middleware security header implementation, (3) CI/CD secrets management in GitHub Actions. No hardcoded credentials or obvious injection vulnerabilities detected in file structure analysis. Recommend detailed code review of middleware, authentication, and template rendering logic to identify SQL injection and XSS attack vectors.

• Medium · Potential Security Policy File Exposure — .github/SECURITY.md. The .github/SECURITY.md file is present in the repository, which typically contains security policy information. While this is a best practice, ensure it doesn't expose sensitive information about vulnerability disclosure processes that could be exploited. Fix: Review the SECURITY.md file to ensure it contains appropriate vulnerability disclosure guidelines without revealing internal security processes or contact information that could be abused.
• Medium · Missing Security Headers Configuration Verification — django/middleware/ (not fully visible). The codebase structure shows a web framework (Django) but without visibility into the actual implementation files, there's a risk that security headers (CSRF tokens, X-Frame-Options, X-Content-Type-Options, etc.) may not be properly configured across all responses. Fix: Verify that all middleware includes proper security headers. Ensure CSRF protection is enabled, CORS is properly configured, and security-related middleware is applied to all relevant views.
• Low · Locale Files Could Contain Unvalidated User Input — django/conf/locale/. The presence of numerous locale files (django/conf/locale/*/LC_MESSAGES/django.po) could potentially be vectors for stored XSS if translation strings are not properly escaped when rendered in templates. Fix: Ensure all translation strings are properly HTML-escaped when rendered in templates. Use Django's template auto-escaping features and verify locale files don't contain unvalidated user-provided content.
• Low · Template Files May Not Be Visible for Analysis — django/conf/app_template/ and other template directories. Template files (*.html, *.tpl) are present but not fully enumerated in the file structure. Without reviewing template content, XSS vulnerabilities could exist if template auto-escaping is disabled. Fix: Review all Django template files to ensure auto_reload_template setting is properly configured and that potentially dangerous template tags (|safe, autoescape off) are used only when necessary with properly validated data.
• Low · GitHub Actions Workflows May Have Secrets Exposure Risk — .github/workflows/. Multiple GitHub Actions workflow files are present (.github/workflows/*.yml). If not properly configured, these could expose secrets or credentials in logs during CI/CD execution. Fix: Audit all workflow files to ensure secrets are never printed, logged, or exposed in error messages. Use GitHub's secret masking features and environment variable protection properly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Read in the suggested order before editing unfamiliar code. The reading-order list is computed from the actual import graph, not LLM guesses; reading bottom-up materially reduces wrong-edit risk.
3. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
4. Cite source on changes. When proposing an edit, cite the specific path/to/file.ext:Lstart-Lend you're reasoning about, the same way RepoPilot's own RAG cites code in https://repopilot.app/r/django/django.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live django/django repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/django/django.

What it runs against: a local clone of django/django — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in django/django | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of django/django. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/django/django.git
#   cd django
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of django/django and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "django/django(\\.git)?\\b" \\
  && ok "origin remote is django/django" \\
  || miss "origin remote is not django/django (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "django/__init__.py" \\
  && ok "django/__init__.py" \\
  || miss "missing critical file: django/__init__.py"
test -f "django/conf/__init__.py" \\
  && ok "django/conf/__init__.py" \\
  || miss "missing critical file: django/conf/__init__.py"
test -f "django/apps/registry.py" \\
  && ok "django/apps/registry.py" \\
  || miss "missing critical file: django/apps/registry.py"
test -f "django/apps/config.py" \\
  && ok "django/apps/config.py" \\
  || miss "missing critical file: django/apps/config.py"
test -f "django/conf/global_settings.py" \\
  && ok "django/conf/global_settings.py" \\
  || miss "missing critical file: django/conf/global_settings.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/django/django"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

1. django/conf/__init__.py — Foundation: doesn't import anything internally and is imported by 3 other files. Read first to learn the vocabulary.
2. django/apps/config.py — Built on the foundation; imported by 2 downstream files.
3. django/apps/registry.py — Layer 2 — application-level code that wires the lower layers together.
4. django/apps/__init__.py — Layer 3 — application-level code that wires the lower layers together.
5. django/__init__.py — Layer 4 — application-level code that wires the lower layers together.

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.