Ваша первая доработка для Django

Введение

Хотите немного помочь сообществу? Возможно, вы нашли ошибку в Django, которую хотелось бы исправить, или хотите добавить небольшую функцию (но помните, что предложения по новым функциям должны соответствовать процессу предложения новых функций).

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

Правила поведения

Как участник сообщества вы можете помочь нам сделать сообщество Django открытым и дружелюбным для всех. Прочитайте и соблюдайте наши правила поведения.

Установка Git

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

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

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

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

Первый шаг к участию в разработке Django — получить копию исходного кода. Сначала создайте форк Django на GitHub. Затем в командной строке с помощью команды cd перейдите в каталог, где будет храниться ваша локальная копия Django.

Скачайте репозиторий с исходным кодом 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\

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

Первый запуск набора тестов Django

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

Перед запуском набора тестов перейдите в каталог tests/ Django с помощью команды cd tests и установите зависимости для тестирования, выполнив:

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

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

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

Теперь можно запустить набор тестов:

$ ./runtests.py

...\> runtests.py 

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

Во время выполнения набора тестов Django на экране будет появляться последовательность символов, отображающих состояние каждого завершившегося теста. E означает, что во время теста возникла ошибка, а F — что не прошли проверки утверждений теста. И то и другое считается неудачным результатом теста. Символы x и s обозначают соответственно ожидаемые неудачные результаты и пропущенные тесты. Точки обозначают успешно пройденные тесты.

Тесты обычно пропускаются из-за отсутствия внешних библиотек, необходимых для их выполнения. Список зависимостей см. в разделе Запуск всех тестов; обязательно установите библиотеки, необходимые для тестов, связанных с вашими изменениями (для этого руководства они не понадобятся). Некоторые тесты относятся только к определённой СУБД и пропускаются, если тестирование выполняется не с ней. В настройках по умолчанию используется SQLite. Информацию о запуске тестов с другой СУБД см. в разделе Использование другого модуля настроек.

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

Обратите внимание: последняя версия ветки Django «main» не всегда стабильна. При разработке в ветке «main» можно проверить результаты непрерывной интеграции Django, чтобы понять, связаны ли ошибки с вашим компьютером или они также возникают в официальных сборках Django. Если открыть конкретную сборку, можно посмотреть «матрицу конфигураций» (Configuration Matrix), в которой ошибки сгруппированы по версиям Python и используемым СУБД.

Работа над одобренной новой функцией

В этом руководстве мы рассмотрим вымышленный «принятый тикет». Вот его условие:

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

Создание ветки

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

$ 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"

Теперь нужно убедиться, что написанный ранее тест проходит, то есть добавленный код работает правильно. Снова перейдите в каталог tests/ Django и выполните:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Все тесты должны пройти. Если это не так, проверьте, что вы добавили функцию в нужный файл.

Второй запуск набора тестов Django

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

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

$ ./runtests.py

...\> runtests.py 

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

Это новая функция, поэтому её нужно задокументировать. Откройте файл docs/topics/http/shortcuts.txt и добавьте в конец файла следующее:

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

.. function:: make_toast()

.. versionadded:: 2.2

Returns ``'toast'``.

Поскольку новая функция появится в одном из будущих выпусков, её также нужно добавить в примечания к выпуску следующей версии Django. Откройте примечания к последней версии в docs/releases/. На момент написания этой документации это 2.2.txt. Добавьте примечание под заголовком «Небольшие функции»:

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

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

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

Просмотр изменений

Теперь пора проверить изменения, внесённые в ветку. Чтобы подготовить все изменения к коммиту, выполните:

$ git add --all

...\> git add --all

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

$ 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')

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

Фиксация изменений

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

$ git commit

...\> git commit

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

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

Отправка коммита и создание pull request

После фиксации изменений отправьте их в свой форк на GitHub (если ваша ветка называется иначе, замените «ticket_99999» её именем):

$ git push origin ticket_99999

...\> git push origin ticket_99999

Создать pull request можно на странице Django на GitHub. В разделе «Your recently pushed branches» вы увидите свою ветку. Нажмите рядом с ней «Compare & pull request».

Не делайте этого для данного руководства, но на следующей странице, где будет показан предварительный просмотр изменений, нужно было бы нажать «Create pull request».

Что дальше

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

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