This document explains how to prepare to contribute to Django. It is intended for use during sprints, or by people who are already familiar with contributing to Python open source projects.
This guide assumes you're familiar with:
Git (see 使用 Git 和 GitHub 工作)
Managing multiple versions of Python
Python dependency management, including virtual environments
The concept of running tests and building documentation
If any of these are unfamiliar, see 编写你的第一个 Django 贡献 for a longer, step-by-step tutorial.
Fork the repository on GitHub, clone your fork to your machine, and configure a remote reference to Django's upstream repository:
$ git clone https://github.com/YourGitHubName/django.git
$ cd django
$ git remote add upstream https://github.com/django/django.git
...\> git clone https://github.com/YourGitHubName/django.git
...\> cd django
...\> git remote add upstream https://github.com/django/django.git
Confirm you're using a compatible version of Python, then set up a virtual environment:
$ # This needs to be >= 3.12
$ python -V
$ python -m venv ~/.virtualenvs/djangodev
$ source ~/.virtualenvs/djangodev/bin/activate
If you are not using a Unix-like system, see the platform-specific instructions.
Install the dependencies to run the tests and build the documentation:
$ python -m pip install -U pip
$ python -m pip install -e . -r tests/requirements/py3.txt -r docs/requirements.txt
...\> py -m pip install -U pip
...\> py -m pip install -e . -r tests\requirements\py3.txt -r docs\requirements.txt
Install pre-commit hooks so that formatting and linting run automatically before each commit:
$ python -m pip install pre-commit
$ pre-commit install
...\> py -m pip install pre-commit
...\> pre-commit install
See 预提交检查 for further details.
Run the tests:
$ ./tests/runtests.py
...\> tests\runtests.py
See 运行单元测试 for more information. While tests will all pass in CI, they may not on every person's local environment. For example, the test suite is only guaranteed to pass on the latest point release of each supported Python version. It's possible you may encounter errors using an earlier point release.
If you have a small number of failures, it may be worth investigating whether they are known issues, or using the django-docker-box project to run the tests. Since this is a sprint, it may be more valuable for you to work on the issue at hand rather than investigating a weird machine configuration problem. Make a note of the failing tests before you start, so you can tell whether a later failure was caused by your changes.
Build the documentation:
$ cd docs && make html && cd ..
...\> cd docs && make.bat html && cd ..
Finding a workable ticket is a challenging task. It's important to read this section before attempting to do so.
When looking over tickets, it's a good idea to keep your search to accepted tickets created in the last five years. Older tickets are old for a reason: they are usually still open because they are hard, contentious, or both. You're welcome to try one, but expect it to require a high degree of perseverance.
Consider using the component filter option in Trac to limit your search to
areas you have used before. If you've used forms in a few Django apps, consider
filtering down to the forms component. Similarly, if you've never worked with
geospatial projects, it's probably wise to avoid django.contrib.gis. For
example, here are the tickets for the documentation component.
There are two recommended ways to find a ticket:
Look at the easy pickings.
Use the vulture method.
The vulture method is the process of looking for accepted tickets that haven't been touched in six months or longer. The ideal ticket has a PR linked to it that has a code review with explicit requests for changes and the author has not responded in at least six months on the PR and on the ticket. Before taking one over, leave a comment on both the ticket and the PR letting the author know that you are continuing their work.
You can view the list of possibly vulture-able tickets here. The filters that are applied are:
Triage stage = Accepted
Patch needs improvement = Yes
Created = between 5 years ago and today
Modified = between 5 years ago and 6 months ago
When you find a ticket, make yourself the owner by clicking the "Modify Ticket" button near the bottom of the page, selecting the "assign to" radio button in the "Action" section, and clicking "Submit changes". Your username will be filled in the text box by default. See “认领”工单 for the full documentation.
How you create your branch depends on whether the ticket already has work attached to it.
With the ticket claimed, create a branch for your work, replacing
TicketNumber with the actual Trac ticket number:
$ git fetch upstream
$ git checkout -b ticket_TicketNumber upstream/main
...\> git fetch upstream
...\> git checkout -b ticket_TicketNumber upstream/main
When your work is ready, push the branch to your fork and open a pull request. See 提交贡献 for the full process.
If you're continuing the work from someone else's pull request on GitHub, things can be tricky. You need to pull their branch, but then push it to your GitHub repository fork.
Run the following, replacing PRNumber and TicketNumber with the actual
pull request and Trac ticket numbers:
$ git fetch upstream pull/PRNumber/head:ticket_TicketNumber
$ git checkout ticket_TicketNumber
$ git push origin ticket_TicketNumber
...\> git fetch upstream pull/PRNumber/head:ticket_TicketNumber
...\> git checkout ticket_TicketNumber
...\> git push origin ticket_TicketNumber
For example, to continue PR 8000 for ticket 123, run:
$ git fetch upstream pull/8000/head:ticket_123
$ git checkout ticket_123
$ git push origin ticket_123
...\> git fetch upstream pull/8000/head:ticket_123
...\> git checkout ticket_123
...\> git push origin ticket_123
When preparing your commit, please review our committing guidelines, specifically how to credit co-authors.
8月 05, 2026