<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Writing your first patch for Django — Django 1.5.9 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.5.9',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Django 1.5.9 documentation" href="../index.html" />
<link rel="up" title="Getting started" href="index.html" />
<link rel="next" title="Using Django" href="../topics/index.html" />
<link rel="prev" title="What to read next" href="whatsnext.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.5.9 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="whatsnext.html" title="What to read next">previous</a>
|
<a href="index.html" title="Getting started" accesskey="U">up</a>
|
<a href="../topics/index.html" title="Using Django">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="intro-contributing">
<div class="section" id="s-writing-your-first-patch-for-django">
<span id="writing-your-first-patch-for-django"></span><h1>Writing your first patch for Django<a class="headerlink" href="#writing-your-first-patch-for-django" title="Permalink to this headline">¶</a></h1>
<div class="section" id="s-introduction">
<span id="introduction"></span><h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>Contributing back to Django itself is the best way to see your own concerns
addressed. This may seem daunting at first, but it’s really pretty simple.
We’ll walk you through the entire process, so you can learn by example.</p>
<div class="section" id="s-who-s-this-tutorial-for">
<span id="who-s-this-tutorial-for"></span><h3>Who’s this tutorial for?<a class="headerlink" href="#who-s-this-tutorial-for" title="Permalink to this headline">¶</a></h3>
<p>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 <a class="reference internal" href="tutorial01.html"><em>writing your first Django app</em></a>.
In addition, you should have a good understanding of Python itself. But if you
don’t, <a class="reference external" href="http://diveintopython.net/toc/index.html">Dive Into Python</a> is a fantastic (and free) online book for beginning
Python programmers.</p>
<p>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.</p>
<p>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.</p>
<div class="admonition-where-to-get-help admonition">
<p class="first admonition-title">Where to get help:</p>
<p class="last">If you’re having trouble going through this tutorial, please post a message
to <a class="reference external" href="http://groups.google.com/group/django-developers">django-developers</a> or drop by <a class="reference external" href="irc://irc.freenode.net/django-dev">#django-dev on irc.freenode.net</a> to
chat with other Django users who might be able to help.</p>
</div>
</div>
<div class="section" id="s-what-does-this-tutorial-cover">
<span id="what-does-this-tutorial-cover"></span><h3>What does this tutorial cover?<a class="headerlink" href="#what-does-this-tutorial-cover" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<ul class="simple">
<li>Installing Git.</li>
<li>How to download a development copy of Django.</li>
<li>Running Django’s test suite.</li>
<li>Writing a test for your patch.</li>
<li>Writing the code for your patch.</li>
<li>Testing your patch.</li>
<li>Generating a patch file for your changes.</li>
<li>Where to look for more information.</li>
</ul>
<p>Once you’re done with the tutorial, you can look through the rest of
<a class="reference internal" href="../internals/contributing/index.html"><em>Django’s documentation on contributing</em></a>.
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.</p>
</div>
</div>
<div class="section" id="s-installing-git">
<span id="installing-git"></span><h2>Installing Git<a class="headerlink" href="#installing-git" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>To check whether or not you have Git installed, enter <tt class="docutils literal"><span class="pre">git</span></tt> into the command
line. If you get messages saying that this command could be found, you’ll have
to download and install it, see <a class="reference external" href="http://git-scm.com/download">Git’s download page</a>.</p>
<p>If you’re not that familiar with Git, you can always find out more about its
commands (once it’s installed) by typing <tt class="docutils literal"><span class="pre">git</span> <span class="pre">help</span></tt> into the command line.</p>
</div>
<div class="section" id="s-getting-a-copy-of-django-s-development-version">
<span id="getting-a-copy-of-django-s-development-version"></span><h2>Getting a copy of Django’s development version<a class="headerlink" href="#getting-a-copy-of-django-s-development-version" title="Permalink to this headline">¶</a></h2>
<p>The first step to contributing to Django is to get a copy of the source code.
From the command line, use the <tt class="docutils literal"><span class="pre">cd</span></tt> command to navigate to the directory
where you’ll want your local copy of Django to live.</p>
<p>Download the Django source code repository using the following command:</p>
<div class="highlight-python"><pre>git clone https://github.com/django/django.git</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>For users who wish to use <a class="reference external" href="http://www.virtualenv.org">virtualenv</a>, you can use:</p>
<div class="highlight-python"><pre>pip install -e /path/to/your/local/clone/django/</pre>
</div>
<p class="last">(where <tt class="docutils literal"><span class="pre">django</span></tt> is the directory of your clone that contains
<tt class="docutils literal"><span class="pre">setup.py</span></tt>) to link your cloned checkout into a virtual environment. This
is a great option to isolate your development copy of Django from the rest
of your system and avoids potential package conflicts.</p>
</div>
</div>
<div class="section" id="s-rolling-back-to-a-previous-revision-of-django">
<span id="rolling-back-to-a-previous-revision-of-django"></span><h2>Rolling back to a previous revision of Django<a class="headerlink" href="#rolling-back-to-a-previous-revision-of-django" title="Permalink to this headline">¶</a></h2>
<p>For this tutorial, we’ll be using <a class="reference external" href="https://code.djangoproject.com/ticket/17549">ticket #17549</a> as a case study, so we’ll
rewind Django’s version history in git to before that ticket’s patch was
applied. This will allow us to go through all of the steps involved in writing
that patch from scratch, including running Django’s test suite.</p>
<p><strong>Keep in mind that while we’ll be using an older revision of Django’s trunk
for the purposes of the tutorial below, you should always use the current
development revision of Django when working on your own patch for a ticket!</strong></p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The patch for this ticket was written by Ulrich Petri, and it was applied
to Django as <a class="reference external" href="https://github.com/django/django/commit/ac2052ebc84c45709ab5f0f25e685bf656ce79bc">commit ac2052ebc84c45709ab5f0f25e685bf656ce79bc</a>.
Consequently, we’ll be using the revision of Django just prior to that,
<a class="reference external" href="https://github.com/django/django/commit/39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac">commit 39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac</a>.</p>
</div>
<p>Navigate into Django’s root directory (that’s the one that contains <tt class="docutils literal"><span class="pre">django</span></tt>,
<tt class="docutils literal"><span class="pre">docs</span></tt>, <tt class="docutils literal"><span class="pre">tests</span></tt>, <tt class="docutils literal"><span class="pre">AUTHORS</span></tt>, etc.). You can then check out the older
revision of Django that we’ll be using in the tutorial below:</p>
<div class="highlight-python"><pre>git checkout 39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac</pre>
</div>
</div>
<div class="section" id="s-running-django-s-test-suite-for-the-first-time">
<span id="running-django-s-test-suite-for-the-first-time"></span><h2>Running Django’s test suite for the first time<a class="headerlink" href="#running-django-s-test-suite-for-the-first-time" title="Permalink to this headline">¶</a></h2>
<p>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
haven’t completely broken Django. If you’ve never run Django’s test suite
before, it’s a good idea to run it once beforehand just to get familiar with
what its output is supposed to look like.</p>
<p>We can run the test suite by simply <tt class="docutils literal"><span class="pre">cd</span></tt>-ing into the Django <tt class="docutils literal"><span class="pre">tests/</span></tt>
directory and, if you’re using GNU/Linux, Mac OS X or some other flavor of
Unix, run:</p>
<div class="highlight-python"><pre>PYTHONPATH=.. python runtests.py --settings=test_sqlite</pre>
</div>
<p>If you’re on Windows, the above should work provided that you are using
“Git Bash” provided by the default Git install. GitHub has a <a class="reference external" href="https://help.github.com/articles/set-up-git#platform-windows">nice tutorial</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you’re using <tt class="docutils literal"><span class="pre">virtualenv</span></tt>, you can omit <tt class="docutils literal"><span class="pre">PYTHONPATH=..</span></tt> when running
the tests. This instructs Python to look for Django in the parent directory
of <tt class="docutils literal"><span class="pre">tests</span></tt>. <tt class="docutils literal"><span class="pre">virtualenv</span></tt> puts your copy of Django on the <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt>
automatically.</p>
</div>
<p>Now sit back and relax. Django’s entire test suite has over 4800 different
tests, so it can take anywhere from 5 to 15 minutes to run, depending on the
speed of your computer.</p>
<p>While Django’s test suite is running, you’ll see a stream of characters
representing the status of each test as it’s run. <tt class="docutils literal"><span class="pre">E</span></tt> indicates that an error
was raised during a test, and <tt class="docutils literal"><span class="pre">F</span></tt> indicates that a test’s assertions failed.
Both of these are considered to be test failures. Meanwhile, <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">s</span></tt>
indicated expected failures and skipped tests, respectively. Dots indicate
passing tests.</p>
<p>Skipped tests are typically due to missing external libraries required to run
the test; see <a class="reference internal" href="../internals/contributing/writing-code/unit-tests.html#running-unit-tests-dependencies"><em>Running all the tests</em></a> 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).</p>
<p>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 <strong>should</strong> pass. If you get failures or
errors make sure you’ve followed all of the previous steps properly. See
<a class="reference internal" href="../internals/contributing/writing-code/unit-tests.html#running-unit-tests"><em>Running the unit tests</em></a> for more information.</p>
<p>Note that the latest Django trunk may not always be stable. When developing
against trunk, you can check <a class="reference external" href="http://ci.djangoproject.com/">Django’s continuous integration builds</a> 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.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For this tutorial and the ticket we’re working on, testing against SQLite
is sufficient, however, it’s possible (and sometimes necessary) to
<a class="reference internal" href="../internals/contributing/writing-code/unit-tests.html#running-unit-tests-settings"><em>run the tests using a different database</em></a>.</p>
</div>
</div>
<div class="section" id="s-writing-some-tests-for-your-ticket">
<span id="writing-some-tests-for-your-ticket"></span><h2>Writing some tests for your ticket<a class="headerlink" href="#writing-some-tests-for-your-ticket" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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
<a class="reference external" href="http://en.wikipedia.org/wiki/Test-driven_development">test-driven development</a> 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.</p>
<p>Now for our hands-on example.</p>
<div class="section" id="s-writing-some-tests-for-ticket-17549">
<span id="writing-some-tests-for-ticket-17549"></span><h3>Writing some tests for ticket #17549<a class="headerlink" href="#writing-some-tests-for-ticket-17549" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="https://code.djangoproject.com/ticket/17549">Ticket #17549</a> describes the following, small feature addition:</p>
<blockquote>
<div>It’s useful for URLField to give you a way to open the URL; otherwise you
might as well use a CharField.</div></blockquote>
<p>In order to resolve this ticket, we’ll add a <tt class="docutils literal"><span class="pre">render</span></tt> method to the
<tt class="docutils literal"><span class="pre">AdminURLFieldWidget</span></tt> in order to display a clickable link above the input
widget. Before we make those changes though, we’re going to write a couple
tests to verify that our modification functions correctly and continues to
function correctly in the future.</p>
<p>Navigate to Django’s <tt class="docutils literal"><span class="pre">tests/regressiontests/admin_widgets/</span></tt> folder and
open the <tt class="docutils literal"><span class="pre">tests.py</span></tt> file. Add the following code on line 269 right before the
<tt class="docutils literal"><span class="pre">AdminFileWidgetTest</span></tt> class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">AdminURLWidgetTest</span><span class="p">(</span><span class="n">DjangoTestCase</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">test_render</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">w</span> <span class="o">=</span> <span class="n">widgets</span><span class="o">.</span><span class="n">AdminURLFieldWidget</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertHTMLEqual</span><span class="p">(</span>
<span class="n">conditional_escape</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="s">''</span><span class="p">)),</span>
<span class="s">'<input class="vURLField" name="test" type="text" />'</span>
<span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertHTMLEqual</span><span class="p">(</span>
<span class="n">conditional_escape</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="s">'http://example.com'</span><span class="p">)),</span>
<span class="s">'<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>'</span>
<span class="p">)</span>
<span class="k">def</span> <span class="nf">test_render_idn</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">w</span> <span class="o">=</span> <span class="n">widgets</span><span class="o">.</span><span class="n">AdminURLFieldWidget</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertHTMLEqual</span><span class="p">(</span>
<span class="n">conditional_escape</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="s">'http://example-äüö.com'</span><span class="p">)),</span>
<span class="s">'<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>'</span>
<span class="p">)</span>
<span class="k">def</span> <span class="nf">test_render_quoting</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">w</span> <span class="o">=</span> <span class="n">widgets</span><span class="o">.</span><span class="n">AdminURLFieldWidget</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertHTMLEqual</span><span class="p">(</span>
<span class="n">conditional_escape</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="s">'http://example.com/<sometag>some text</sometag>'</span><span class="p">)),</span>
<span class="s">'<p class="url">Currently:<a href="http://example.com/%3Csometag</span><span class="si">%3E</span><span class="s">some%20text%3C/sometag</span><span class="si">%3E</span><span class="s">">http://example.com/&lt;sometag&gt;some text&lt;/sometag&gt;</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com/<sometag>some text</sometag>" /></p>'</span>
<span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertHTMLEqual</span><span class="p">(</span>
<span class="n">conditional_escape</span><span class="p">(</span><span class="n">w</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'test'</span><span class="p">,</span> <span class="s">'http://example-äüö.com/<sometag>some text</sometag>'</span><span class="p">)),</span>
<span class="s">'<p class="url">Currently:<a href="http://xn--example--7za4pnc.com/%3Csometag</span><span class="si">%3E</span><span class="s">some%20text%3C/sometag</span><span class="si">%3E</span><span class="s">">http://example-äüö.com/&lt;sometag&gt;some text&lt;/sometag&gt;</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com/<sometag>some text</sometag>" /></p>'</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The new tests check to see that the <tt class="docutils literal"><span class="pre">render</span></tt> method we’ll be adding works
correctly in a couple different situations.</p>
<div class="admonition-but-this-testing-thing-looks-kinda-hard admonition">
<p class="first admonition-title">But this testing thing looks kinda hard...</p>
<p>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 <em>very</em> big subject in
computer programming, so there’s lots of information out there:</p>
<ul class="last simple">
<li>A good first look at writing tests for Django can be found in the
documentation on <a class="reference internal" href="../topics/testing/overview.html"><em>Testing Django applications</em></a>.</li>
<li>Dive Into Python (a free online book for beginning Python developers)
includes a great <a class="reference external" href="http://diveintopython.net/unit_testing/index.html">introduction to Unit Testing</a>.</li>
<li>After reading those, if you want something a little meatier to sink
your teeth into, there’s always the <a class="reference external" href="http://docs.python.org/library/unittest.html">Python unittest documentation</a>.</li>
</ul>
</div>
</div>
<div class="section" id="s-running-your-new-test">
<span id="running-your-new-test"></span><h3>Running your new test<a class="headerlink" href="#running-your-new-test" title="Permalink to this headline">¶</a></h3>
<p>Remember that we haven’t actually made any modifications to
<tt class="docutils literal"><span class="pre">AdminURLFieldWidget</span></tt> yet, so our tests are going to fail. Let’s run all the
tests in the <tt class="docutils literal"><span class="pre">model_forms_regress</span></tt> folder to make sure that’s really what
happens. From the command line, <tt class="docutils literal"><span class="pre">cd</span></tt> into the Django <tt class="docutils literal"><span class="pre">tests/</span></tt> directory
and run:</p>
<div class="highlight-python"><pre>PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets</pre>
</div>
<p>If the tests ran correctly, you should see three failures corresponding to each
of the test methods we added. 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
class.</p>
</div>
</div>
<div class="section" id="s-writing-the-code-for-your-ticket">
<span id="writing-the-code-for-your-ticket"></span><h2>Writing the code for your ticket<a class="headerlink" href="#writing-the-code-for-your-ticket" title="Permalink to this headline">¶</a></h2>
<p>Next we’ll be adding the functionality described in <a class="reference external" href="https://code.djangoproject.com/ticket/17549">ticket #17549</a> to Django.</p>
<div class="section" id="s-writing-the-code-for-ticket-17549">
<span id="writing-the-code-for-ticket-17549"></span><h3>Writing the code for ticket #17549<a class="headerlink" href="#writing-the-code-for-ticket-17549" title="Permalink to this headline">¶</a></h3>
<p>Navigate to the <tt class="docutils literal"><span class="pre">django/django/contrib/admin/</span></tt> folder and open the
<tt class="docutils literal"><span class="pre">widgets.py</span></tt> file. Find the <tt class="docutils literal"><span class="pre">AdminURLFieldWidget</span></tt> class on line 302 and add
the following <tt class="docutils literal"><span class="pre">render</span></tt> method after the existing <tt class="docutils literal"><span class="pre">__init__</span></tt> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">render</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
<span class="n">html</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">AdminURLFieldWidget</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">attrs</span><span class="p">)</span>
<span class="k">if</span> <span class="n">value</span><span class="p">:</span>
<span class="n">value</span> <span class="o">=</span> <span class="n">force_text</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_format_value</span><span class="p">(</span><span class="n">value</span><span class="p">))</span>
<span class="n">final_attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s">'href'</span><span class="p">:</span> <span class="n">mark_safe</span><span class="p">(</span><span class="n">smart_urlquote</span><span class="p">(</span><span class="n">value</span><span class="p">))}</span>
<span class="n">html</span> <span class="o">=</span> <span class="n">format_html</span><span class="p">(</span>
<span class="s">'<p class="url">{0} <a {1}>{2}</a><br />{3} {4}</p>'</span><span class="p">,</span>
<span class="n">_</span><span class="p">(</span><span class="s">'Currently:'</span><span class="p">),</span> <span class="n">flatatt</span><span class="p">(</span><span class="n">final_attrs</span><span class="p">),</span> <span class="n">value</span><span class="p">,</span>
<span class="n">_</span><span class="p">(</span><span class="s">'Change:'</span><span class="p">),</span> <span class="n">html</span>
<span class="p">)</span>
<span class="k">return</span> <span class="n">html</span>
</pre></div>
</div>
</div>
<div class="section" id="s-verifying-your-test-now-passes">
<span id="verifying-your-test-now-passes"></span><h3>Verifying your test now passes<a class="headerlink" href="#verifying-your-test-now-passes" title="Permalink to this headline">¶</a></h3>
<p>Once you’re done modifying Django, we need to make sure that the tests we wrote
earlier pass, so we can see whether the code we wrote above is working
correctly. To run the tests in the <tt class="docutils literal"><span class="pre">admin_widgets</span></tt> folder, <tt class="docutils literal"><span class="pre">cd</span></tt> into the
Django <tt class="docutils literal"><span class="pre">tests/</span></tt> directory and run:</p>
<div class="highlight-python"><pre>PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets</pre>
</div>
<p>Oops, good thing we wrote those tests! You should still see 3 failures with
the following exception:</p>
<div class="highlight-python"><pre>NameError: global name 'smart_urlquote' is not defined</pre>
</div>
<p>We forgot to add the import for that method. Go ahead and add the
<tt class="docutils literal"><span class="pre">smart_urlquote</span></tt> import at the end of line 13 of
<tt class="docutils literal"><span class="pre">django/contrib/admin/widgets.py</span></tt> so it looks as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.utils.html</span> <span class="kn">import</span> <span class="n">escape</span><span class="p">,</span> <span class="n">format_html</span><span class="p">,</span> <span class="n">format_html_join</span><span class="p">,</span> <span class="n">smart_urlquote</span>
</pre></div>
</div>
<p>Re-run the tests and everything should pass. If it doesn’t, make sure you
correctly modified the <tt class="docutils literal"><span class="pre">AdminURLFieldWidget</span></tt> class as shown above and
copied the new tests correctly.</p>
</div>
</div>
<div class="section" id="s-running-django-s-test-suite-for-the-second-time">
<span id="running-django-s-test-suite-for-the-second-time"></span><h2>Running Django’s test suite for the second time<a class="headerlink" href="#running-django-s-test-suite-for-the-second-time" title="Permalink to this headline">¶</a></h2>
<p>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 just 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.</p>
<p>To run the entire Django test suite, <tt class="docutils literal"><span class="pre">cd</span></tt> into the Django <tt class="docutils literal"><span class="pre">tests/</span></tt>
directory and run:</p>
<div class="highlight-python"><pre>PYTHONPATH=.. python runtests.py --settings=test_sqlite</pre>
</div>
<p>As long as you don’t see any failures, you’re good to go. Note that this fix
also made a <a class="reference external" href="https://github.com/django/django/commit/ac2052ebc84c45709ab5f0f25e685bf656ce79bc#diff-0">small CSS change</a> to format the new widget. You can make the
change if you’d like, but we’ll skip it for now in the interest of brevity.</p>
</div>
<div class="section" id="s-writing-documentation">
<span id="writing-documentation"></span><h2>Writing Documentation<a class="headerlink" href="#writing-documentation" title="Permalink to this headline">¶</a></h2>
<p>This is a new feature, so it should be documented. Add the following on line
925 of <tt class="docutils literal"><span class="pre">django/docs/ref/models/fields.txt</span></tt> beneath the existing docs for
<tt class="docutils literal"><span class="pre">URLField</span></tt>:</p>
<div class="highlight-python"><pre>.. versionadded:: 1.5
The current value of the field will be displayed as a clickable link above the
input widget.</pre>
</div>
<p>For more information on writing documentation, including an explanation of what
the <tt class="docutils literal"><span class="pre">versionadded</span></tt> bit is all about, see
<a class="reference internal" href="../internals/contributing/writing-documentation.html"><em>Writing documentation</em></a>. 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.</p>
</div>
<div class="section" id="s-generating-a-patch-for-your-changes">
<span id="generating-a-patch-for-your-changes"></span><h2>Generating a patch for your changes<a class="headerlink" href="#generating-a-patch-for-your-changes" title="Permalink to this headline">¶</a></h2>
<p>Now it’s time to generate a patch file that can be uploaded to Trac or applied
to another copy of Django. To get a look at the content of your patch, run the
following command:</p>
<div class="highlight-python"><pre>git diff</pre>
</div>
<p>This will display the differences between your current copy of Django (with
your changes) and the revision that you initially checked out earlier in the
tutorial.</p>
<p>Once you’re done looking at the patch, hit the <tt class="docutils literal"><span class="pre">q</span></tt> key to exit back to the
command line. If the patch’s content looked okay, you can run the following
command to save the patch file to your current working directory:</p>
<div class="highlight-python"><pre>git diff > 17549.diff</pre>
</div>
<p>You should now have a file in the root Django directory called <tt class="docutils literal"><span class="pre">17549.diff</span></tt>.
This patch file contains all your changes and should look this:</p>
<div class="highlight-diff"><div class="highlight"><pre><span class="gh">diff --git a/django/contrib/admin/widgets.py b/django/contrib/admin/widgets.py</span>
<span class="gh">index 1e0bc2d..9e43a10 100644</span>
<span class="gd">--- a/django/contrib/admin/widgets.py</span>
<span class="gi">+++ b/django/contrib/admin/widgets.py</span>
<span class="gu">@@ -10,7 +10,7 @@ from django.contrib.admin.templatetags.admin_static import static</span>
from django.core.urlresolvers import reverse
from django.forms.widgets import RadioFieldRenderer
from django.forms.util import flatatt
<span class="gd">-from django.utils.html import escape, format_html, format_html_join</span>
<span class="gi">+from django.utils.html import escape, format_html, format_html_join, smart_urlquote</span>
from django.utils.text import Truncator
from django.utils.translation import ugettext as _
from django.utils.safestring import mark_safe
<span class="gu">@@ -306,6 +306,18 @@ class AdminURLFieldWidget(forms.TextInput):</span>
final_attrs.update(attrs)
super(AdminURLFieldWidget, self).__init__(attrs=final_attrs)
<span class="gi">+ def render(self, name, value, attrs=None):</span>
<span class="gi">+ html = super(AdminURLFieldWidget, self).render(name, value, attrs)</span>
<span class="gi">+ if value:</span>
<span class="gi">+ value = force_text(self._format_value(value))</span>
<span class="gi">+ final_attrs = {'href': mark_safe(smart_urlquote(value))}</span>
<span class="gi">+ html = format_html(</span>
<span class="gi">+ '<p class="url">{0} <a {1}>{2}</a><br />{3} {4}</p>',</span>
<span class="gi">+ _('Currently:'), flatatt(final_attrs), value,</span>
<span class="gi">+ _('Change:'), html</span>
<span class="gi">+ )</span>
<span class="gi">+ return html</span>
<span class="gi">+</span>
class AdminIntegerFieldWidget(forms.TextInput):
class_name = 'vIntegerField'
<span class="gh">diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt</span>
<span class="gh">index 809d56e..d44f85f 100644</span>
<span class="gd">--- a/docs/ref/models/fields.txt</span>
<span class="gi">+++ b/docs/ref/models/fields.txt</span>
<span class="gu">@@ -922,6 +922,10 @@ Like all :class:`CharField` subclasses, :class:`URLField` takes the optional</span>
:attr:`~CharField.max_length`argument. If you don't specify
:attr:`~CharField.max_length`, a default of 200 is used.
<span class="gi">+.. versionadded:: 1.5</span>
<span class="gi">+</span>
<span class="gi">+The current value of the field will be displayed as a clickable link above the</span>
<span class="gi">+input widget.</span>
Relationship fields
===================
<span class="gh">diff --git a/tests/regressiontests/admin_widgets/tests.py b/tests/regressiontests/admin_widgets/tests.py</span>
<span class="gh">index 4b11543..94acc6d 100644</span>
<span class="gd">--- a/tests/regressiontests/admin_widgets/tests.py</span>
<span class="gi">+++ b/tests/regressiontests/admin_widgets/tests.py</span>
<span class="gu">@@ -265,6 +265,35 @@ class AdminSplitDateTimeWidgetTest(DjangoTestCase):</span>
'<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>',
)
<span class="gi">+class AdminURLWidgetTest(DjangoTestCase):</span>
<span class="gi">+ def test_render(self):</span>
<span class="gi">+ w = widgets.AdminURLFieldWidget()</span>
<span class="gi">+ self.assertHTMLEqual(</span>
<span class="gi">+ conditional_escape(w.render('test', '')),</span>
<span class="gi">+ '<input class="vURLField" name="test" type="text" />'</span>
<span class="gi">+ )</span>
<span class="gi">+ self.assertHTMLEqual(</span>
<span class="gi">+ conditional_escape(w.render('test', 'http://example.com')),</span>
<span class="gi">+ '<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>'</span>
<span class="gi">+ )</span>
<span class="gi">+</span>
<span class="gi">+ def test_render_idn(self):</span>
<span class="gi">+ w = widgets.AdminURLFieldWidget()</span>
<span class="gi">+ self.assertHTMLEqual(</span>
<span class="gi">+ conditional_escape(w.render('test', 'http://example-äüö.com')),</span>
<span class="gi">+ '<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>'</span>
<span class="gi">+ )</span>
<span class="gi">+</span>
<span class="gi">+ def test_render_quoting(self):</span>
<span class="gi">+ w = widgets.AdminURLFieldWidget()</span>
<span class="gi">+ self.assertHTMLEqual(</span>
<span class="gi">+ conditional_escape(w.render('test', 'http://example.com/<sometag>some text</sometag>')),</span>
<span class="gi">+ '<p class="url">Currently:<a href="http://example.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example.com/&lt;sometag&gt;some text&lt;/sometag&gt;</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example.com/<sometag>some text</sometag>" /></p>'</span>
<span class="gi">+ )</span>
<span class="gi">+ self.assertHTMLEqual(</span>
<span class="gi">+ conditional_escape(w.render('test', 'http://example-äüö.com/<sometag>some text</sometag>')),</span>
<span class="gi">+ '<p class="url">Currently:<a href="http://xn--example--7za4pnc.com/%3Csometag%3Esome%20text%3C/sometag%3E">http://example-äüö.com/&lt;sometag&gt;some text&lt;/sometag&gt;</a><br />Change:<input class="vURLField" name="test" type="text" value="http://example-äüö.com/<sometag>some text</sometag>" /></p>'</span>
<span class="gi">+ )</span>
class AdminFileWidgetTest(DjangoTestCase):
def test_render(self):
</pre></div>
</div>
</div>
<div class="section" id="s-so-what-do-i-do-next">
<span id="so-what-do-i-do-next"></span><h2>So what do I do next?<a class="headerlink" href="#so-what-do-i-do-next" title="Permalink to this headline">¶</a></h2>
<p>Congratulations, you’ve generated your very first Django patch! Now that you’ve
got that under your belt, you can put those skills to good use by helping to
improve Django’s codebase. Generating patches and attaching them to Trac
tickets is useful, however, since we are using git - adopting a more <a class="reference internal" href="../internals/contributing/writing-code/working-with-git.html"><em>git
oriented workflow</em></a> is
recommended.</p>
<p>Since we never committed our changes locally, perform the following to get your
git branch back to a good starting point:</p>
<div class="highlight-python"><pre>git reset --hard HEAD
git checkout master</pre>
</div>
<div class="section" id="s-more-information-for-new-contributors">
<span id="more-information-for-new-contributors"></span><h3>More information for new contributors<a class="headerlink" href="#more-information-for-new-contributors" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<ul class="simple">
<li>You should make sure to read Django’s documentation on
<a class="reference internal" href="../internals/contributing/writing-code/submitting-patches.html"><em>claiming tickets and submitting patches</em></a>.
It covers Trac etiquette, how to claim tickets for yourself, expected
coding style for patches, and many other important details.</li>
<li>First time contributors should also read Django’s <a class="reference internal" href="../internals/contributing/new-contributors.html"><em>documentation
for first time contributors</em></a>.
It has lots of good advice for those of us who are new to helping out
with Django.</li>
<li>After those, if you’re still hungry for more information about
contributing, you can always browse through the rest of
<a class="reference internal" href="../internals/contributing/index.html"><em>Django’s documentation on contributing</em></a>.
It contains a ton of useful information and should be your first source
for answering any questions you might have.</li>
</ul>
</div>
<div class="section" id="s-finding-your-first-real-ticket">
<span id="finding-your-first-real-ticket"></span><h3>Finding your first real ticket<a class="headerlink" href="#finding-your-first-real-ticket" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>If you just want to get started already (and nobody would blame you!), try
taking a look at the list of <a class="reference external" href="https://code.djangoproject.com/query?status=new&status=reopened&has_patch=0&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority">easy tickets that need patches</a> and the
<a class="reference external" href="https://code.djangoproject.com/query?status=new&status=reopened&needs_better_patch=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority">easy tickets that have patches which need improvement</a>. If you’re familiar
with writing tests, you can also look at the list of
<a class="reference external" href="https://code.djangoproject.com/query?status=new&status=reopened&needs_tests=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority">easy tickets that need tests</a>. Just remember to follow the guidelines about
claiming tickets that were mentioned in the link to Django’s documentation on
<a class="reference internal" href="../internals/contributing/writing-code/submitting-patches.html"><em>claiming tickets and submitting patches</em></a>.</p>
</div>
<div class="section" id="s-what-s-next">
<span id="what-s-next"></span><h3>What’s next?<a class="headerlink" href="#what-s-next" title="Permalink to this headline">¶</a></h3>
<p>After a ticket has a patch, it needs to be reviewed by a second set of eyes.
After uploading a patch or submitting a pull request, be sure to 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
<a class="reference internal" href="../internals/contributing/triaging-tickets.html"><em>Triaging tickets</em></a> for details.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Writing your first patch for Django</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a><ul>
<li><a class="reference internal" href="#who-s-this-tutorial-for">Who’s this tutorial for?</a></li>
<li><a class="reference internal" href="#what-does-this-tutorial-cover">What does this tutorial cover?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing-git">Installing Git</a></li>
<li><a class="reference internal" href="#getting-a-copy-of-django-s-development-version">Getting a copy of Django’s development version</a></li>
<li><a class="reference internal" href="#rolling-back-to-a-previous-revision-of-django">Rolling back to a previous revision of Django</a></li>
<li><a class="reference internal" href="#running-django-s-test-suite-for-the-first-time">Running Django’s test suite for the first time</a></li>
<li><a class="reference internal" href="#writing-some-tests-for-your-ticket">Writing some tests for your ticket</a><ul>
<li><a class="reference internal" href="#writing-some-tests-for-ticket-17549">Writing some tests for ticket #17549</a></li>
<li><a class="reference internal" href="#running-your-new-test">Running your new test</a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-the-code-for-your-ticket">Writing the code for your ticket</a><ul>
<li><a class="reference internal" href="#writing-the-code-for-ticket-17549">Writing the code for ticket #17549</a></li>
<li><a class="reference internal" href="#verifying-your-test-now-passes">Verifying your test now passes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-django-s-test-suite-for-the-second-time">Running Django’s test suite for the second time</a></li>
<li><a class="reference internal" href="#writing-documentation">Writing Documentation</a></li>
<li><a class="reference internal" href="#generating-a-patch-for-your-changes">Generating a patch for your changes</a></li>
<li><a class="reference internal" href="#so-what-do-i-do-next">So what do I do next?</a><ul>
<li><a class="reference internal" href="#more-information-for-new-contributors">More information for new contributors</a></li>
<li><a class="reference internal" href="#finding-your-first-real-ticket">Finding your first real ticket</a></li>
<li><a class="reference internal" href="#what-s-next">What’s next?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="whatsnext.html">What to read next</a></li>
<li>Next: <a href="../topics/index.html">Using Django</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.5.9 documentation</a>
<ul><li><a href="index.html">Getting started</a>
<ul><li>Writing your first patch for Django</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/intro/contributing.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 19, 2015</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="whatsnext.html" title="What to read next">previous</a>
|
<a href="index.html" title="Getting started" accesskey="U">up</a>
|
<a href="../topics/index.html" title="Using Django">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
