Interested in giving back to the community a little? Maybe you’ve found a bug
in Django that you’d like to see fixed, or maybe there’s a small feature you
want added.

Contributing back to Django itself is the best way to see your own concerns
addressed. This may seem daunting at first, but it’s a well-traveled path with
documentation, tooling, and a community to support you. We’ll walk you through
the entire process, so you can learn by example.

If you are looking for a reference on how to submit patches, see the
Submitting patches
documentation.

For this tutorial, we expect that you have at least a basic understanding of
how Django works. This means you should be comfortable going through the
existing tutorials on writing your first Django app.
In addition, you should have a good understanding of Python itself. But if you
don’t, Dive Into Python is a fantastic (and free) online book for
beginning Python programmers.

Those of you who are unfamiliar with version control systems and Trac will find
that this tutorial and its links include just enough information to get started.
However, you’ll probably want to read some more about these different tools if
you plan on contributing to Django regularly.

For the most part though, this tutorial tries to explain as much as possible,
so that it can be of use to the widest audience.

We’ll be walking you through contributing a patch to Django for the first time.
By the end of this tutorial, you should have a basic understanding of both the
tools and the processes involved. Specifically, we’ll be covering the following:

Installing Git.

Downloading a copy of Django’s development version.

Running Django’s test suite.

Writing a test for your patch.

Writing the code for your patch.

Testing your patch.

Submitting a pull request.

Where to look for more information.

Once you’re done with the tutorial, you can look through the rest of
Django’s documentation on contributing.
It contains lots of great information and is a must read for anyone who’d like
to become a regular contributor to Django. If you’ve got questions, it’s
probably got the answers.

Python 3 required!

The current version of Django doesn’t support Python 2.7. Get Python 3 at
Python’s download page or with your
operating system’s package manager.

For this tutorial, you’ll need Git installed to download the current
development version of Django and to generate patch files for the changes you
make.

To check whether or not you have Git installed, enter git into the command
line. If you get messages saying that this command could not be found, you’ll
have to download and install it, see Git’s download page.

If you’re not that familiar with Git, you can always find out more about its
commands (once it’s installed) by typing githelp into the command line.

The first step to contributing to Django is to get a copy of the source code.
First, fork Django on GitHub. Then,
from the command line, use the cd command to navigate to the directory
where you’ll want your local copy of Django to live.

Download the Django source code repository using the following command:

$ git clone https://github.com/YourGitHubName/django.git

Low bandwidth connection?

You can add the --depth1 argument to gitclone to skip downloading
all of Django’s commit history, which reduces data transfer from ~250 MB
to ~70 MB.

Now that you have a local copy of Django, you can install it just like you would
install any package using pip. The most convenient way to do so is by using
a virtual environment, which is a feature built into Python that allows you
to keep a separate directory of installed packages for each of your projects so
that they don’t interfere with each other.

It’s a good idea to keep all your virtual environments in one place, for
example in .virtualenvs/ in your home directory.

Create a new virtual environment by running:

$ python3 -m venv ~/.virtualenvs/djangodev

The path is where the new environment will be saved on your computer.

The final step in setting up your virtual environment is to activate it:

$source ~/.virtualenvs/djangodev/bin/activate

If the source command is not available, you can try using a dot instead:

$ . ~/.virtualenvs/djangodev/bin/activate

You have to activate the virtual environment whenever you open a new
terminal window.

For Windows users

To activate your virtual environment on Windows, run:

...\>%HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

The name of the currently activated virtual environment is displayed on the
command line to help you keep track of which one you are using. Anything you
install through pip while this name is displayed will be installed in that
virtual environment, isolated from other environments and system-wide packages.

Go ahead and install the previously cloned copy of Django:

$ python -m pip install -e /path/to/your/local/clone/django/

The installed version of Django is now pointing at your local copy by installing
in editable mode. You will immediately see any changes you make to it, which is
of great help when writing your first patch.

It may be helpful to test your local changes with a Django project. First you
have to create a new virtual environment, install the previously cloned
local copy of Django in editable mode,
and create a new Django project outside of your local copy of Django. You will
immediately see any changes you make to Django in your new project, which is
of great help when writing your first patch.

When contributing to Django it’s very important that your code changes don’t
introduce bugs into other areas of Django. One way to check that Django still
works after you make your changes is by running Django’s test suite. If all
the tests still pass, then you can be reasonably sure that your changes
work and haven’t broken other parts of Django. If you’ve never run Django’s test
suite before, it’s a good idea to run it once beforehand to get familiar with
its output.

Before running the test suite, install its dependencies by cd-ing into the
Django tests/ directory and then running:

$ python -m pip install -r requirements/py3.txt

If you encounter an error during the installation, your system might be missing
a dependency for one or more of the Python packages. Consult the failing
package’s documentation or search the Web with the error message that you
encounter.

Now we are ready to run the test suite. If you’re using GNU/Linux, macOS, or
some other flavor of Unix, run:

$ ./runtests.py

Now sit back and relax. Django’s entire test suite has thousands of tests, and
it takes at least a few minutes to run, depending on the speed of your
computer.

While Django’s test suite is running, you’ll see a stream of characters
representing the status of each test as it completes. E indicates that an
error was raised during a test, and F indicates that a test’s assertions
failed. Both of these are considered to be test failures. Meanwhile, x and
s indicated expected failures and skipped tests, respectively. Dots indicate
passing tests.

Skipped tests are typically due to missing external libraries required to run
the test; see Running all the tests for a list of dependencies
and be sure to install any for tests related to the changes you are making (we
won’t need any for this tutorial). Some tests are specific to a particular
database backend and will be skipped if not testing with that backend. SQLite
is the database backend for the default settings. To run the tests using a
different backend, see Using another settings module.

Once the tests complete, you should be greeted with a message informing you
whether the test suite passed or failed. Since you haven’t yet made any changes
to Django’s code, the entire test suite should pass. If you get failures or
errors make sure you’ve followed all of the previous steps properly. See
Running the unit tests for more information.

Note that the latest Django master may not always be stable. When developing
against master, you can check Django’s continuous integration builds to
determine if the failures are specific to your machine or if they are also
present in Django’s official builds. If you click to view a particular build,
you can view the “Configuration Matrix” which shows failures broken down by
Python version and database backend.

You can choose any name that you want for the branch, “ticket_99999” is an
example. All changes made in this branch will be specific to the ticket and
won’t affect the main copy of the code that we cloned earlier.

In most cases, for a patch to be accepted into Django it has to include tests.
For bug fix patches, this means writing a regression test to ensure that the
bug is never reintroduced into Django later on. A regression test should be
written in such a way that it will fail while the bug still exists and pass
once the bug has been fixed. For patches containing new features, you’ll need
to include tests which ensure that the new features are working correctly.
They too should fail when the new feature is not present, and then pass once it
has been implemented.

A good way to do this is to write your new tests first, before making any
changes to the code. This style of development is called
test-driven development and can be applied to both entire projects and
single patches. After writing your tests, you then run them to make sure that
they do indeed fail (since you haven’t fixed that bug or added that feature
yet). If your new tests don’t fail, you’ll need to fix them so that they do.
After all, a regression test that passes regardless of whether a bug is present
is not very helpful at preventing that bug from reoccurring down the road.

In order to resolve this ticket, we’ll add a make_toast() function to the
top-level django module. First we are going to write a test that tries to
use the function and check that its output looks correct.

Navigate to Django’s tests/shortcuts/ folder and create a new file
test_make_toast.py. Add the following code:

If you’ve never had to deal with tests before, they can look a little hard
to write at first glance. Fortunately, testing is a very big subject in
computer programming, so there’s lots of information out there:

Since we haven’t made any modifications to django.shortcuts yet, our test
should fail. Let’s run all the tests in the shortcuts folder to make sure
that’s really what happens. cd to the Django tests/ directory and run:

$ ./runtests.py shortcuts

If the tests ran correctly, you should see one failure corresponding to the test
method we added, with this error:

ImportError:cannotimportname'make_toast'from'django.shortcuts'

If all of the tests passed, then you’ll want to make sure that you added the
new test shown above to the appropriate folder and file name.

Once you’ve verified that your patch and your test are working correctly, it’s
a good idea to run the entire Django test suite to verify that your change
hasn’t introduced any bugs into other areas of Django. While successfully
passing the entire test suite doesn’t guarantee your code is bug free, it does
help identify many bugs and regressions that might otherwise go unnoticed.

To run the entire Django test suite, cd into the Django tests/
directory and run:

Since this new feature will be in an upcoming release it is also added to the
release notes for the next version of Django. Open the release notes for the
latest version in docs/releases/, which at time of writing is 2.2.txt.
Add a note under the “Minor Features” header:

For more information on writing documentation, including an explanation of what
the versionadded bit is all about, see
Writing documentation. That page also includes
an explanation of how to build a copy of the documentation locally, so you can
preview the HTML that will be generated.

Before you get too into writing patches for Django, there’s a little more
information on contributing that you should probably take a look at:

You should make sure to read Django’s documentation on
claiming tickets and submitting patches.
It covers Trac etiquette, how to claim tickets for yourself, expected
coding style for patches, and many other important details.

After those, if you’re still hungry for more information about
contributing, you can always browse through the rest of
Django’s documentation on contributing.
It contains a ton of useful information and should be your first source
for answering any questions you might have.

Once you’ve looked through some of that information, you’ll be ready to go out
and find a ticket of your own to write a patch for. Pay special attention to
tickets with the “easy pickings” criterion. These tickets are often much
simpler in nature and are great for first time contributors. Once you’re
familiar with contributing to Django, you can move on to writing patches for
more difficult and complicated tickets.

After a ticket has a patch, it needs to be reviewed by a second set of eyes.
After submitting a pull request, update the ticket metadata by setting the
flags on the ticket to say “has patch”, “doesn’t need tests”, etc, so others
can find it for review. Contributing doesn’t necessarily always mean writing a
patch from scratch. Reviewing existing patches is also a very helpful
contribution. See Triaging tickets for details.