Ticket #16779: contrib-tutorial-5.txt

File contrib-tutorial-5.txt, 26.9 KB (added by taavi223, 4 years ago)
Line 
1===================================
2Writing your first patch for Django
3===================================
4
5Introduction
6============
7
8Now that you've finished writing your first Django app, how about 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.
9
10Contributing 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.
11
12Who's this tutorial for?
13------------------------
14
15For 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 :doc:`writing your first Django app</intro/tutorial01>`. In addition, you should have a good understanding of Python itself. But if you don't, `Dive Into Python`__ is a fantastic (and free) online book for beginning Python programmers.
16
17Those 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.
18
19For the most part though, this tutorial tries to explain as much as possible, so that it can be of use to the widest audience.
20
21.. admonition:: Where to get help:
22
23    If you're having trouble going through this tutorial, please post a message
24    to `django-users`__ or drop by `#django on irc.freenode.net`__ to chat
25    with other Django users who might be able to help.
26
27__ http://diveintopython.org/toc/index.html
28__ http://groups.google.com/group/django-users
29__ irc://irc.freenode.net/django
30
31What does this tutorial cover?
32------------------------------
33
34We'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:
35
36    * Installing Subversion or Git.
37    * How to download a development copy of Django.
38    * Running Django's full test suite.
39    * Writing a test for your patch.
40    * Writing the code for your patch.
41    * Testing your patch.
42    * Generating a patch file for your changes.
43    * Where to look for more information.
44
45Once you're done with the tutorial, you can look through the rest of :doc:`Django's documentation on contributing<internals/contributing/index>`. 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.
46
47Installing Subversion or Git
48=============================
49
50For this tutorial, you'll need to have either Subversion or Git installed. These tools will be used to download the current development version of Django and to generate patch files for the changes you make.
51
52To check whether or not you have one of these tools already installed, enter either ``svn`` or ``git`` into the command line. If you get messages saying that neither of these commands could be found, you'll have to download and install one of them yourself.
53
54You can download and install Subversion from the `Apache's Subversion Binary Packages page`__.
55
56Alternatively, you can download and install Git from `Git's download page`__.
57
58.. note::
59
60    If you're not that familiar with Subversion or Git, you can always find out more about their various commands (once they're installed) by typing either ``svn help`` or ``git help`` into the command line. And of course, `Google`__ is always a great resource.
61
62
63__ http://subversion.apache.org/packages.html
64__ http://git-scm.com/download
65__ http://www.google.com/
66
67Getting a copy of Django's development version
68==============================================
69
70The first step to contributing to Django is to   Django's current development revision using either Subversion or Git. If you're using ``virtualenv``, it's better if you don't use ``pip`` to install Django, since that can cause Django's setup.py script to be run. Just follow the instructions below to use Subversion or Git to check out a copy of Django manually.
71
72From the command line, use the ``cd`` command to navigate to the directory where you'll want your local copy of Django to live.
73
74Using Subversion
75----------------
76
77If you have Subversion installed, you can run the following command to download the current development revision of Django:
78
79.. code-block:: bash
80   
81    svn checkout http://code.djangoproject.com/svn/django/trunk/
82
83Using Git
84---------
85
86Alternatively, if you prefer using Git, you can clone the official Django Git mirror (which is updated from the Subversion repository every five minutes), and then switch to revision 16658 as shown below:
87
88.. code-block:: bash
89
90    git clone https://github.com/django/django.git
91
92Rolling back to a previous revision of Django
93=============================================
94
95For this tutorial, we'll be using `ticket #15315`__ as a case study, so we'll be using an older revision of Django from 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.
96
97**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!**
98       
99.. note::
100
101    The patch for this ticket was generously written by SardarNL and Will Hardy, and it was applied to Django as `changeset 16659`__. Consequently, we'll be using the revision of Django just prior to that, revision 16658.
102
103__ https://code.djangoproject.com/ticket/15315
104__ https://code.djangoproject.com/changeset/16659
105
106Using Subversion
107----------------
108
109If you're using Subversion, run the following command from the same directory you used above to install Django:
110
111.. code-block:: bash
112   
113    svn checkout -r 16658 http://code.djangoproject.com/svn/django/trunk/
114   
115You should now have an older revision installed, that we can use for the tutorial below.
116
117Using Git
118---------
119
120If you're using Git, then navigate into Django's root directory (that's the one that contains ``django``, ``docs``, ``tests``, ``AUTHORS``, etc.) using the ``cd`` command as shown below:
121
122.. code-block:: bash
123   
124    cd django
125
126You can then check out the older revision of Django that we'll be using in the tutorial below:
127
128.. code-block:: bash
129   
130    git checkout 90e8bd48f2
131
132Running Django's test suite for the first time
133==============================================
134
135When 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 stills works after you make your changes is by running Django's entire 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.
136
137
138Setting Django up to run the test suite
139---------------------------------------
140
141Before we can actually run the test suite though, we need to make sure that your new local copy of Django is on your ``PYTHONPATH``; otherwise, the test suite won't run properly. We also need to make sure that there aren't any **other** copies of Django installed somewhere else that are taking priority over your newer copy (this happens more often than you might think). To check for these problems, start up the Python interpreter and follow along with the code below:
142
143.. code-block:: python
144   
145    >>> import django
146    >>> django
147    <module 'django' from '/.../django/__init__.pyc'>
148
149If you get an ``ImportError: No module named django`` after entering the first line, then you'll need to add your new copy of Django to your ``PYTHONPATH``. For more details on how to do this, read :ref:`pointing-python-at-the-new-django-version`.
150
151If you didn't get any errors, then look at the path found in the third line (abbreviated above as ``/.../django/__init__.pyc``). If that isn't the directory that you put Django into earlier in this tutorial, then there is **another** copy of Django on your ``PYTHONPATH`` that is taking priority over the newer copy.  You'll either have to remove this older copy from your ``PYTHONPATH``, or add your new copy to the beginning of your ``PYTHONPATH`` so that it takes priority.
152
153.. note::
154
155    If you're a savvy Djangonaut you might be thinking that using ``virtualenv`` would work perfectly for this type of thing, and you'd be right (+100 bonus points). Using ``virtualenv`` with the ``--no-site-packages`` option isolates your local copy of Django from the rest of your system and avoids potential conflicts.
156   
157    Make sure you don't use ``pip`` to install Django, since that causes Django's setup.py script to be run. If you do, you'll lose Django's root directory and end up with only the code installed. So you'll still need to use Subversion or Git to check out a copy of Django, and then :ref:`manually add it to your PYTHONPATH<pointing-python-at-the-new-django-version>`.
158
159Running the full test suite
160---------------------------
161
162Once Django is setup properly, we can actually run the test suite. Simply ``cd`` into the Django ``tests/`` directory and run:
163
164.. code-block:: bash
165
166    ./runtests.py --settings=test_sqlite
167
168If you get an ``ImportError: No module named django.contrib`` error, you still need to add your current copy of Django to your ``PYTHONPATH``. For more details on how to do this, read :ref:`pointing-python-at-the-new-django-version`.
169
170Otherwise, sit back and relax. Django's entire test suite has over 4000 different tests, so it can take anywhere from 5 to 15 minutes to run, depending on the speed of your computer.
171
172.. note::
173   
174    While Django's test suite is running, you'll see a stream of characters representing the status of each test as it's run. ``E`` indicates that an error was raised during a test, and ``F`` indicates that a test's assertions failed. Both of these are considered to be test failures. Meanwhile, ``x`` and ``s`` indicated expected failures and skipped tests, respectively.  Dots indicate passing tests.
175
176Once the process is done, you should be greeted with a message informing you whether the test suite passed or failed. Since you haven't yet made any changes to Django's code, the entire test suite **should** pass.  If it doesn't, make sure you've followed all of the previous steps properly.
177
178More information on running the test suite can be found in the :doc:`Django's online documentation</internals/contributing/writing-code/unit-tests>`.
179
180Writing a test for your ticket
181==============================
182
183In 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.
184
185A good way to do this is to write your new tests first, before making any changes to the code. This style of development is called `test-driven development`__ and can be applied to both entire projects and single patches. After writing your tests, you then run them to make sure that they do indeed fail (since you haven't fixed that bug or added that feature yet). If your new tests don't fail, you'll need to fix them so that they do. After all, a regression test that passes regardless of whether a bug is present is not very helpful at preventing that bug from reoccurring down the road.
186
187Now for our hands on example.
188
189__ http://en.wikipedia.org/wiki/Test-driven_development
190
191Writing a test for ticket #15315
192--------------------------------
193
194`Ticket #15315`__ describes the following, small feature addition:
195   
196    Since Django 1.2, the ``ModelForm`` class can override widgets by specifying a ``'widgets'`` attribute in ``Meta``, similar to ``'fields'`` or ``'exclude'``. The ``modelform_factory`` function doesn't have any way to specify widgets directly, so the only option is to define a new ``ModelForm`` subclass with a ``'widget'`` attribute in ``Meta``, and then pass that class to ``modelform_factory`` using the ``'form'`` argument. This is more complex than it needs to be.
197
198    The fix is to add a new keyword argument ``widgets=None`` to ``modelform_factory``.
199   
200In order to resolve this ticket, we'll modify the ``modelform_factory`` function to accept a ``widgets`` keyword argument. Before we make those changes though, we're going to write a test to verify that our modification functions correctly and continues to function correctly in the future.
201
202Navigate to Django's ``tests/regressiontests/model_forms_regress/`` folder and open the ``tests.py`` file. Find the :class:`FormFieldCallbackTests` class on line 264 and add the ``test_factory_with_widget_argument`` test to it as shown below:
203
204.. code-block:: python
205   
206    class FormFieldCallbackTests(TestCase):
207   
208        def test_factory_with_widget_argument(self):
209            """ Regression for #15315: modelform_factory should accept widgets
210                argument
211            """
212            widget = forms.Textarea()
213           
214            # Without the widget, the form field should not have the widget set to a textarea
215            Form = modelform_factory(Person)
216            self.assertNotEqual(Form.base_fields['name'].widget.__class__, forms.Textarea)
217           
218            # With a widget, the form field should have the widget set to a textarea
219            Form = modelform_factory(Person, widgets={'name':widget})
220            self.assertEqual(Form.base_fields['name'].widget.__class__, forms.Textarea)
221       
222        def test_baseform_with_widgets_in_meta(self):
223            ...
224
225This test checks to see if the function ``modelform_factory`` accepts the new widgets argument specifying what widgets to use for each field. It also makes sure that those form fields are using the specified widgets. Now we have the test for our patch written.
226
227.. admonition:: But this testing thing looks kinda hard...
228   
229    If you've never had to deal with tests before, they can look a little hard to write at first glance. Fortunately, testing is a *very* big subject in computer programming, so there's lots of information out there:
230   
231        * A good first look at writing tests for Django can be found in the online  documentation on :doc:`Testing Django applications</topics/testing/>`.
232        * Dive Into Python (a free online book for beginning Python developers) includes a great `introduction to Unit Testing`__.
233        * After reading those, if you want something a little meatier to sink your teeth into, there's always the `Python unittest documentation`__.
234
235__ https://code.djangoproject.com/ticket/15315
236__ http://diveintopython.org/unit_testing/index.html
237__ http://docs.python.org/library/unittest.html
238
239Running your new test
240---------------------
241
242Remember that we haven't actually made any modifications to ``modelform_factory`` yet, so our test is going to fail.  Let's run all the tests in the ``model_forms_regress`` folder to make sure that's really what happens. From the command line, ``cd`` into the Django ``tests/`` directory and run:
243
244.. code-block:: bash
245
246    ./runtests.py --settings=test_sqlite model_forms_regress
247
248If tests ran correctly, you should see that one of the tests failed with an error. Verify that it was the new ``test_factory_with_widget_argument`` test we added above, and then go on to the next step.
249
250If 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. It's also possible that you have a second copy of Django on your ``PYTHONPATH`` that is taking priority over this copy, and therefore it may be that copy of Django whose tests are being run. To check if this might be the problem, refer to the section `Setting Django up to run the test suite`_.
251
252Writing the code for your ticket
253================================
254
255Next we'll be adding the functionality described in `ticket #15315`__ to Django.
256
257Writing the code for ticket #15315
258----------------------------------
259
260Navigate to the ``trunk/django/forms/`` folder and open the ``models.py`` file. Find the ``modelform_factory`` function on line 370 and modify **the first part of it** so that it reads as follows:
261
262.. code-block:: python
263
264    def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
265                          formfield_callback=None,  widgets=None):
266        # Create the inner Meta class. FIXME: ideally, we should be able to
267        # construct a ModelForm without creating and passing in a temporary
268        # inner class.
269     
270        # Build up a list of attributes that the Meta object will have.
271        attrs = {'model': model}
272        if fields is not None:
273            attrs['fields'] = fields
274        if exclude is not None:
275            attrs['exclude'] = exclude
276        if widgets is not None:
277            attrs['widgets'] = widgets
278     
279        # If parent form class already has an inner Meta, the Meta we're
280        # creating needs to inherit from the parent's inner meta.
281        ...
282   
283Notice that we're changing one line of code to add a new ``widgets`` keyword argument to the function's signature, and then we're adding two lines of code a little below that which set ``attrs['widgets']`` to the value of our new keyword argument if it was supplied.
284
285Verifying your test now passes
286------------------------------
287
288Once you're done modifying ``modelform_factory``, we need to make sure that the test we wrote earlier passes now, so we can see whether the code we wrote above is working right. To run the tests in the ``model_forms_regress`` folder, ``cd`` into the Django ``tests/`` directory and run:
289
290.. code-block:: bash
291
292    ./runtests.py --settings=test_sqlite model_forms_regress
293
294If everything passes, then we can move on. If it doesn't, make sure you correctly modified the ``modelform_factory`` function as shown above and copied the ``test_factory_with_widget_argument`` test correctly.
295
296__ https://code.djangoproject.com/ticket/15315
297
298Running Django's test suite for the second time
299===============================================
300
301Once 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.
302
303To run the entire Django test suite, ``cd`` into the Django ``tests/`` directory and run:
304
305.. code-block:: bash
306
307    ./runtests.py --settings=test_sqlite
308
309As long as you don't see any failures, you're good to go, and you can move on to generating a patch file that can be uploaded to Trac. If you do have any failures, you'll need to examine them in order to determine whether or not the modifications you made caused them.
310
311Generating a patch for your changes
312===================================
313
314Now it's time to generate a patch file that can be uploaded to Trac or applied to another copy of Django. Once you're done with this step, you'll have a fancy patch file that should look something like this:
315
316.. code-block:: diff
317
318    Index: django/forms/models.py
319    ===================================================================
320    --- django/forms/models.py  (revision 16658)
321    +++ django/forms/models.py  (working copy)
322    @@ -368,7 +368,7 @@
323         __metaclass__ = ModelFormMetaclass
324     
325     def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
326    -                       formfield_callback=None):
327    +                       formfield_callback=None, widgets=None):
328         # Create the inner Meta class. FIXME: ideally, we should be able to
329         # construct a ModelForm without creating and passing in a temporary
330         # inner class.
331    @@ -379,7 +379,9 @@
332             attrs['fields'] = fields
333         if exclude is not None:
334             attrs['exclude'] = exclude
335    -
336    +    if widgets is not None:
337    +        attrs['widgets'] = widgets
338    +   
339         # If parent form class already has an inner Meta, the Meta we're
340         # creating needs to inherit from the parent's inner meta.
341         parent = (object,)
342   
343    Index: tests/regressiontests/model_forms_regress/tests.py
344    ===================================================================
345    --- tests/regressiontests/model_forms_regress/tests.py      (revision 16658)
346    +++ tests/regressiontests/model_forms_regress/tests.py      (working copy)
347    @@ -263,6 +263,20 @@
348     
349     class FormFieldCallbackTests(TestCase):
350     
351    +    def test_factory_with_widget_argument(self):
352    +        """ Regression for #15315: modelform_factory should accept widgets
353    +            argument
354    +        """
355    +        widget = forms.Textarea()
356    +       
357    +        # Without a widget should not set the widget to textarea
358    +        Form = modelform_factory(Person)
359    +        self.assertNotEqual(Form.base_fields['name'].widget.__class__, forms.Textarea)
360    +       
361    +        # With a widget should not set the widget to textarea
362    +        Form = modelform_factory(Person, widgets={'name':widget})
363    +        self.assertEqual(Form.base_fields['name'].widget.__class__, forms.Textarea)
364    +
365         def test_baseform_with_widgets_in_meta(self):
366             """Regression for #13095: Using base forms with widgets defined in Meta should not raise errors."""
367             widget = forms.Textarea()
368
369Creating your patch file with Subversion
370----------------------------------------
371
372If you used Subversion to checkout your copy of Django, you'll first need to navigate to your root Django directory (that's the one that contains ``django``, ``docs``, ``tests``, ``AUTHORS``, etc.). This is where we'll generate the patch file from.
373
374.. note::
375
376    It's very important that you generate your patch file from Django's root directory; otherwise, it can be difficult for other developers to apply your patch, because a patch file can only be applied in the same directory it was generated in.
377
378Once you've navigated to Django's root directory, you can get see what your patch file will look like by running the following command:
379
380.. code-block:: bash
381
382    svn diff
383   
384This 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. It should look similar to (but not necessarily the same as) the example patch file shown above.
385
386If the patch's content looks okay, you can run the following command to save the patch file to your current working directory.
387
388.. code-block:: bash
389
390    svn diff > myfancynewpatch.diff
391
392You should now have a file in the root Django directory called ``myfancynewpatch.diff``. This patch file that contains all your changes.
393
394Creating your patch file with Git
395---------------------------------
396
397For those who prefer using Git, the process is much the same as with Subversion.  To get a look at the content of your patch, run the following command instead:
398
399.. code-block:: bash
400
401    git diff
402   
403This 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. Note that your patch won't look exactly the same as the example patch shown above, since the Git patch format is slightly different than the Subversion format. Either format is acceptable though.
404
405Once you're done looking at the patch, hit the ``Q`` 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.
406
407.. code-block:: bash
408
409    git diff > myfancynewpatch.diff
410
411You should now have a file in the root Django directory called ``myfancynewpatch.diff``. This patch file that contains all your changes.
412
413So what do I do next?
414=====================
415
416Congratulations, 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 improve Django's codebase.
417
418More information for new contributors
419-------------------------------------
420
421Before you get too into writing patches for Django, there's a little more information on contributing that you should probably take a look at:
422
423    * You should make sure to read Django's documentation on :doc:`claiming tickets and submitting patches</internals/contributing/writing-code/submitting-patches>`. It covers Trac etiquette, how to claim tickets for yourself, expected coding style for patches, and many other important details.
424    * First time contributors should also read Django's :doc:`documentation for first time contributors</internals/contributing/new-contributors/>`. It has lots of good advice for those of us who are new to helping out with Django.
425    * After those, if you're still hungry for more information about contributing, you can always browse through the rest of :doc:`Django's documentation on contributing<internals/contributing/index>`. It contains a ton of useful information and should be your first source for answering any questions you might have.
426
427Finding your first real ticket
428------------------------------
429
430Once 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.
431
432If you just want to get started already (and nobody would blame you!), try taking a look at the list of `easy tickets that need patches`__ and the `easy tickets that have patches which need improvement`__. If you're familiar with writing tests, you can also look at the list of `easy tickets that need tests`__. Just remember to follow the guidelines about claiming tickets that were mentioned in the link to Django's documentation on :doc:`claiming tickets and submitting patches</internals/contributing/writing-code/submitting-patches>`.
433
434__ 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
435__ 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
436__ 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
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
Back to Top