Введение¶

Заинтересованы в небольшой обратной помощи сообществу? Может быть Вы нашли ошибку в Django, которую хотели бы видеть исправленной, либо имеете небольшое новшество, которое хотели бы добавить.

Contributing back to Django itself is the best way to see your own concerns addressed. This may seem daunting at first, but it’s a well-traveled path with documentation, tooling, and a community to support you. We’ll walk you through the entire process, so you can learn by example.

Нормы поведения¶

Как участник, вы можете помочь нам сохранить сообщество Django открытым и инклюзивным. Пожалуйста, прочитайте и соблюдайте наш «Кодекс поведения <https://www.djangoproject.com/conduct/>»_.

Установка Git¶

Для этого урока Вам потребуется установить git, чтобы загрузить текущую разрабатываемую версию Django, а также для создания патч-файлов Ваших изменений.

Чтобы проверить, доступен ли git или Вы ещё не устанавливали его, введите git в командной строке. Если Вы получите сообщение о том, что эта команда не может быть найдена, Вам придется скачать и установить его, см. страницу скачивания Git.

Если Вы не знакомы с git, то всегда можете узнать подробнее о командах (после его установки) путем ввода git help в командной строке.

Получение копии разрабатываемой версии Django¶

The first step to contributing to Django is to get a copy of the source code. First, fork Django on GitHub. Then, from the command line, use the cd command to navigate to the directory where you’ll want your local copy of Django to live.

Загрузите репозиторий исходного кода Django, используя следующую команду:

$ git clone https://github.com/YourGitHubName/django.git

...\> git clone https://github.com/YourGitHubName/django.git

Теперь, когда у вас есть локальная копия Django, вы можете установить ее так же, как если бы вы устанавливали любой пакет, используя pip. Самый удобный способ сделать это — использовать виртуальную среду, которая представляет собой функцию, встроенную в Python, которая позволяет вам хранить отдельный каталог установленных пакетов для каждого из ваших проектов, чтобы они не мешали друг другу.

Хорошая идея — хранить все ваши виртуальные среды в одном месте, например, в .virtualenvs/ в вашем домашнем каталоге.

Создайте новую виртуальную среду, выполнив:

$ python3 -m venv ~/.virtualenvs/djangodev

...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev

Путь — это место, где новая среда будет сохранена на вашем компьютере.

Последним шагом в настройке виртуальной среды является ее активация:

$ source ~/.virtualenvs/djangodev/bin/activate

Если команда source недоступна, вы можете попробовать использовать вместо нее точку:

$ . ~/.virtualenvs/djangodev/bin/activate

Вам необходимо активировать виртуальную среду каждый раз, когда вы открываете новое окно терминала.

...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

Имя активированной в данный момент виртуальной среды отображается в командной строке, чтобы помочь вам отслеживать, какую из них вы используете. Все, что вы устанавливаете через pip, пока отображается это имя, будет установлено в этой виртуальной среде, изолированной от других сред и общесистемных пакетов.

Установите ранее клонированную копию Django:

$ python -m pip install -e /path/to/your/local/clone/django/

...\> py -m pip install -e \path\to\your\local\clone\django\

The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when writing your first patch.

Запуск коллекции тестов Django впервые¶

При работе с Django очень важно, чтобы изменения вашего кода не приводили к ошибкам в других областях Django. Один из способов проверить, что Django продолжает работать после внесения изменений, — запустить набор тестов Django. Если все тесты пройдены, вы можете быть уверены, что ваши изменения работают и не нарушают работу других частей Django. Если вы никогда раньше не запускали набор тестов Django, рекомендуется запустить его один раз заранее, чтобы ознакомиться с его результатами.

Before running the test suite, install its dependencies by cd-ing into the Django tests/ directory and then running:

$ python -m pip install -r requirements/py3.txt

...\> py -m pip install -r requirements\py3.txt

Если во время установки вы столкнулись с ошибкой, возможно, в вашей системе отсутствует зависимость для одного или нескольких пакетов Python. Обратитесь к документации неисправного пакета или выполните поиск в Интернете по сообщению об ошибке, с которым вы столкнулись.

Now we are ready to run the test suite. If you’re using GNU/Linux, macOS, or some other flavor of Unix, run:

$ ./runtests.py

...\> runtests.py 

Теперь сядьте и расслабьтесь. Весь набор тестов Django состоит из тысяч тестов, и их запуск занимает как минимум несколько минут, в зависимости от скорости вашего компьютера.

While Django’s test suite is running, you’ll see a stream of characters representing the status of each test as it completes. 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.

Skipped tests are typically due to missing external libraries required to run the test; see Выполнение всех тестов for a list of dependencies and be sure to install any for tests related to the changes you are making (we won’t need any for this tutorial). Some tests are specific to a particular database backend and will be skipped if not testing with that backend. SQLite is the database backend for the default settings. To run the tests using a different backend, see Использование другого модуля settings.

Once the tests complete, you should be greeted with a message informing you whether the test suite passed or failed. Since you haven’t yet made any changes to Django’s code, the entire test suite should pass. If you get failures or errors make sure you’ve followed all of the previous steps properly. See Выполнение модульных тестов for more information.

Note that the latest Django master may not always be stable. When developing against master, you can check `Django's continuous integration builds`__ to determine if the failures are specific to your machine or if they are also present in Django’s official builds. If you click to view a particular build, you can view the «Configuration Matrix» which shows failures broken down by Python version and database backend.

Работаем над функцией¶

В этом руководстве мы будем работать с «поддельным билетом» в качестве примера. Вот воображаемые детали:

Теперь мы реализуем эту функцию и связанные с ней тесты.

Creating a branch for your patch¶

Прежде чем вносить какие-либо изменения, создайте новую ветку для заявки:

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

Вы можете выбрать любое имя для ветки, например «ticket_99999». Все изменения, внесенные в эту ветку, будут относиться только к билету и не повлияют на основную копию кода, которую мы клонировали ранее.

Написание тестов для Вашего тикета¶

В большинстве случаев, патч, который будет принят в Django, должен включать тесты. Для патчей, исправляющих ошибки, это означает написание регрессионного тестирования, чтобы гарантировать, что ошибка никогда больше не будет восстановлена в Django. Регрессионный тест должен быть написан таким образом, чтобы он не мог быть выполнен, пока ошибка существует и пройден после того, как ошибка была исправлена. Для патчей, содержащих новые возможности, Вам необходимо включить тесты, которые гарантируют, что эти новые возможности работают правильно. Они тоже должны завершаться ошибкой, когда новая возможность отсутствует, а затем проходить успешно, после её реализации.

Хороший способ сделать это, во-первых, писать новые тесты перед внесением любых изменений в код. Этот тип разработки называется `разработкой через тестирование`__ и может быть применена как к целым проектам, так и к отдельным патчам. После написания тестов, Вам нужно запустить их, чтобы убедиться, что они действительно проваливаются (ведь Вы еще не починили баг или не добавили эту возможность). Если Ваши новые тесты не проваливаются, то необходимо исправить их так, чтобы они это делали. Ведь, регрессионный тест, который проходит независимо от присутствия ошибки - не очень полезная вещь для предотвращения повторения этой ошибки в будущем.

Теперь за наш практический пример.

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), 'toast')

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

ImportError: cannot import name 'make_toast' from 'django.shortcuts'

Написание кода для Вашего тикета¶

Далее мы добавим функцию make_toast().

Перейдите в папку django/ и откройте файл Shortcuts.py. Внизу добавьте:

def make_toast():
    return 'toast'

Now we need to make sure that the test we wrote earlier passes, so we can see whether the code we added is working correctly. Again, navigate to the Django tests/ directory and run:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Everything should pass. If it doesn’t, make sure you correctly added the function to the correct file.

Запуск коллекции тестов Django во второй раз¶

Once you’ve verified that your patch and your test are working correctly, it’s a good idea to run the entire Django test suite 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.

Чтобы запустить весь набор тестов Джанго, скомандуйте cd в Django-директорию tests/ и запустите:

$ ./runtests.py

...\> runtests.py 

Написание документации¶

This is a new feature, so it should be documented. Open the file docs/topics/http/shortcuts.txt and add the following at the end of the file:

``make_toast()``
================

.. versionadded:: 2.2

Returns ``'toast'``.

Since this new feature will be in an upcoming release it is also added to the release notes for the next version of Django. Open the release notes for the latest version in docs/releases/, which at time of writing is 2.2.txt. Add a note under the «Minor Features» header:

:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~

* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

Для более подробной информации о написании документации, в том числе объяснению того, что такое versionadded, см. Написание документации. Эта страница также включает объяснение о том, как построить копию документации локально так, чтобы Вы могли просматривать сгенерированный HTML-код.

Previewing your changes¶

Now it’s time to go through all the changes made in our patch. To stage all the changes ready for commit, run:

$ git add --all

...\> git add --all

Then display the differences between your current copy of Django (with your changes) and the revision that you initially checked out earlier in the tutorial with:

$ git diff --cached

...\> git diff --cached

Используйте клавиши со стрелками для перемещения вверх и вниз.

diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):

     # Finally, fall back and assume it's a URL
     return to
+
+
+def make_toast():
+    return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
 Minor features
 --------------

+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
 :mod:`django.contrib.admin`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
         my_objects = list(MyModel.objects.filter(published=True))
         if not my_objects:
             raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+    def test_make_toast(self):
+        self.assertEqual(make_toast(), 'toast')

When you’re done previewing the patch, hit the q key to return to the command line. If the patch’s content looked okay, it’s time to commit the changes.

Committing the changes in the patch¶

Чтобы зафиксировать изменения:

$ git commit

...\> git commit

Откроется текстовый редактор для ввода сообщения фиксации. Следуйте рекомендациям по сообщениям о фиксации и напишите сообщение типа:

Fixed #99999 -- Added a shortcut function to make toast.

Нажатие коммита и выполнение запроса на извлечение¶

After committing the patch, send it to your fork on GitHub (substitute «ticket_99999» with the name of your branch if it’s different):

$ git push origin ticket_99999

...\> git push origin ticket_99999

Вы можете создать запрос на включение, посетив страницу Django GitHub. Вы увидите свою ветку в разделе «Недавно добавленные ветки». Нажмите «Сравнить и запросить извлечение» рядом с ним.

Please don’t do it for this tutorial, but on the next page that displays a preview of the patch, you would click «Create pull request».

Следующие шаги¶

Поздравляем, вы узнали, как сделать запрос на включение в Django! Подробности о более продвинутых методах, которые могут вам понадобиться, находятся в Работа с Git и GitHub.

Теперь вы можете применить эти навыки с пользой, помогая улучшить кодовую базу Django.