Writing your first patch for Django

Introduction

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

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

Who’s this tutorial for?

See also

If you are looking for a reference on how to submit patches, see theSubmitting patchesdocumentation.

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

Those of you who are unfamiliar with version control systems and Trac will findthat 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 ifyou 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.

Where to get help:

If you’re having trouble going through this tutorial, please post a messageto django-developers or drop by #django-dev on irc.freenode.net tochat with other Django users who might be able to help.

What does this tutorial cover?

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 thetools 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 ofDjango’s documentation on contributing.It contains lots of great information and is a must read for anyone who’d liketo become a regular contributor to Django. If you’ve got questions, it’sprobably got the answers.

Python 3 required!

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

For Windows users

When installing Python on Windows, make sure you check the option “Addpython.exe to Path”, so that it is always available on the command line.

Code of Conduct

As a contributor, you can help us keep the Django community open and inclusive.Please read and follow our Code of Conduct.

Installing Git

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

To check whether or not you have Git installed, enter git into the commandline. If you get messages saying that this command could not be found, you’llhave 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 itscommands (once it’s installed) by typing git help into the command line.

Getting a copy of Django’s development version

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 directorywhere you’ll want your local copy of Django to live.

Download the Django source code repository using the following command:

  1. $ git clone https://github.com/YourGitHubName/django.git
  1. ...\> git clone https://github.com/YourGitHubName/django.git

Low bandwidth connection?

You can add the —depth 1 argument to git clone to skip downloadingall of Django’s commit history, which reduces data transfer from ~250 MBto ~70 MB.

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

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

Create a new virtual environment by running:

  1. $ python3 -m venv ~/.virtualenvs/djangodev
  1. ...\> py -m venv %HOMEPATH%\.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:

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

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

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

You have to activate the virtual environment whenever you open a newterminal window. virtualenvwrapper is a useful tool for making thismore convenient.

For Windows users

To activate your virtual environment on Windows, run:

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

or you can install a Windows version of virtualenvwrapper and then use:

  1. ...\> workon djangodev

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

Go ahead and install the previously cloned copy of Django:

  1. $ python -m pip install -e /path/to/your/local/clone/django/
  1. ...\> py -m pip install -e \path\to\your\local\clone\django\

The installed version of Django is now pointing at your local copy. You willimmediately see any changes you make to it, which is of great help when writingyour first patch.

Running Django’s test suite for the first time

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

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

  1. $ python -m pip install -r requirements/py3.txt
  1. ...\> py -m pip install -r requirements\py3.txt

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

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

  1. $ ./runtests.py
  1. ...\> runtests.py

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

While Django’s test suite is running, you’ll see a stream of charactersrepresenting the status of each test as it completes. E indicates that anerror was raised during a test, and F indicates that a test’s assertionsfailed. Both of these are considered to be test failures. Meanwhile, x ands indicated expected failures and skipped tests, respectively. Dots indicatepassing tests.

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

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

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

Note

For this tutorial and the ticket we’re working on, testing against SQLiteis sufficient, however, it’s possible (and sometimes necessary) torun the tests using a different database.

Working on a feature

For this tutorial, we’ll work on a “fake ticket” as a case study. Here are theimaginary details:

Ticket #99999 – Allow making toast

Django should provide a function django.shortcuts.make_toast() thatreturns 'toast'.

We’ll now implement this feature and associated tests.

Creating a branch for your patch

Before making any changes, create a new branch for the ticket:

  1. $ git checkout -b ticket_99999
  1. ...\> git checkout -b ticket_99999

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

Writing some tests for your ticket

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 thebug is never reintroduced into Django later on. A regression test should bewritten in such a way that it will fail while the bug still exists and passonce the bug has been fixed. For patches containing new features, you’ll needto 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 ithas been implemented.

A good way to do this is to write your new tests first, before making anychanges to the code. This style of development is calledtest-driven development and can be applied to both entire projects andsingle patches. After writing your tests, you then run them to make sure thatthey do indeed fail (since you haven’t fixed that bug or added that featureyet). 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 presentis not very helpful at preventing that bug from reoccurring down the road.

Now for our hands-on example.

Writing a test for ticket #99999

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

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

  1. from django.shortcuts import make_toast
  2. from django.test import SimpleTestCase
  3.  
  4.  
  5. class MakeToastTests(SimpleTestCase):
  6.     def test_make_toast(self):
  7.         self.assertEqual(make_toast(), 'toast')

This test checks that the make_toast() returns 'toast'.

But this testing thing looks kinda hard…

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

  • A good first look at writing tests for Django can be found in thedocumentation on Writing and running tests.
  • Dive Into Python (a free online book for beginning Python developers)includes a great introduction to Unit Testing.
  • After reading those, if you want something a little meatier to sinkyour teeth into, there’s always the Python unittest documentation.

Running your new test

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

  1. $ ./runtests.py shortcuts
  1. ...\> runtests.py shortcuts

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

  1. ImportError: cannot import name 'make_toast' from 'django.shortcuts'

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

Writing the code for your ticket

Next we’ll be adding the make_toast() function.

Navigate to the django/ folder and open the shortcuts.py file. At thebottom, add:

  1. def make_toast():
  2.     return 'toast'

Now we need to make sure that the test we wrote earlier passes, so we can seewhether the code we added is working correctly. Again, navigate to the Djangotests/ directory and run:

  1. $ ./runtests.py shortcuts
  1. ...\> runtests.py shortcuts

Everything should pass. If it doesn’t, make sure you correctly added thefunction to the correct file.

Running Django’s test suite for the second time

Once you’ve verified that your patch and your test are working correctly, it’sa good idea to run the entire Django test suite to verify that your changehasn’t introduced any bugs into other areas of Django. While successfullypassing the entire test suite doesn’t guarantee your code is bug free, it doeshelp 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:

  1. $ ./runtests.py
  1. ...\> runtests.py

Writing Documentation

This is a new feature, so it should be documented. Open the filedocs/topics/http/shortcuts.txt and add the following at the end of thefile:

  1. make_toast()

.. versionadded:: 2.2

Returns 'toast'.

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

  1. :mod:`django.shortcuts`
  2. ~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. * The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

For more information on writing documentation, including an explanation of whatthe versionadded bit is all about, seeWriting documentation. That page also includesan explanation of how to build a copy of the documentation locally, so you canpreview the HTML that will be generated.

Previewing your changes

Now it’s time to go through all the changes made in our patch. To stage all thechanges ready for commit, run:

  1. $ git add --all
  1. ...\> git add --all

Then display the differences between your current copy of Django (with yourchanges) and the revision that you initially checked out earlier in thetutorial with:

  1. $ git diff --cached
  1. ...\> git diff --cached

Use the arrow keys to move up and down.

  1. diff --git a/django/shortcuts.py b/django/shortcuts.py
  2. index 7ab1df0e9d..8dde9e28d9 100644
  3. --- a/django/shortcuts.py
  4. +++ b/django/shortcuts.py
  5. @@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
  6.  
  7.      # Finally, fall back and assume it's a URL
  8.      return to
  9. +
  10. +
  11. +def make_toast():
  12. +    return 'toast'
  13. diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
  14. index 7d85d30c4a..81518187b3 100644
  15. --- a/docs/releases/2.2.txt
  16. +++ b/docs/releases/2.2.txt
  17. @@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
  18.  Minor features
  19.  --------------
  20.  
  21. +:mod:`django.shortcuts`
  22. +~~~~~~~~~~~~~~~~~~~~~~~
  23. +
  24. +* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
  25. +
  26.  :mod:`django.contrib.admin`
  27.  ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28.  
  29. diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
  30. index 7b3a3a2c00..711bf6bb6d 100644
  31. --- a/docs/topics/http/shortcuts.txt
  32. +++ b/docs/topics/http/shortcuts.txt
  33. @@ -271,3 +271,12 @@ This example is equivalent to::
  34.          my_objects = list(MyModel.objects.filter(published=True))
  35.          if not my_objects:
  36.              raise Http404("No MyModel matches the given query.")
  37. +
  38. +``make_toast()``
  39. +================
  40. +
  41. +.. function:: make_toast()
  42. +
  43. +.. versionadded:: 2.2
  44. +
  45. +Returns ``'toast'``.
  46. diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
  47. new file mode 100644
  48. index 0000000000..6f4c627b6e
  49. --- /dev/null
  50. +++ b/tests/shortcuts/test_make_toast.py
  51. @@ -0,0 +1,7 @@
  52. +from django.shortcuts import make_toast
  53. +from django.test import SimpleTestCase
  54. +
  55. +
  56. +class MakeToastTests(SimpleTestCase):
  57. +    def test_make_toast(self):
  58. +        self.assertEqual(make_toast(), 'toast')

When you’re done previewing the patch, hit the q key to return to thecommand line. If the patch’s content looked okay, it’s time to commit thechanges.

Committing the changes in the patch

To commit the changes:

  1. $ git commit
  1. ...\> git commit

This opens up a text editor to type the commit message. Follow the commitmessage guidelines and write a message like:

  1. Fixed #99999 -- Added a shortcut function to make toast.

Pushing the commit and making a pull request

After committing the patch, send it to your fork on GitHub (substitute“ticket_99999” with the name of your branch if it’s different):

  1. $ git push origin ticket_99999
  1. ...\> git push origin ticket_99999

You can create a pull request by visiting the Django GitHub page. You’ll see your branch under “Yourrecently pushed branches”. Click “Compare & pull request” next to it.

Please don’t do it for this tutorial, but on the next page that displays apreview of the patch, you would click “Create pull request”.

Next steps

Congratulations, you’ve learned how to make a pull request to Django! Detailsof more advanced techniques you may need are inWorking with Git and GitHub.

Now you can put those skills to good use by helping to improve Django’scodebase.

More information for new contributors

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

  • You should make sure to read Django’s documentation onclaiming tickets and submitting patches.It covers Trac etiquette, how to claim tickets for yourself, expectedcoding style for patches, and many other important details.
  • First time contributors should also read Django’s documentationfor first time contributors.It has lots of good advice for those of us who are new to helping outwith Django.
  • After those, if you’re still hungry for more information aboutcontributing, you can always browse through the rest ofDjango’s documentation on contributing.It contains a ton of useful information and should be your first sourcefor answering any questions you might have.

Finding your first real ticket

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

If you just want to get started already (and nobody would blame you!), trytaking a look at the list of easy tickets that need patches and theeasy tickets that have patches which need improvement. If you’re familiarwith writing tests, you can also look at the list ofeasy tickets that need tests. Remember to follow the guidelines aboutclaiming tickets that were mentioned in the link to Django’s documentation onclaiming tickets and submitting patches.

What’s next after creating a pull request?

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 theflags on the ticket to say “has patch”, “doesn’t need tests”, etc, so otherscan find it for review. Contributing doesn’t necessarily always mean writing apatch from scratch. Reviewing existing patches is also a very helpfulcontribution. See Triaging tickets for details.