How to contribute

Django uses a Trac-driven workflow. Bugs and feature requests live at code.djangoproject.com, pull requests live on GitHub, and the two are linked through the ticket number in commit messages (e.g., Fixed #36919 -- ...).

At a glance

1. Find or file a Trac ticket. Anything more than a typo fix needs one. CONTRIBUTING.rst is explicit: "non-trivial pull requests (anything more than fixing a typo) without Trac tickets will be closed".
2. Discuss design changes on the Django Forum or Discord before writing code if your change affects public API.
3. Write the patch with a regression test. No regression test = no merge.
4. Run the test suite locally (see getting started).
5. Open a PR against main. The PR title should reference the Trac ticket: Fixed #NNNNN -- Short description.
6. Iterate on review. A core team member or fellow will review. The DSF currently funds two fellows (Mariusz Felisiak, Sarah Boyce) who do the bulk of triage and review.
7. A merger lands the PR. Contributors do not merge their own PRs.

What to read first

• CONTRIBUTING.rst at the repo root — the short version of these rules.
• docs/internals/contributing/ — the long form, including the full PR checklist, coding style, commit message conventions, and review expectations.
• Code of Conduct — applies to all Django spaces.

Definition of done

Before requesting review, the PR should:

• Reference an open Trac ticket with the agreed-upon resolution.
• Include a regression test that fails on main without the patch and passes with it.
• Pass tox -e py3 black flake8 isort docs lint-docs zizmor.
• Update docs/releases/<next-version>.txt if the change is user-visible.
• Update reference docs in docs/ref/ if the change adds or modifies public API.
• Match Django's coding style. The pre-commit hook handles black/isort automatically; flake8 violations need manual fixes.

Where the rules are documented

• Coding style — docs/internals/contributing/writing-code/coding-style.txt
• Unit tests — docs/internals/contributing/writing-code/unit-tests.txt
• Working with git — docs/internals/contributing/writing-code/working-with-git.txt
• Submitting patches — docs/internals/contributing/writing-code/submitting-patches.txt
• Triage — docs/internals/contributing/triaging-tickets.txt
• Release process — docs/internals/release-process.txt
• Security policies — docs/internals/security.txt (and https://www.djangoproject.com/security/)

Sub-pages

• Development workflow — branch, code, test, PR, merge cycle in detail.
• Testing — frameworks, fixtures, test client, running subsets, parallelisation.
• Debugging — common errors, reading tracebacks, the runserver autoreloader, async debugging.
• Patterns and conventions — coding style, error handling, API stability rules, deprecation cycles.
• Tooling — black, isort, flake8, pre-commit, tox, sphinx.