Interested in giving back to the community a little? Maybe you’ve found a bug\nin Django that you’d like to see fixed, or maybe there’s a small feature you\nwant added.
\nContributing back to Django itself is the best way to see your own concerns\naddressed. This may seem daunting at first, but it’s a well-traveled path with\ndocumentation, tooling, and a community to support you. We’ll walk you through\nthe entire process, so you can learn by example.
\nFor this tutorial, we expect that you have at least a basic understanding of\nhow Django works. This means you should be comfortable going through the\nexisting tutorials on writing your first Django app.\nIn addition, you should have a good understanding of Python itself. But if you\ndon’t, Dive Into Python is a fantastic (and free) online book for\nbeginning Python programmers.
\nThose of you who are unfamiliar with version control systems and Trac will find\nthat this tutorial and its links include just enough information to get started.\nHowever, you’ll probably want to read some more about these different tools if\nyou plan on contributing to Django regularly.
\nFor the most part though, this tutorial tries to explain as much as possible,\nso that it can be of use to the widest audience.
\n\nWe’ll be walking you through contributing a patch to Django for the first time.\nBy the end of this tutorial, you should have a basic understanding of both the\ntools and the processes involved. Specifically, we’ll be covering the following:
\nInstalling 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\nDjango’s documentation on contributing.\nIt contains lots of great information and is a must read for anyone who’d like\nto become a regular contributor to Django. If you’ve got questions, it’s\nprobably got the answers.
\n\n\nAs a contributor, you can help us keep the Django community open and inclusive.\nPlease read and follow our Code of Conduct.
\nFor this tutorial, you’ll need Git installed to download the current\ndevelopment version of Django and to generate patch files for the changes you\nmake.
\nTo check whether or not you have Git installed, enter git into the command\nline. If you get messages saying that this command could not be found, you’ll\nhave 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\ncommands (once it’s installed) by typing git help into the command line.
The first step to contributing to Django is to get a copy of the source code.\nFirst, fork Django on GitHub. Then,\nfrom the command line, use the cd command to navigate to the directory\nwhere you’ll want your local copy of Django to live.
Download the Django source code repository using the following command:
\nLinux / macOS
$ git clone https://github.com/YourGitHubName/django.git\nWindows
...\\> git clone https://github.com/YourGitHubName/django.git\nNow that you have a local copy of Django, you can install it just like you would\ninstall any package using pip. The most convenient way to do so is by using\na virtual environment, which is a feature built into Python that allows you\nto keep a separate directory of installed packages for each of your projects so\nthat they don’t interfere with each other.
It’s a good idea to keep all your virtual environments in one place, for\nexample in .virtualenvs/ in your home directory.
Create a new virtual environment by running:
\nLinux / macOS
$ python3 -m venv ~/.virtualenvs/djangodev\nWindows
...\\> py -m venv %HOMEPATH%\\.virtualenvs\\djangodev\nThe path is where the new environment will be saved on your computer.
\nThe final step in setting up your virtual environment is to activate it:
\n$ source ~/.virtualenvs/djangodev/bin/activate\nIf the source command is not available, you can try using a dot instead:
$ . ~/.virtualenvs/djangodev/bin/activate\nYou have to activate the virtual environment whenever you open a new\nterminal window.
\n\nThe name of the currently activated virtual environment is displayed on the\ncommand line to help you keep track of which one you are using. Anything you\ninstall through pip while this name is displayed will be installed in that\nvirtual environment, isolated from other environments and system-wide packages.
Go ahead and install the previously cloned copy of Django:
\nLinux / macOS
$ python -m pip install -e /path/to/your/local/clone/django/\nWindows
...\\> py -m pip install -e \\path\\to\\your\\local\\clone\\django\\\nThe installed version of Django is now pointing at your local copy by installing\nin editable mode. You will immediately see any changes you make to it, which is\nof great help when writing your first patch.
\nIt may be helpful to test your local changes with a Django project. First you\nhave to create a new virtual environment, install the previously cloned\nlocal copy of Django in editable mode,\nand create a new Django project outside of your local copy of Django. You will\nimmediately see any changes you make to Django in your new project, which is\nof great help when writing your first patch, especially if testing any changes\nto the UI.
\nYou can follow the tutorial for help in creating a\nDjango project.
\nWhen contributing to Django it’s very important that your code changes don’t\nintroduce bugs into other areas of Django. One way to check that Django still\nworks after you make your changes is by running Django’s test suite. If all\nthe tests still pass, then you can be reasonably sure that your changes\nwork and haven’t broken other parts of Django. If you’ve never run Django’s test\nsuite before, it’s a good idea to run it once beforehand to get familiar with\nits output.
\nBefore running the test suite, enter the Django tests/ directory using the\ncd tests command, and install test dependencies by running:
Linux / macOS
$ python -m pip install -r requirements/py3.txt\nWindows
...\\> py -m pip install -r requirements\\py3.txt\nIf you encounter an error during the installation, your system might be missing\na dependency for one or more of the Python packages. Consult the failing\npackage’s documentation or search the web with the error message that you\nencounter.
\nNow we are ready to run the test suite. If you’re using GNU/Linux, macOS, or\nsome other flavor of Unix, run:
\nLinux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nNow sit back and relax. Django’s entire test suite has thousands of tests, and\nit takes at least a few minutes to run, depending on the speed of your\ncomputer.
\nWhile Django’s test suite is running, you’ll see a stream of characters\nrepresenting the status of each test as it completes. E indicates that an\nerror was raised during a test, and F indicates that a test’s assertions\nfailed. Both of these are considered to be test failures. Meanwhile, x and\ns indicated expected failures and skipped tests, respectively. Dots indicate\npassing tests.
Skipped tests are typically due to missing external libraries required to run\nthe test; see Running all the tests for a list of dependencies\nand be sure to install any for tests related to the changes you are making (we\nwon’t need any for this tutorial). Some tests are specific to a particular\ndatabase backend and will be skipped if not testing with that backend. SQLite\nis the database backend for the default settings. To run the tests using a\ndifferent backend, see Using another settings module.
\nOnce the tests complete, you should be greeted with a message informing you\nwhether the test suite passed or failed. Since you haven’t yet made any changes\nto Django’s code, the entire test suite should pass. If you get failures or\nerrors make sure you’ve followed all of the previous steps properly. See\nRunning the unit tests for more information.
\nNote that the latest Django “main” branch may not always be stable. When\ndeveloping against “main”, you can check Django’s continuous integration\nbuilds to determine if the failures are specific to your machine or if they\nare also present in Django’s official builds. If you click to view a particular\nbuild, you can view the “Configuration Matrix” which shows failures broken down\nby Python version and database backend.
\n\nFor this tutorial, we’ll work on a “fake ticket” as a case study. Here are the\nimaginary details:
\n\nWe’ll now implement this feature and associated tests.
\nBefore making any changes, create a new branch for the ticket:
\nLinux / macOS
$ git checkout -b ticket_99999\nWindows
...\\> git checkout -b ticket_99999\nYou can choose any name that you want for the branch, “ticket_99999” is an\nexample. All changes made in this branch will be specific to the ticket and\nwon’t affect the main copy of the code that we cloned earlier.
\nIn most cases, for a patch to be accepted into Django it has to include tests.\nFor bug fix patches, this means writing a regression test to ensure that the\nbug is never reintroduced into Django later on. A regression test should be\nwritten in such a way that it will fail while the bug still exists and pass\nonce the bug has been fixed. For patches containing new features, you’ll need\nto include tests which ensure that the new features are working correctly.\nThey too should fail when the new feature is not present, and then pass once it\nhas been implemented.
\nA good way to do this is to write your new tests first, before making any\nchanges to the code. This style of development is called\ntest-driven development and can be applied to both entire projects and\nsingle patches. After writing your tests, you then run them to make sure that\nthey do indeed fail (since you haven’t fixed that bug or added that feature\nyet). If your new tests don’t fail, you’ll need to fix them so that they do.\nAfter all, a regression test that passes regardless of whether a bug is present\nis not very helpful at preventing that bug from reoccurring down the road.
\nNow for our hands-on example.
\nIn order to resolve this ticket, we’ll add a make_toast() function to the\ndjango.shortcuts module. First we are going to write a test that tries to\nuse the function and check that its output looks correct.
Navigate to Django’s tests/shortcuts/ folder and create a new file\ntest_make_toast.py. Add the following code:
from django.shortcuts import make_toast\nfrom django.test import SimpleTestCase\n\n\nclass MakeToastTests(SimpleTestCase):\n def test_make_toast(self):\n self.assertEqual(make_toast(), "toast")\nThis test checks that the make_toast() returns 'toast'.
Since we haven’t made any modifications to django.shortcuts yet, our test\nshould fail. Let’s run all the tests in the shortcuts folder to make sure\nthat’s really what happens. cd to the Django tests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nIf the tests ran correctly, you should see one failure corresponding to the test\nmethod we added, with this error:
\nImportError: cannot import name 'make_toast' from 'django.shortcuts'\nIf all of the tests passed, then you’ll want to make sure that you added the\nnew test shown above to the appropriate folder and file name.
\nNext we’ll be adding the make_toast() function.
Navigate to the django/ folder and open the shortcuts.py file. At the\nbottom, add:
def make_toast():\n return "toast"\nNow we need to make sure that the test we wrote earlier passes, so we can see\nwhether the code we added is working correctly. Again, navigate to the Django\ntests/ directory and run:
Linux / macOS
$ ./runtests.py shortcuts\nWindows
...\\> runtests.py shortcuts\nEverything should pass. If it doesn’t, make sure you correctly added the\nfunction to the correct file.
\nOnce you’ve verified that your patch and your test are working correctly, it’s\na good idea to run the entire Django test suite to verify that your change\nhasn’t introduced any bugs into other areas of Django. While successfully\npassing the entire test suite doesn’t guarantee your code is bug free, it does\nhelp identify many bugs and regressions that might otherwise go unnoticed.
\nTo run the entire Django test suite, cd into the Django tests/\ndirectory and run:
Linux / macOS
$ ./runtests.py\nWindows
...\\> runtests.py \nThis is a new feature, so it should be documented. Open the file\ndocs/topics/http/shortcuts.txt and add the following at the end of the\nfile:
``make_toast()``\n================\n\n.. function:: make_toast()\n\n.. versionadded:: 2.2\n\nReturns ``'toast'``.\nSince this new feature will be in an upcoming release it is also added to the\nrelease notes for the next version of Django. Open the release notes for the\nlatest version in docs/releases/, which at time of writing is 2.2.txt.\nAdd a note under the “Minor Features” header:
:mod:`django.shortcuts`\n~~~~~~~~~~~~~~~~~~~~~~~\n\n* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\nFor more information on writing documentation, including an explanation of what\nthe versionadded bit is all about, see\nWriting documentation. That page also includes\nan explanation of how to build a copy of the documentation locally, so you can\npreview the HTML that will be generated.
Now it’s time to go through all the changes made in our patch. To stage all the\nchanges ready for commit, run:
\nLinux / macOS
$ git add --all\nWindows
...\\> git add --all\nThen display the differences between your current copy of Django (with your\nchanges) and the revision that you initially checked out earlier in the\ntutorial with:
\nLinux / macOS
$ git diff --cached\nWindows
...\\> git diff --cached\nUse the arrow keys to move up and down.
\ndiff --git a/django/shortcuts.py b/django/shortcuts.py\nindex 7ab1df0e9d..8dde9e28d9 100644\n--- a/django/shortcuts.py\n+++ b/django/shortcuts.py\n@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):\n\n # Finally, fall back and assume it's a URL\n return to\n+\n+\n+def make_toast():\n+ return 'toast'\ndiff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt\nindex 7d85d30c4a..81518187b3 100644\n--- a/docs/releases/2.2.txt\n+++ b/docs/releases/2.2.txt\n@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the\n Minor features\n --------------\n\n+:mod:`django.shortcuts`\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.\n+\n :mod:`django.contrib.admin`\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\ndiff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt\nindex 7b3a3a2c00..711bf6bb6d 100644\n--- a/docs/topics/http/shortcuts.txt\n+++ b/docs/topics/http/shortcuts.txt\n@@ -271,3 +271,12 @@ This example is equivalent to::\n my_objects = list(MyModel.objects.filter(published=True))\n if not my_objects:\n raise Http404("No MyModel matches the given query.")\n+\n+``make_toast()``\n+================\n+\n+.. function:: make_toast()\n+\n+.. versionadded:: 2.2\n+\n+Returns ``'toast'``.\ndiff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py\nnew file mode 100644\nindex 0000000000..6f4c627b6e\n--- /dev/null\n+++ b/tests/shortcuts/test_make_toast.py\n@@ -0,0 +1,7 @@\n+from django.shortcuts import make_toast\n+from django.test import SimpleTestCase\n+\n+\n+class MakeToastTests(SimpleTestCase):\n+ def test_make_toast(self):\n+ self.assertEqual(make_toast(), 'toast')\nWhen you’re done previewing the patch, hit the q key to return to the\ncommand line. If the patch’s content looked okay, it’s time to commit the\nchanges.
To commit the changes:
\nLinux / macOS
$ git commit\nWindows
...\\> git commit\nThis opens up a text editor to type the commit message. Follow the commit\nmessage guidelines and write a message like:
\nFixed #99999 -- Added a shortcut function to make toast.\nAfter committing the patch, send it to your fork on GitHub (substitute\n“ticket_99999” with the name of your branch if it’s different):
\nLinux / macOS
$ git push origin ticket_99999\nWindows
...\\> git push origin ticket_99999\nYou can create a pull request by visiting the Django GitHub page. You’ll see your branch under “Your\nrecently pushed branches”. Click “Compare & pull request” next to it.
\nPlease don’t do it for this tutorial, but on the next page that displays a\npreview of the patch, you would click “Create pull request”.
\nCongratulations, you’ve learned how to make a pull request to Django! Details\nof more advanced techniques you may need are in\nWorking with Git and GitHub.
\nNow you can put those skills to good use by helping to improve Django’s\ncodebase.
\nBefore you get too into writing patches for Django, there’s a little more\ninformation on contributing that you should probably take a look at:
\nYou should make sure to read Django’s documentation on\nclaiming tickets and submitting patches.\nIt covers Trac etiquette, how to claim tickets for yourself, expected\ncoding style for patches, and many other important details.
First time contributors should also read Django’s documentation\nfor first time contributors.\nIt has lots of good advice for those of us who are new to helping out\nwith Django.
After those, if you’re still hungry for more information about\ncontributing, you can always browse through the rest of\nDjango’s documentation on contributing.\nIt contains a ton of useful information and should be your first source\nfor answering any questions you might have.
Once you’ve looked through some of that information, you’ll be ready to go out\nand find a ticket of your own to write a patch for. Pay special attention to\ntickets with the “easy pickings” criterion. These tickets are often much\nsimpler in nature and are great for first time contributors. Once you’re\nfamiliar with contributing to Django, you can move on to writing patches for\nmore difficult and complicated tickets.
\nIf you just want to get started already (and nobody would blame you!), try\ntaking a look at the list of easy tickets that need patches and the\neasy tickets that have patches which need improvement. If you’re familiar\nwith writing tests, you can also look at the list of\neasy tickets that need tests. Remember to follow the guidelines about\nclaiming tickets that were mentioned in the link to Django’s documentation on\nclaiming tickets and submitting patches.
\nAfter a ticket has a patch, it needs to be reviewed by a second set of eyes.\nAfter submitting a pull request, update the ticket metadata by setting the\nflags on the ticket to say “has patch”, “doesn’t need tests”, etc, so others\ncan find it for review. Contributing doesn’t necessarily always mean writing a\npatch from scratch. Reviewing existing patches is also a very helpful\ncontribution. See Triaging tickets for details.
\n