Debian Codegraph @

docs/intro/contributing.txt

raw
1 ==========================================
2 Writing your first contribution for Django
3 ==========================================
4
5 Introduction
6 ============
7
8 Interested in giving back to the community a little? Maybe you've found a bug
9 in Django that you'd like to see fixed, or maybe there's a small feature you
10 want added (but remember that proposals for new features should follow the
11 :ref:`process for suggesting new features <requesting-features>`).
12
13 Contributing back to Django itself is the best way to see your own concerns
14 addressed. This may seem daunting at first, but it's a well-traveled path with
15 documentation, tooling, and a community to support you. We'll walk you through
16 the entire process, so you can learn by example.
17
18 Who's this tutorial for?
19 ------------------------
20
21 .. seealso::
22
23 If you are looking for a reference on the details of making code
24 contributions, see the :doc:`/internals/contributing/writing-code/index`
25 documentation.
26
27 For this tutorial, we expect that you have at least a basic understanding of
28 how Django works. This means you should be comfortable going through the
29 existing tutorials on :doc:`writing your first Django app</intro/tutorial01>`.
30 In addition, you should have a good understanding of Python itself. But if you
31 don't, `Dive Into Python`_ is a fantastic (and free) online book for beginning
32 Python programmers.
33
34 Those of you who are unfamiliar with version control systems and Trac will find
35 that this tutorial and its links include just enough information to get started.
36 However, you'll probably want to read some more about these different tools if
37 you plan on contributing to Django regularly.
38
39 For the most part though, this tutorial tries to explain as much as possible,
40 so that it can be of use to the widest audience.
41
42 .. admonition:: Where to get help:
43
44 If you're having trouble going through this tutorial, please post a message
45 on the `Django Forum`_ or drop by the `Django Discord server`_ to chat with
46 other Django users who might be able to help.
47
48 .. _Dive Into Python: https://diveintopython3.net/
49 .. _Django Forum: https://forum.djangoproject.com/
50 .. _Django Discord server: https://chat.djangoproject.com
51
52 What does this tutorial cover?
53 ------------------------------
54
55 We'll be walking you through contributing to Django for the first time.
56 By the end of this tutorial, you should have a basic understanding of both the
57 tools and the processes involved. Specifically, we'll be covering the following:
58
59 * Installing Git.
60 * Downloading a copy of Django's development version.
61 * Running Django's test suite.
62 * Writing a test for your changes.
63 * Writing the code for your changes.
64 * Testing your changes.
65 * Submitting a pull request.
66 * Where to look for more information.
67
68 Once you're done with the tutorial, you can look through the rest of
69 :doc:`Django's documentation on contributing</internals/contributing/index>`.
70 It contains lots of great information and is a must read for anyone who'd like
71 to become a regular contributor to Django. If you've got questions, it's
72 probably got the answers.
73
74 .. admonition:: Python 3 required!
75
76 The current version of Django doesn't support Python 2.7. Get Python 3 at
77 `Python's download page <https://www.python.org/downloads/>`_ or with your
78 operating system's package manager.
79
80 .. admonition:: For Windows users
81
82 See :ref:`install_python_windows` on Windows docs for additional guidance.
83
84 Code of Conduct
85 ===============
86
87 As a contributor, you can help us keep the Django community open and inclusive.
88 Please read and follow our `Code of Conduct <https://www.djangoproject.com/conduct/>`_.
89
90 Installing Git
91 ==============
92
93 For this tutorial, you'll need Git installed to download the current
94 development version of Django and to generate a branch for the changes you
95 make.
96
97 To check whether or not you have Git installed, enter ``git`` into the command
98 line. If you get messages saying that this command could not be found, you'll
99 have to download and install it, see `Git's download page`__.
100
101 If you're not that familiar with Git, you can always find out more about its
102 commands (once it's installed) by typing ``git help`` into the command line.
103
104 __ https://git-scm.com/download
105
106 Getting a copy of Django's development version
107 ==============================================
108
109 The first step to contributing to Django is to get a copy of the source code.
110 First, `fork Django on GitHub <https://github.com/django/django/fork>`__. Then,
111 from the command line, use the ``cd`` command to navigate to the directory
112 where you'll want your local copy of Django to live.
113
114 Download the Django source code repository using the following command:
115
116 .. console::
117
118 $ git clone https://github.com/YourGitHubName/django.git
119
120 .. admonition:: Low bandwidth connection?
121
122 You can add the ``--depth 1`` argument to ``git clone`` to skip downloading
123 all of Django's commit history, which reduces data transfer from ~250 MB
124 to ~70 MB.
125
126 Now that you have a local copy of Django, you can install it just like you would
127 install any package using ``pip``. The most convenient way to do so is by using
128 a *virtual environment*, which is a feature built into Python that allows you
129 to keep a separate directory of installed packages for each of your projects so
130 that they don't interfere with each other.
131
132 It's a good idea to keep all your virtual environments in one place, for
133 example in ``.virtualenvs/`` in your home directory.
134
135 .. _intro-contributing-install-local-copy:
136
137 Create a new virtual environment by running:
138
139 .. console::
140
141 $ python3 -m venv ~/.virtualenvs/djangodev
142
143 The path is where the new environment will be saved on your computer.
144
145 The final step in setting up your virtual environment is to activate it:
146
147 .. code-block:: console
148
149 $ source ~/.virtualenvs/djangodev/bin/activate
150
151 If the ``source`` command is not available, you can try using a dot instead:
152
153 .. code-block:: console
154
155 $ . ~/.virtualenvs/djangodev/bin/activate
156
157 You have to activate the virtual environment whenever you open a new
158 terminal window.
159
160 .. admonition:: For Windows users
161
162 To activate your virtual environment on Windows, run:
163
164 .. code-block:: doscon
165
166 ...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
167
168 The name of the currently activated virtual environment is displayed on the
169 command line to help you keep track of which one you are using. Anything you
170 install through ``pip`` while this name is displayed will be installed in that
171 virtual environment, isolated from other environments and system-wide packages.
172
173 Go ahead and install the previously cloned copy of Django:
174
175 .. console::
176
177 $ python -m pip install -e /path/to/your/local/clone/django/
178
179 The installed version of Django is now pointing at your local copy by installing
180 in editable mode. You will immediately see any changes you make to it, which is
181 of great help when testing your first contribution.
182
183 Running Django's test suite for the first time
184 ==============================================
185
186 When contributing to Django it's very important that your code changes don't
187 introduce bugs into other areas of Django. One way to check that Django still
188 works after you make your changes is by running Django's test suite. If all
189 the tests still pass, then you can be reasonably sure that your changes
190 work and haven't broken other parts of Django. If you've never run Django's test
191 suite before, it's a good idea to run it once beforehand to get familiar with
192 its output.
193
194 Before running the test suite, enter the Django ``tests/`` directory using the
195 ``cd tests`` command, and install test dependencies by running:
196
197 .. console::
198
199 $ python -m pip install -r requirements/py3.txt
200
201 If you encounter an error during the installation, your system might be missing
202 a dependency for one or more of the Python packages. Consult the failing
203 package's documentation or search the web with the error message that you
204 encounter.
205
206 Now we are ready to run the test suite:
207
208 .. console::
209
210 $ ./runtests.py
211
212 Now sit back and relax. Django's entire test suite has thousands of tests, and
213 it takes at least a few minutes to run, depending on the speed of your
214 computer.
215
216 While Django's test suite is running, you'll see a stream of characters
217 representing the status of each test as it completes. ``E`` indicates that an
218 error was raised during a test, and ``F`` indicates that a test's assertions
219 failed. Both of these are considered to be test failures. Meanwhile, ``x`` and
220 ``s`` indicate expected failures and skipped tests, respectively. Dots indicate
221 passing tests.
222
223 Skipped tests are typically due to missing external libraries required to run
224 the test; see :ref:`running-unit-tests-dependencies` for a list of dependencies
225 and be sure to install any for tests related to the changes you are making (we
226 won't need any for this tutorial). Some tests are specific to a particular
227 database backend and will be skipped if not testing with that backend. SQLite
228 is the database backend for the default settings. To run the tests using a
229 different backend, see :ref:`running-unit-tests-settings`.
230
231 Once the tests complete, you should be greeted with a message informing you
232 whether the test suite passed or failed. Since you haven't yet made any changes
233 to Django's code, the entire test suite **should** pass. If you get failures or
234 errors make sure you've followed all of the previous steps properly. See
235 :ref:`running-unit-tests` for more information.
236
237 Note that the latest Django "main" branch may not always be stable. When
238 developing against "main", you can check `Django's continuous integration
239 builds`__ to determine if the failures are specific to your machine or if they
240 are also present in Django's official builds. If you click to view a particular
241 build, you can view the "Configuration Matrix" which shows failures broken down
242 by Python version and database backend.
243
244 __ https://djangoci.com
245
246 .. note::
247
248 For this tutorial and the ticket we're working on, testing against SQLite
249 is sufficient, however, it's possible (and sometimes necessary) to
250 :ref:`run the tests using a different database
251 <running-unit-tests-settings>`. When making UI changes, you will need to
252 :ref:`run the Selenium tests <running-selenium-tests>`.
253
254 Working on an approved new feature
255 ==================================
256
257 For this tutorial, we'll work on a "fake accepted ticket" as a case study. Here
258 are the imaginary details:
259
260 .. admonition:: Ticket #99999 -- Allow making toast
261
262 Django should provide a function ``django.shortcuts.make_toast()`` that
263 returns ``'toast'``.
264
265 We'll now implement this feature and associated tests.
266
267 Creating a branch
268 =================
269
270 Before making any changes, create a new branch for the ticket:
271
272 .. console::
273
274 $ git checkout -b ticket_99999
275
276 You can choose any name that you want for the branch, "ticket_99999" is an
277 example. All changes made in this branch will be specific to the ticket and
278 won't affect the main copy of the code that we cloned earlier.
279
280 Writing some tests for your ticket
281 ==================================
282
283 In most cases, for a contribution to be accepted into Django it has to include
284 tests. For bug fix contributions, this means writing a regression test to
285 ensure that the bug is never reintroduced into Django later on. A regression
286 test should be written in such a way that it will fail while the bug still
287 exists and pass once the bug has been fixed. For contributions containing new
288 features, you'll need to include tests which ensure that the new features are
289 working correctly. They too should fail when the new feature is not present,
290 and then pass once it has been implemented.
291
292 A good way to do this is to write your new tests first, before making any
293 changes to the code. This style of development is called
294 `test-driven development`__ and can be applied to both entire projects and
295 single changes. After writing your tests, you then run them to make sure that
296 they do indeed fail (since you haven't fixed that bug or added that feature
297 yet). If your new tests don't fail, you'll need to fix them so that they do.
298 After all, a regression test that passes regardless of whether a bug is present
299 is not very helpful at preventing that bug from reoccurring down the road.
300
301 Now for our hands-on example.
302
303 __ https://en.wikipedia.org/wiki/Test-driven_development
304
305 Writing a test for ticket #99999
306 --------------------------------
307
308 In order to resolve this ticket, we'll add a ``make_toast()`` function to the
309 ``django.shortcuts`` module. First we are going to write a test that tries to
310 use the function and check that its output looks correct.
311
312 Navigate to Django's ``tests/shortcuts/`` folder and create a new file
313 ``test_make_toast.py``. Add the following code::
314
315 from django.shortcuts import make_toast
316 from django.test import SimpleTestCase
317
318
319 class MakeToastTests(SimpleTestCase):
320 def test_make_toast(self):
321 self.assertEqual(make_toast(), "toast")
322
323 This test checks that the ``make_toast()`` returns ``'toast'``.
324
325 .. admonition:: But this testing thing looks kinda hard...
326
327 If you've never had to deal with tests before, they can look a little hard
328 to write at first glance. Fortunately, testing is a *very* big subject in
329 computer programming, so there's lots of information out there:
330
331 * A good first look at writing tests for Django can be found in the
332 documentation on :doc:`/topics/testing/overview`.
333 * Dive Into Python (a free online book for beginning Python developers)
334 includes a great `introduction to Unit Testing`__.
335 * After reading those, if you want something a little meatier to sink
336 your teeth into, there's always the Python :mod:`unittest` documentation.
337
338 __ https://diveintopython3.net/unit-testing.html
339
340 Running your new test
341 ---------------------
342
343 Since we haven't made any modifications to ``django.shortcuts`` yet, our test
344 should fail. Let's run all the tests in the ``shortcuts`` folder to make sure
345 that's really what happens. ``cd`` to the Django ``tests/`` directory and run:
346
347 .. console::
348
349 $ ./runtests.py shortcuts
350
351 If the tests ran correctly, you should see one failure corresponding to the test
352 method we added, with this error:
353
354 .. code-block:: pytb
355
356 ImportError: cannot import name 'make_toast' from 'django.shortcuts'
357
358 If all of the tests passed, then you'll want to make sure that you added the
359 new test shown above to the appropriate folder and file name.
360
361 Writing the code for your ticket
362 ================================
363
364 Next we'll be adding the ``make_toast()`` function.
365
366 Navigate to the ``django/`` folder and open the ``shortcuts.py`` file. At the
367 bottom, add::
368
369 def make_toast():
370 return "toast"
371
372 Now we need to make sure that the test we wrote earlier passes, so we can see
373 whether the code we added is working correctly. Again, navigate to the Django
374 ``tests/`` directory and run:
375
376 .. console::
377
378 $ ./runtests.py shortcuts
379
380 Everything should pass. If it doesn't, make sure you correctly added the
381 function to the correct file.
382
383 Running Django's test suite for the second time
384 ===============================================
385
386 Once you've verified that your changes and test are working correctly, it's
387 a good idea to run the entire Django test suite to verify that your change
388 hasn't introduced any bugs into other areas of Django. While successfully
389 passing the entire test suite doesn't guarantee your code is bug free, it does
390 help identify many bugs and regressions that might otherwise go unnoticed.
391
392 To run the entire Django test suite, ``cd`` into the Django ``tests/``
393 directory and run:
394
395 .. console::
396
397 $ ./runtests.py
398
399 Writing Documentation
400 =====================
401
402 This is a new feature, so it should be documented. Open the file
403 ``docs/topics/http/shortcuts.txt`` and add the following at the end of the
404 file:
405
406 .. code-block:: rst
407
408 ``make_toast()``
409 ================
410
411 .. function:: make_toast()
412
413 .. versionadded:: 2.2
414
415 Returns ``'toast'``.
416
417 Since this new feature will be in an upcoming release it is also added to the
418 release notes for the next version of Django. Open the release notes for the
419 latest version in ``docs/releases/``, which at time of writing is ``2.2.txt``.
420 Add a note under the "Minor Features" header:
421
422 .. code-block:: rst
423
424 :mod:`django.shortcuts`
425 ~~~~~~~~~~~~~~~~~~~~~~~
426
427 * The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
428
429 For more information on writing documentation, including an explanation of what
430 the ``versionadded`` bit is all about, see
431 :doc:`/internals/contributing/writing-documentation`. That page also includes
432 an explanation of how to build a copy of the documentation locally, so you can
433 preview the HTML that will be generated.
434
435 Previewing your changes
436 =======================
437
438 Now it's time to review the changes made in the branch. To stage all the
439 changes ready for commit, run:
440
441 .. console::
442
443 $ git add --all
444
445 Then display the differences between your current copy of Django (with your
446 changes) and the revision that you initially checked out earlier in the
447 tutorial with:
448
449 .. console::
450
451 $ git diff --cached
452
453 Use the arrow keys to move up and down.
454
455 .. code-block:: diff
456
457 diff --git a/django/shortcuts.py b/django/shortcuts.py
458 index 7ab1df0e9d..8dde9e28d9 100644
459 --- a/django/shortcuts.py
460 +++ b/django/shortcuts.py
461 @@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
462
463 # Finally, fall back and assume it's a URL
464 return to
465 +
466 +
467 +def make_toast():
468 + return 'toast'
469 diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
470 index 7d85d30c4a..81518187b3 100644
471 --- a/docs/releases/2.2.txt
472 +++ b/docs/releases/2.2.txt
473 @@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
474 Minor features
475 --------------
476
477 +:mod:`django.shortcuts`
478 +~~~~~~~~~~~~~~~~~~~~~~~
479 +
480 +* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
481 +
482 :mod:`django.contrib.admin`
483 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
484
485 diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
486 index 7b3a3a2c00..711bf6bb6d 100644
487 --- a/docs/topics/http/shortcuts.txt
488 +++ b/docs/topics/http/shortcuts.txt
489 @@ -271,3 +271,12 @@ This example is equivalent to::
490 my_objects = list(MyModel.objects.filter(published=True))
491 if not my_objects:
492 raise Http404("No MyModel matches the given query.")
493 +
494 +``make_toast()``
495 +================
496 +
497 +.. function:: make_toast()
498 +
499 +.. versionadded:: 2.2
500 +
501 +Returns ``'toast'``.
502 diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
503 new file mode 100644
504 index 0000000000..6f4c627b6e
505 --- /dev/null
506 +++ b/tests/shortcuts/test_make_toast.py
507 @@ -0,0 +1,7 @@
508 +from django.shortcuts import make_toast
509 +from django.test import SimpleTestCase
510 +
511 +
512 +class MakeToastTests(SimpleTestCase):
513 + def test_make_toast(self):
514 + self.assertEqual(make_toast(), 'toast')
515
516 When you're done previewing the changes, hit the ``q`` key to return to the
517 command line. If the diff looked okay, it's time to commit the changes.
518
519 Committing the changes
520 ======================
521
522 To commit the changes:
523
524 .. console::
525
526 $ git commit
527
528 This opens up a text editor to type the commit message. Follow the :ref:`commit
529 message guidelines <committing-guidelines>` and write a message like:
530
531 .. code-block:: text
532
533 Fixed #99999 -- Added a shortcut function to make toast.
534
535 Pushing the commit and making a pull request
536 ============================================
537
538 After committing the changes, send it to your fork on GitHub (substitute
539 "ticket_99999" with the name of your branch if it's different):
540
541 .. console::
542
543 $ git push origin ticket_99999
544
545 You can create a pull request by visiting the `Django GitHub page
546 <https://github.com/django/django/>`_. You'll see your branch under "Your
547 recently pushed branches". Click "Compare & pull request" next to it.
548
549 Please don't do it for this tutorial, but on the next page that displays a
550 preview of the changes, you would click "Create pull request".
551
552 Next steps
553 ==========
554
555 Congratulations, you've learned how to make a pull request to Django! Details
556 of more advanced techniques you may need are in
557 :doc:`/internals/contributing/writing-code/working-with-git`.
558
559 Now you can put those skills to good use by helping to improve Django's
560 codebase.
561
562 More information for new contributors
563 -------------------------------------
564
565 Before you get too into contributing to Django, there's a little more
566 information on contributing that you should probably take a look at:
567
568 * You should make sure to read Django's documentation on
569 :doc:`claiming tickets and submitting pull requests
570 </internals/contributing/writing-code/submitting-patches>`.
571 It covers Trac etiquette, how to claim tickets for yourself, expected
572 coding style (both for code and docs), and many other important details.
573 * First time contributors should also read Django's :doc:`documentation
574 for first time contributors</internals/contributing/new-contributors/>`.
575 It has lots of good advice for those of us who are new to helping out
576 with Django.
577 * After those, if you're still hungry for more information about
578 contributing, you can always browse through the rest of
579 :doc:`Django's documentation on contributing</internals/contributing/index>`.
580 It contains a ton of useful information and should be your first source
581 for answering any questions you might have.
582
583 Finding your first real ticket
584 ------------------------------
585
586 Once you've looked through some of that information, you'll be ready to go out
587 and find a ticket of your own to contribute to. Pay special attention to
588 tickets with the "easy pickings" criterion. These tickets are often much
589 simpler in nature and are great for first time contributors. Once you're
590 familiar with contributing to Django, you can start working on more difficult
591 and complicated tickets.
592
593 If you just want to get started already (and nobody would blame you!), try
594 taking a look at the list of `easy tickets without a branch`__ and the
595 `easy tickets that have branches which need improvement`__. If you're familiar
596 with writing tests, you can also look at the list of
597 `easy tickets that need tests`__. Remember to follow the guidelines about
598 claiming tickets that were mentioned in the link to Django's documentation on
599 :doc:`claiming tickets and submitting branches
600 </internals/contributing/writing-code/submitting-patches>`.
601
602 __ 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
603 __ 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
604 __ 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
605
606 What's next after creating a pull request?
607 ------------------------------------------
608
609 After a ticket has a branch, it needs to be reviewed by a second set of eyes.
610 After submitting a pull request, update the ticket metadata by setting the
611 flags on the ticket to say "has patch", "doesn't need tests", etc, so others
612 can find it for review. Contributing doesn't necessarily always mean writing
613 code from scratch. Reviewing open pull requests is also a very helpful
614 contribution. See :doc:`/internals/contributing/triaging-tickets` for details.