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 really pretty simple.\nWe’ll walk you through the 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.
How to download a development copy of Django.
Running Django’s test suite.
Writing a test for your patch.
Writing the code for your patch.
Testing your patch.
Generating a patch file for your changes.
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.
\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 have\nto 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.\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:
\ngit clone https://github.com/django/django.git\nFor this tutorial, we’ll be using ticket #17549 as a case study, so we’ll\nrewind Django’s version history in git to before that ticket’s patch was\napplied. This will allow us to go through all of the steps involved in writing\nthat patch from scratch, including running Django’s test suite.
\nKeep in mind that while we’ll be using an older revision of Django’s trunk\nfor the purposes of the tutorial below, you should always use the current\ndevelopment revision of Django when working on your own patch for a ticket!
\n\nNavigate into Django’s root directory (that’s the one that contains django,\ndocs, tests, AUTHORS, etc.). You can then check out the older\nrevision of Django that we’ll be using in the tutorial below:
git checkout 39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac\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\nhaven’t completely broken Django. If you’ve never run Django’s test suite\nbefore, it’s a good idea to run it once beforehand just to get familiar with\nwhat its output is supposed to look like.
\nWe can run the test suite by simply cd-ing into the Django tests/\ndirectory and, if you’re using GNU/Linux, Mac OS X or some other flavor of\nUnix, run:
PYTHONPATH=.. python runtests.py --settings=test_sqlite\nIf you’re on Windows, the above should work provided that you are using\n“Git Bash” provided by the default Git install. GitHub has a nice tutorial.
\n\nNow sit back and relax. Django’s entire test suite has over 4800 different\ntests, so it can take anywhere from 5 to 15 minutes to run, depending on the\nspeed of your computer.
\nWhile Django’s test suite is running, you’ll see a stream of characters\nrepresenting the status of each test as it’s run. E indicates that an error\nwas raised during a test, and F indicates that a test’s assertions failed.\nBoth of these are considered to be test failures. Meanwhile, x and s\nindicated 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).
\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 trunk may not always be stable. When developing\nagainst trunk, you can check Django’s continuous integration builds to\ndetermine if the failures are specific to your machine or if they are also\npresent in Django’s official builds. If you click to view a particular build,\nyou can view the “Configuration Matrix” which shows failures broken down by\nPython version and database backend.
\n\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.
\nTicket #17549 describes the following, small feature addition:
\n\n\nIt’s useful for URLField to give you a way to open the URL; otherwise you\nmight as well use a CharField.
\n
In order to resolve this ticket, we’ll add a render method to the\nAdminURLFieldWidget in order to display a clickable link above the input\nwidget. Before we make those changes though, we’re going to write a couple\ntests to verify that our modification functions correctly and continues to\nfunction correctly in the future.
Navigate to Django’s tests/regressiontests/admin_widgets/ folder and\nopen the tests.py file. Add the following code on line 269 right before the\nAdminFileWidgetTest class:
class AdminURLWidgetTest(DjangoTestCase):\n def test_render(self):\n w = widgets.AdminURLFieldWidget()\n self.assertHTMLEqual(\n conditional_escape(w.render('test', '')),\n '<input class="vURLField" name="test" type="text" />'\n )\n self.assertHTMLEqual(\n conditional_escape(w.render('test', 'http://example.com')),\n '<p class="url">Currently:<a href="http://example.com">http://example.com</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com" /></p>'\n )\n\n def test_render_idn(self):\n w = widgets.AdminURLFieldWidget()\n self.assertHTMLEqual(\n conditional_escape(w.render('test', 'http://example-äüö.com')),\n '<p class="url">Currently:<a href="http://xn--example--7za4pnc.com">http://example-äüö.com</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com" /></p>'\n )\n\n def test_render_quoting(self):\n w = widgets.AdminURLFieldWidget()\n self.assertHTMLEqual(\n conditional_escape(w.render('test', 'http://example.com/<sometag>some text</sometag>')),\n '<p class="url">Currently:<a href="http://example.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example.com/<sometag>some text</sometag></a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com/<sometag>some text</sometag>" /></p>'\n )\n self.assertHTMLEqual(\n conditional_escape(w.render('test', 'http://example-äüö.com/<sometag>some text</sometag>')),\n '<p class="url">Currently:<a href="http://xn--example--7za4pnc.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example-äüö.com/<sometag>some text</sometag></a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com/<sometag>some text</sometag>" /></p>'\n )\nThe new tests check to see that the render method we’ll be adding works\ncorrectly in a couple different situations.
Remember that we haven’t actually made any modifications to\nAdminURLFieldWidget yet, so our tests are going to fail. Let’s run all the\ntests in the model_forms_regress folder to make sure that’s really what\nhappens. From the command line, cd into the Django tests/ directory\nand run:
PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets\nIf the tests ran correctly, you should see three failures corresponding to each\nof the test methods we added. If all of the tests passed, then you’ll want to\nmake sure that you added the new test shown above to the appropriate folder and\nclass.
\nNext we’ll be adding the functionality described in ticket #17549 to\nDjango.
\nNavigate to the django/django/contrib/admin/ folder and open the\nwidgets.py file. Find the AdminURLFieldWidget class on line 302 and add\nthe following render method after the existing __init__ method:
def render(self, name, value, attrs=None):\n html = super(AdminURLFieldWidget, self).render(name, value, attrs)\n if value:\n value = force_text(self._format_value(value))\n final_attrs = {'href': mark_safe(smart_urlquote(value))}\n html = format_html(\n '<p class="url">{} <a {}>{}</a><br />{} {}</p>',\n _('Currently:'), flatatt(final_attrs), value,\n _('Change:'), html\n )\n return html\nOnce you’re done modifying Django, we need to make sure that the tests we wrote\nearlier pass, so we can see whether the code we wrote above is working\ncorrectly. To run the tests in the admin_widgets folder, cd into the\nDjango tests/ directory and run:
PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets\nOops, good thing we wrote those tests! You should still see 3 failures with\nthe following exception:
\nNameError: global name 'smart_urlquote' is not defined\nWe forgot to add the import for that method. Go ahead and add the\nsmart_urlquote import at the end of line 13 of\ndjango/contrib/admin/widgets.py so it looks as follows:
from django.utils.html import escape, format_html, format_html_join, smart_urlquote\nRe-run the tests and everything should pass. If it doesn’t, make sure you\ncorrectly modified the AdminURLFieldWidget class as shown above and\ncopied the new tests correctly.
Once you’ve verified that your patch and your test are working correctly, it’s\na good idea to run the entire Django test suite just 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:
PYTHONPATH=.. python runtests.py --settings=test_sqlite\nAs long as you don’t see any failures, you’re good to go. Note that this fix\nalso made a small CSS change to format the new widget. You can make the\nchange if you’d like, but we’ll skip it for now in the interest of brevity.
\nThis is a new feature, so it should be documented. Add the following on line\n925 of django/docs/ref/models/fields.txt beneath the existing docs for\nURLField:
.. versionadded:: 1.5\n\n The current value of the field will be displayed as a clickable link above the\n input widget.\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 generate a patch file that can be uploaded to Trac or applied\nto another copy of Django. To get a look at the content of your patch, run the\nfollowing command:
\ngit diff\nThis will display the differences between your current copy of Django (with\nyour changes) and the revision that you initially checked out earlier in the\ntutorial.
\nOnce you’re done looking at the patch, hit the q key to exit back to the\ncommand line. If the patch’s content looked okay, you can run the following\ncommand to save the patch file to your current working directory:
git diff > 17549.diff\nYou should now have a file in the root Django directory called 17549.diff.\nThis patch file contains all your changes and should look this:
diff --git a/django/contrib/admin/widgets.py b/django/contrib/admin/widgets.py\nindex 1e0bc2d..9e43a10 100644\n--- a/django/contrib/admin/widgets.py\n+++ b/django/contrib/admin/widgets.py\n@@ -10,7 +10,7 @@ from django.contrib.admin.templatetags.admin_static import static\n from django.core.urlresolvers import reverse\n from django.forms.widgets import RadioFieldRenderer\n from django.forms.util import flatatt\n-from django.utils.html import escape, format_html, format_html_join\n+from django.utils.html import escape, format_html, format_html_join, smart_urlquote\n from django.utils.text import Truncator\n from django.utils.translation import ugettext as _\n from django.utils.safestring import mark_safe\n@@ -306,6 +306,18 @@ class AdminURLFieldWidget(forms.TextInput):\n final_attrs.update(attrs)\n super(AdminURLFieldWidget, self).__init__(attrs=final_attrs)\n\n+ def render(self, name, value, attrs=None):\n+ html = super(AdminURLFieldWidget, self).render(name, value, attrs)\n+ if value:\n+ value = force_text(self._format_value(value))\n+ final_attrs = {'href': mark_safe(smart_urlquote(value))}\n+ html = format_html(\n+ '<p class="url">{} <a {}>{}</a><br />{} {}</p>',\n+ _('Currently:'), flatatt(final_attrs), value,\n+ _('Change:'), html\n+ )\n+ return html\n+\n class AdminIntegerFieldWidget(forms.TextInput):\n class_name = 'vIntegerField'\n\ndiff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt\nindex 809d56e..d44f85f 100644\n--- a/docs/ref/models/fields.txt\n+++ b/docs/ref/models/fields.txt\n@@ -922,6 +922,10 @@ Like all :class:`CharField` subclasses, :class:`URLField` takes the optional\n :attr:`~CharField.max_length`argument. If you don't specify\n :attr:`~CharField.max_length`, a default of 200 is used.\n\n+.. versionadded:: 1.5\n+\n+The current value of the field will be displayed as a clickable link above the\n+input widget.\n\n Relationship fields\n ===================\ndiff --git a/tests/regressiontests/admin_widgets/tests.py b/tests/regressiontests/admin_widgets/tests.py\nindex 4b11543..94acc6d 100644\n--- a/tests/regressiontests/admin_widgets/tests.py\n+++ b/tests/regressiontests/admin_widgets/tests.py\n\n@@ -265,6 +265,35 @@ class AdminSplitDateTimeWidgetTest(DjangoTestCase):\n '<p class="datetime">Datum: <input value="01.12.2007" type="text" class="vDateField" name="test_0" size="10" /><br />Zeit: <input value="09:30:00" type="text" class="vTimeField" name="test_1" size="8" /></p>',\n )\n\n+class AdminURLWidgetTest(DjangoTestCase):\n+ def test_render(self):\n+ w = widgets.AdminURLFieldWidget()\n+ self.assertHTMLEqual(\n+ conditional_escape(w.render('test', '')),\n+ '<input class="vURLField" name="test" type="text" />'\n+ )\n+ self.assertHTMLEqual(\n+ conditional_escape(w.render('test', 'http://example.com')),\n+ '<p class="url">Currently:<a href="http://example.com">http://example.com</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com" /></p>'\n+ )\n+\n+ def test_render_idn(self):\n+ w = widgets.AdminURLFieldWidget()\n+ self.assertHTMLEqual(\n+ conditional_escape(w.render('test', 'http://example-äüö.com')),\n+ '<p class="url">Currently:<a href="http://xn--example--7za4pnc.com">http://example-äüö.com</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com" /></p>'\n+ )\n+\n+ def test_render_quoting(self):\n+ w = widgets.AdminURLFieldWidget()\n+ self.assertHTMLEqual(\n+ conditional_escape(w.render('test', 'http://example.com/<sometag>some text</sometag>')),\n+ '<p class="url">Currently:<a href="http://example.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example.com/<sometag>some text</sometag></a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com/<sometag>some text</sometag>" /></p>'\n+ )\n+ self.assertHTMLEqual(\n+ conditional_escape(w.render('test', 'http://example-äüö.com/<sometag>some text</sometag>')),\n+ '<p class="url">Currently:<a href="http://xn--example--7za4pnc.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example-äüö.com/<sometag>some text</sometag></a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com/<sometag>some text</sometag>" /></p>'\n+ )\n\n class AdminFileWidgetTest(DjangoTestCase):\n def test_render(self):\nCongratulations, you’ve generated your very first Django patch! Now that you’ve\ngot that under your belt, you can put those skills to good use by helping to\nimprove Django’s codebase. Generating patches and attaching them to Trac\ntickets is useful, however, since we are using git - adopting a more git\noriented workflow is\nrecommended.
\nSince we never committed our changes locally, perform the following to get your\ngit branch back to a good starting point:
\ngit reset --hard HEAD\ngit checkout master\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. Just 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 uploading a patch or submitting a pull request, be sure to update the\nticket metadata by setting the flags on the ticket to say “has patch”,\n“doesn’t need tests”, etc, so others can find it for review. Contributing\ndoesn’t necessarily always mean writing a patch from scratch. Reviewing\nexisting patches is also a very helpful contribution. See\nTriaging tickets for details.
\n