| 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. |