Ticket #16779: 16779.4.diff

File 16779.4.diff, 29.0 KB (added by timo, 3 years ago)
  • docs/index.txt

    diff --git a/docs/index.txt b/docs/index.txt
    index a6d9ed2..e6eb77c 100644
    a b Are you new to Django or to programming? This is the place to start! 
    4747  :doc:`Part 4 <intro/tutorial04>`
    4848
    4949* **Advanced Tutorials:**
    50   :doc:`How to write reusable apps <intro/reusable-apps>`
     50  :doc:`How to write reusable apps <intro/reusable-apps>` |
     51  :doc:`Writing your first patch for Django <intro/contributing>`
    5152
    5253The model layer
    5354===============
  • docs/internals/contributing/writing-code/unit-tests.txt

    diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
    index a828b06..71666a1 100644
    a b with this sample ``settings`` module, ``cd`` into the Django 
    3838If you get an ``ImportError: No module named django.contrib`` error,
    3939you need to add your install of Django to your ``PYTHONPATH``.
    4040
     41.. _running-unit-tests-settings:
     42
    4143Using another ``settings`` module
    4244~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    4345
    Then, run the tests normally, for example: 
    133135
    134136    ./runtests.py --settings=test_sqlite admin_inlines
    135137
     138.. _running-unit-tests-dependencies:
     139
    136140Running all the tests
    137141~~~~~~~~~~~~~~~~~~~~~
    138142
  • new file docs/intro/contributing.txt

    diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt
    new file mode 100644
    index 0000000..8717f7a
    - +  
     1===================================
     2Writing your first patch for Django
     3===================================
     4
     5Introduction
     6============
     7
     8Interested in giving back to the community a little? Maybe you've found a bug
     9in Django that you'd like to see fixed, or maybe there's a small feature you
     10want added.
     11
     12Contributing back to Django itself is the best way to see your own concerns
     13addressed. This may seem daunting at first, but it's really pretty simple.
     14We'll walk you through the entire process, so you can learn by example.
     15
     16Who's this tutorial for?
     17------------------------
     18
     19For this tutorial, we expect that you have at least a basic understanding of
     20how Django works. This means you should be comfortable going through the
     21existing tutorials on :doc:`writing your first Django app</intro/tutorial01>`.
     22In addition, you should have a good understanding of Python itself. But if you
     23don't, `Dive Into Python`__ is a fantastic (and free) online book for beginning
     24Python programmers.
     25
     26Those of you who are unfamiliar with version control systems and Trac will find
     27that this tutorial and its links include just enough information to get started.
     28However, you'll probably want to read some more about these different tools if
     29you plan on contributing to Django regularly.
     30
     31For the most part though, this tutorial tries to explain as much as possible,
     32so that it can be of use to the widest audience.
     33
     34.. admonition:: Where to get help:
     35
     36    If you're having trouble going through this tutorial, please post a message
     37    to `django-developers`__ or drop by `#django-dev on irc.freenode.net`__ to chat
     38    with other Django users who might be able to help.
     39
     40__ http://diveintopython.net/toc/index.html
     41__ http://groups.google.com/group/django-developers
     42__ irc://irc.freenode.net/django-dev
     43
     44What does this tutorial cover?
     45------------------------------
     46
     47We'll be walking you through contributing a patch to Django for the first time.
     48By the end of this tutorial, you should have a basic understanding of both the
     49tools and the processes involved. Specifically, we'll be covering the following:
     50
     51* Installing Git.
     52* How to download a development copy of Django.
     53* Running Django's test suite.
     54* Writing a test for your patch.
     55* Writing the code for your patch.
     56* Testing your patch.
     57* Generating a patch file for your changes.
     58* Where to look for more information.
     59
     60Once you're done with the tutorial, you can look through the rest of
     61:doc:`Django's documentation on contributing</internals/contributing/index>`.
     62It contains lots of great information and is a must read for anyone who'd like
     63to become a regular contributor to Django. If you've got questions, it's
     64probably got the answers.
     65
     66Installing Git
     67==============
     68
     69For this tutorial, you'll need Git installed to download the current
     70development version of Django and to generate patch files for the changes you
     71make.
     72
     73To check whether or not you have Git installed, enter ``git`` into the command
     74line. If you get messages saying that this command could be found, you'll have
     75to download and install it, see `Git's download page`__.
     76
     77If you're not that familiar with Git, you can always find out more about its
     78commands (once it's installed) by typing ``git help`` into the command line.
     79
     80__ http://git-scm.com/download
     81
     82Getting a copy of Django's development version
     83==============================================
     84
     85The first step to contributing to Django is to get a copy of the source code.
     86From the command line, use the ``cd`` command to navigate to the directory
     87where you'll want your local copy of Django to live.
     88
     89Download the Django source code repository using the following command::
     90
     91    git clone https://github.com/django/django.git
     92
     93.. note::
     94
     95    For users who wish to use `virtualenv`__, you can use::
     96
     97        pip install -e git+https://github.com/django/django.git#egg=django
     98
     99    to install a live, editable source checkout into a virtual environment.
     100    This is a great option to isolate your development copy of Django from the
     101    rest of your system and avoids potential package conflicts.
     102
     103__ http://www.virtualenv.org
     104
     105Rolling back to a previous revision of Django
     106=============================================
     107
     108For this tutorial, we'll be using `ticket #17549`__ as a case study, so we'll
     109be using an older revision of Django from before that ticket's patch was
     110applied. This will allow us to go through all of the steps involved in writing
     111that patch from scratch, including running Django's test suite.
     112
     113**Keep in mind that while we'll be using an older revision of Django's trunk
     114for the purposes of the tutorial below, you should always use the current
     115development revision of Django when working on your own patch for a ticket!**
     116
     117.. note::
     118
     119    The patch for this ticket was written by Ulrich Petri, and it was applied
     120    to Django as `commit ac2052ebc84c45709ab5f0f25e685bf656ce79bc`__.
     121    Consequently, we'll be using the revision of Django just prior to that,
     122    `commit 39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac`__.
     123
     124__ https://code.djangoproject.com/ticket/17549
     125__ https://github.com/django/django/commit/ac2052ebc84c45709ab5f0f25e685bf656ce79bc
     126__ https://github.com/django/django/commit/39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac
     127
     128Navigate into Django's root directory (that's the one that contains ``django``,
     129``docs``, ``tests``, ``AUTHORS``, etc.). You can then check out the older
     130revision of Django that we'll be using in the tutorial below::
     131
     132    git checkout 39f5bc7fc3a4bb43ed8a1358b17fe0521a1a63ac
     133
     134Running Django's test suite for the first time
     135==============================================
     136
     137When contributing to Django it's very important that your code changes don't
     138introduce bugs into other areas of Django.  One way to check that Django still
     139works after you make your changes is by running Django's test suite. If all
     140the tests still pass, then you can be reasonably sure that your changes
     141haven't completely broken Django. If you've never run Django's test suite
     142before, it's a good idea to run it once beforehand just to get familiar with
     143what its output is supposed to look like.
     144
     145We can run the test suite by simply ``cd``-ing into the Django ``tests/``
     146directory and, if you're using GNU/Linux, Mac OS X or some other flavor of
     147Unix, run::
     148
     149    PYTHONPATH=.. python runtests.py --settings=test_sqlite
     150
     151If you're on Windows, the above should work provided that you are using
     152"Git Bash" provided by the default Git install. GitHub has a `nice tutorial`__.
     153
     154__ https://help.github.com/articles/set-up-git#platform-windows
     155
     156.. note::
     157
     158    If you're using ``virtualenv``, you can omit ``PYTHONPATH=..`` when running
     159    the tests. This instructs Python to look for Django in the parent directory
     160    of ``tests``. ``virtualenv`` puts your copy of Django on the ``PYTHONPATH``
     161    automatically.
     162
     163Now sit back and relax. Django's entire test suite has over 4800 different
     164tests, so it can take anywhere from 5 to 15 minutes to run, depending on the
     165speed of your computer.
     166
     167While Django's test suite is running, you'll see a stream of characters
     168representing the status of each test as it's run. ``E`` indicates that an error
     169was raised during a test, and ``F`` indicates that a test's assertions failed.
     170Both of these are considered to be test failures. Meanwhile, ``x`` and ``s``
     171indicated expected failures and skipped tests, respectively. Dots indicate
     172passing tests.
     173
     174Skipped tests are typically due to missing external libraries required to run
     175the test; see :ref:`running-unit-tests-dependencies` for a list of dependencies
     176and be sure to install any for tests related to the changes you are making (we
     177won't need any for this tutorial).
     178
     179Once the tests complete, you should be greeted with a message informing you
     180whether the test suite passed or failed. Since you haven't yet made any changes
     181to Django's code, the entire test suite **should** pass. If you get failures or
     182errors make sure you've followed all of the previous steps properly. See
     183:ref:`running-unit-tests` for more information.
     184
     185Note that the latest Django trunk may not always be stable. When developing
     186against trunk, you can check `Django's continuous integration builds`__ to
     187determine if the failures are specific to your machine or if they are also
     188present in Django's official builds.
     189
     190__ http://ci.djangoproject.com/
     191
     192.. note::
     193
     194    For this tutorial and the ticket we're working on, testing against SQLite
     195    is sufficient, however, it's possible (and sometimes necessary) to
     196    :ref:`run the tests using a different database
     197    <running-unit-tests-settings>`.
     198
     199Writing some tests for your ticket
     200==================================
     201
     202In most cases, for a patch to be accepted into Django it has to include tests.
     203For bug fix patches, this means writing a regression test to ensure that the
     204bug is never reintroduced into Django later on. A regression test should be
     205written in such a way that it will fail while the bug still exists and pass
     206once the bug has been fixed. For patches containing new features, you'll need
     207to include tests which ensure that the new features are working correctly.
     208They too should fail when the new feature is not present, and then pass once it
     209has been implemented.
     210
     211A good way to do this is to write your new tests first, before making any
     212changes to the code. This style of development is called
     213`test-driven development`__ and can be applied to both entire projects and
     214single patches. After writing your tests, you then run them to make sure that
     215they do indeed fail (since you haven't fixed that bug or added that feature
     216yet). If your new tests don't fail, you'll need to fix them so that they do.
     217After all, a regression test that passes regardless of whether a bug is present
     218is not very helpful at preventing that bug from reoccurring down the road.
     219
     220Now for our hands-on example.
     221
     222__ http://en.wikipedia.org/wiki/Test-driven_development
     223
     224Writing some tests for ticket #17549
     225------------------------------------
     226
     227`Ticket #17549`__ describes the following, small feature addition:
     228
     229    It's useful for URLField to give you a way to open the URL; otherwise you
     230    might as well use a CharField.
     231
     232In order to resolve this ticket, we'll add a ``render`` method to the
     233``AdminURLFieldWidget`` in order to display a clickable link above the input
     234widget. Before we make those changes though, we're going to write a couple
     235tests to verify that our modification functions correctly and continues to
     236function correctly in the future.
     237
     238Navigate to Django's ``tests/regressiontests/admin_widgets/`` folder and
     239open the ``tests.py`` file. Add the following code on line 269 right before the
     240``AdminFileWidgetTest`` class::
     241
     242    class AdminURLWidgetTest(DjangoTestCase):
     243        def test_render(self):
     244            w = widgets.AdminURLFieldWidget()
     245            self.assertHTMLEqual(
     246                conditional_escape(w.render('test', '')),
     247                '<input class="vURLField" name="test" type="text" />'
     248            )
     249            self.assertHTMLEqual(
     250                conditional_escape(w.render('test', 'http://example.com')),
     251                '<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>'
     252            )
     253
     254        def test_render_idn(self):
     255            w = widgets.AdminURLFieldWidget()
     256            self.assertHTMLEqual(
     257                conditional_escape(w.render('test', 'http://example-äüö.com')),
     258                '<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>'
     259            )
     260
     261        def test_render_quoting(self):
     262            w = widgets.AdminURLFieldWidget()
     263            self.assertHTMLEqual(
     264                conditional_escape(w.render('test', 'http://example.com/<sometag>some text</sometag>')),
     265                '<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>'
     266            )
     267            self.assertHTMLEqual(
     268                conditional_escape(w.render('test', 'http://example-äüö.com/<sometag>some text</sometag>')),
     269                '<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>'
     270            )
     271
     272The new tests check to see that the ``render`` method we'll be adding works
     273correctly in a couple different situations.
     274
     275.. admonition:: But this testing thing looks kinda hard...
     276
     277    If you've never had to deal with tests before, they can look a little hard
     278    to write at first glance. Fortunately, testing is a *very* big subject in
     279    computer programming, so there's lots of information out there:
     280
     281    * A good first look at writing tests for Django can be found in the
     282      documentation on :doc:`Testing Django applications</topics/testing/>`.
     283    * Dive Into Python (a free online book for beginning Python developers)
     284      includes a great `introduction to Unit Testing`__.
     285    * After reading those, if you want something a little meatier to sink
     286      your teeth into, there's always the `Python unittest documentation`__.
     287
     288__ https://code.djangoproject.com/ticket/17549
     289__ http://diveintopython.net/unit_testing/index.html
     290__ http://docs.python.org/library/unittest.html
     291
     292Running your new test
     293---------------------
     294
     295Remember that we haven't actually made any modifications to
     296``AdminURLFieldWidget`` yet, so our tests are going to fail. Let's run all the
     297tests in the ``model_forms_regress`` folder to make sure that's really what
     298happens. From the command line, ``cd`` into the Django ``tests/`` directory
     299and run::
     300
     301    PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets
     302
     303If the tests ran correctly, you should see three failures corresponding to each
     304of the test methods we added. If all of the tests passed, then you'll want to
     305make sure that you added the new test shown above to the appropriate folder and
     306class.
     307
     308Writing the code for your ticket
     309================================
     310
     311Next we'll be adding the functionality described in `ticket #17549`__ to Django.
     312
     313Writing the code for ticket #17549
     314----------------------------------
     315
     316Navigate to the ``django/django/contrib/admin/`` folder and open the
     317``widgets.py`` file. Find the ``AdminURLFieldWidget`` class on line 302 and add
     318the following ``render`` method after the existing ``__init__`` method::
     319
     320    def render(self, name, value, attrs=None):
     321        html = super(AdminURLFieldWidget, self).render(name, value, attrs)
     322        if value:
     323            value = force_text(self._format_value(value))
     324            final_attrs = {'href': mark_safe(smart_urlquote(value))}
     325            html = format_html(
     326                '<p class="url">{0} <a {1}>{2}</a><br />{3} {4}</p>',
     327                _('Currently:'), flatatt(final_attrs), value,
     328                _('Change:'), html
     329            )
     330        return html
     331
     332Verifying your test now passes
     333------------------------------
     334
     335Once you're done modifying Django, we need to make sure that the tests we wrote
     336earlier pass, so we can see whether the code we wrote above is working
     337correctly. To run the tests in the ``admin_widgets`` folder, ``cd`` into the
     338Django ``tests/`` directory and run::
     339
     340    PYTHONPATH=.. python runtests.py --settings=test_sqlite admin_widgets
     341
     342Oops, good thing we wrote those tests! You should still see 3 failures with
     343the following exception::
     344
     345    NameError: global name 'smart_urlquote' is not defined
     346
     347We forgot to add the import for that method.  Go ahead and add the
     348``smart_urlquote`` import at the end of line 13 of
     349``django/contrib/admin/widgets.py`` so it looks as follows::
     350
     351    from django.utils.html import escape, format_html, format_html_join, smart_urlquote
     352
     353Re-run the tests and everything should pass. If it doesn't, make sure you
     354correctly modified the ``AdminURLFieldWidget`` class as shown above and
     355copied the new tests correctly.
     356
     357__ https://code.djangoproject.com/ticket/17549
     358
     359Running Django's test suite for the second time
     360===============================================
     361
     362Once you've verified that your patch and your test are working correctly, it's
     363a good idea to run the entire Django test suite just to verify that your change
     364hasn't introduced any bugs into other areas of Django. While successfully
     365passing the entire test suite doesn't guarantee your code is bug free, it does
     366help identify many bugs and regressions that might otherwise go unnoticed.
     367
     368To run the entire Django test suite, ``cd`` into the Django ``tests/``
     369directory and run::
     370
     371    PYTHONPATH=.. python runtests.py --settings=test_sqlite
     372
     373As long as you don't see any failures, you're good to go. Note that this fix
     374also made a `small CSS change`__ to format the new widget. You can make the
     375change if you'd like, but we'll skip it for now in the interest of brevity.
     376
     377__ https://github.com/django/django/commit/ac2052ebc84c45709ab5f0f25e685bf656ce79bc#diff-0
     378
     379Writing Documentation
     380=====================
     381
     382This is a new feature, so it should be documented.  Add the following on line
     383925 of ``django/docs/ref/models/fields.txt`` beneath the existing docs for
     384``URLField``::
     385
     386    .. versionadded:: 1.5
     387
     388    The current value of the field will be displayed as a clickable link above the
     389    input widget.
     390
     391For more information on writing documentation, including an explanation of what
     392the ``versionadded`` bit is all about, see
     393:doc:`/internals/contributing/writing-documentation`. That page also includes
     394an explanation of how to build a copy of the documentation locally, so you can
     395preview the HTML that will be generated.
     396
     397Generating a patch for your changes
     398===================================
     399
     400Now it's time to generate a patch file that can be uploaded to Trac or applied
     401to another copy of Django. To get a look at the content of your patch, run the
     402following command::
     403
     404    git diff
     405
     406This will display the differences between your current copy of Django (with
     407your changes) and the revision that you initially checked out earlier in the
     408tutorial.
     409
     410Once you're done looking at the patch, hit the ``q`` key to exit back to the
     411command line.  If the patch's content looked okay, you can run the following
     412command to save the patch file to your current working directory::
     413
     414    git diff > 17549.diff
     415
     416You should now have a file in the root Django directory called ``17549.diff``.
     417This patch file contains all your changes and should look this:
     418
     419.. code-block:: diff
     420
     421    diff --git a/django/contrib/admin/widgets.py b/django/contrib/admin/widgets.py
     422    index 1e0bc2d..9e43a10 100644
     423    --- a/django/contrib/admin/widgets.py
     424    +++ b/django/contrib/admin/widgets.py
     425    @@ -10,7 +10,7 @@ from django.contrib.admin.templatetags.admin_static import static
     426     from django.core.urlresolvers import reverse
     427     from django.forms.widgets import RadioFieldRenderer
     428     from django.forms.util import flatatt
     429    -from django.utils.html import escape, format_html, format_html_join
     430    +from django.utils.html import escape, format_html, format_html_join, smart_urlquote
     431     from django.utils.text import Truncator
     432     from django.utils.translation import ugettext as _
     433     from django.utils.safestring import mark_safe
     434    @@ -306,6 +306,18 @@ class AdminURLFieldWidget(forms.TextInput):
     435                 final_attrs.update(attrs)
     436             super(AdminURLFieldWidget, self).__init__(attrs=final_attrs)
     437
     438    +    def render(self, name, value, attrs=None):
     439    +        html = super(AdminURLFieldWidget, self).render(name, value, attrs)
     440    +        if value:
     441    +            value = force_text(self._format_value(value))
     442    +            final_attrs = {'href': mark_safe(smart_urlquote(value))}
     443    +            html = format_html(
     444    +                '<p class="url">{0} <a {1}>{2}</a><br />{3} {4}</p>',
     445    +                _('Currently:'), flatatt(final_attrs), value,
     446    +                _('Change:'), html
     447    +            )
     448    +        return html
     449    +
     450     class AdminIntegerFieldWidget(forms.TextInput):
     451         class_name = 'vIntegerField'
     452
     453    diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
     454    index 809d56e..d44f85f 100644
     455    --- a/docs/ref/models/fields.txt
     456    +++ b/docs/ref/models/fields.txt
     457    @@ -922,6 +922,10 @@ Like all :class:`CharField` subclasses, :class:`URLField` takes the optional
     458     :attr:`~CharField.max_length`argument. If you don't specify
     459     :attr:`~CharField.max_length`, a default of 200 is used.
     460
     461    +.. versionadded:: 1.5
     462    +
     463    +The current value of the field will be displayed as a clickable link above the
     464    +input widget.
     465
     466     Relationship fields
     467     ===================
     468    diff --git a/tests/regressiontests/admin_widgets/tests.py b/tests/regressiontests/admin_widgets/tests.py
     469    index 4b11543..94acc6d 100644
     470    --- a/tests/regressiontests/admin_widgets/tests.py
     471    +++ b/tests/regressiontests/admin_widgets/tests.py
     472    @@ -265,6 +265,35 @@ class AdminSplitDateTimeWidgetTest(DjangoTestCase):
     473                         '<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>',
     474                     )
     475
     476    +class AdminURLWidgetTest(DjangoTestCase):
     477    +    def test_render(self):
     478    +        w = widgets.AdminURLFieldWidget()
     479    +        self.assertHTMLEqual(
     480    +            conditional_escape(w.render('test', '')),
     481    +            '<input class="vURLField" name="test" type="text" />'
     482    +        )
     483    +        self.assertHTMLEqual(
     484    +            conditional_escape(w.render('test', 'http://example.com')),
     485    +            '<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>'
     486    +        )
     487    +
     488    +    def test_render_idn(self):
     489    +        w = widgets.AdminURLFieldWidget()
     490    +        self.assertHTMLEqual(
     491    +            conditional_escape(w.render('test', 'http://example-äüö.com')),
     492    +            '<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>'
     493    +        )
     494    +
     495    +    def test_render_quoting(self):
     496    +        w = widgets.AdminURLFieldWidget()
     497    +        self.assertHTMLEqual(
     498    +            conditional_escape(w.render('test', 'http://example.com/<sometag>some text</sometag>')),
     499    +            '<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>'
     500    +        )
     501    +        self.assertHTMLEqual(
     502    +            conditional_escape(w.render('test', 'http://example-äüö.com/<sometag>some text</sometag>')),
     503    +            '<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>'
     504    +        )
     505
     506     class AdminFileWidgetTest(DjangoTestCase):
     507         def test_render(self):
     508
     509So what do I do next?
     510=====================
     511
     512Congratulations, you've generated your very first Django patch! Now that you've
     513got that under your belt, you can put those skills to good use by helping to
     514improve Django's codebase. Generating patches and attaching them to Trac
     515tickets is useful, however, you can also :doc:`submit pull requests on Github
     516</internals/contributing/writing-code/working-with-git>`.
     517
     518More information for new contributors
     519-------------------------------------
     520
     521Before you get too into writing patches for Django, there's a little more
     522information on contributing that you should probably take a look at:
     523
     524* You should make sure to read Django's documentation on
     525  :doc:`claiming tickets and submitting patches
     526  </internals/contributing/writing-code/submitting-patches>`.
     527  It covers Trac etiquette, how to claim tickets for yourself, expected
     528  coding style for patches, and many other important details.
     529* First time contributors should also read Django's :doc:`documentation
     530  for first time contributors</internals/contributing/new-contributors/>`.
     531  It has lots of good advice for those of us who are new to helping out
     532  with Django.
     533* After those, if you're still hungry for more information about
     534  contributing, you can always browse through the rest of
     535  :doc:`Django's documentation on contributing</internals/contributing/index>`.
     536  It contains a ton of useful information and should be your first source
     537  for answering any questions you might have.
     538
     539Finding your first real ticket
     540------------------------------
     541
     542Once you've looked through some of that information, you'll be ready to go out
     543and find a ticket of your own to write a patch for. Pay special attention to
     544tickets with the "easy pickings" criterion. These tickets are often much
     545simpler in nature and are great for first time contributors.  Once you're
     546familiar with contributing to Django, you can move on to writing patches for
     547more difficult and complicated tickets.
     548
     549If you just want to get started already (and nobody would blame you!), try
     550taking a look at the list of `easy tickets that need patches`__ and the
     551`easy tickets that have patches which need improvement`__. If you're familiar
     552with writing tests, you can also look at the list of
     553`easy tickets that need tests`__. Just remember to follow the guidelines about
     554claiming tickets that were mentioned in the link to Django's documentation on
     555:doc:`claiming tickets and submitting patches
     556</internals/contributing/writing-code/submitting-patches>`.
     557
     558__ 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
     559__ 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
     560__ 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
     561
     562What's next?
     563------------
     564
     565After a ticket has a patch, it needs to be reviewed by a second set of eyes.
     566After uploading a patch or submitting a pull request, be sure to update the
     567ticket metadata by setting the flags on the ticket to say "has patch",
     568"doesn't need tests", etc, so others can find it for review. Contributing
     569doesn't necessarily always mean writing a patch from scratch. Reviewing
     570existing patches is also a very helpful contribution. See
     571:doc:`/internals/contributing/triaging-tickets` for details.
  • docs/intro/index.txt

    diff --git a/docs/intro/index.txt b/docs/intro/index.txt
    index afb1825..bca2d77 100644
    a b place: read this material to quickly get up and running. 
    1515   tutorial04
    1616   reusable-apps
    1717   whatsnext
     18   contributing
    1819
    1920.. seealso::
    2021
Back to Top