Написание вашего первого патча для Django

Введение

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

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

Для кого этот учебник?

Для этого учебника мы предполагаем, что у вас есть, по крайней мере, базовые знания о работе Django. Это означает, что вы должны быть знакомы с существующими учебниками по созданию вашего первого приложения Django. Кроме того, вы должны хорошо понимать сам Python. Но если нет, Dive Into Python — фантастическая (и бесплатная) онлайн-книга для начинающих программистов Python.

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

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

Что охватывает этот учебник?

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

• Установка Git.
• Загрузка копии версии разработки Django.
• Запуск тестового набора Django.
• Написание теста для вашего патча.
• Написание кода для вашего патча.
• Тестирование вашего патча.
• Отправка запроса на включение.
• Где найти дополнительную информацию.

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

Кодекс поведения

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

Установка Git

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

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

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

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

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

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

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

...\> git clone git@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

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

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

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

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

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

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

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

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

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

$ pip install -r requirements/py3.txt

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

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

Теперь мы готовы запустить тестовый набор. Если вы используете GNU/Linux, macOS или другой дистрибутив Unix, запустите:

$ ./runtests.py

...\> runtests.py 

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

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

Пропущенные тесты, как правило, связаны с отсутствием внешних библиотек, необходимых для выполнения теста; см. Запуск всех тестов для списка зависимостей и убедитесь, что установлены все необходимые для тестов, связанные с изменениями, которые вы вносите (нам они не понадобятся в этом учебнике). Некоторые тесты специфичны для определенного бэкенда базы данных и будут пропущены, если не выполняются с этим бэкендом. SQLite — это бэкенд базы данных по умолчанию. Чтобы запустить тесты с использованием другого бэкенда, см. Использование другого модуля настроек.

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

Обратите внимание, что последняя версия Django master может не всегда быть стабильной. При разработке с использованием master вы можете проверить непрерывные интеграционные сборки Django, чтобы определить, являются ли сбои специфичными для вашей машины или также присутствуют в официальных сборках Django. Если вы нажмёте, чтобы просмотреть определённую сборку, вы сможете просмотреть «Матрицу конфигурации», которая показывает сбои, разбитые по версиям Python и базам данных.

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

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

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

Создание ветви для вашего исправления

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

Написание тестов для вашего задания

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

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

Теперь для нашего практического примера.

Написание теста для задания #99999

Для решения этого задания мы добавим функцию make_toast(), в модуль django. Сначала мы напишем тест, который попытается использовать функцию и проверит, что её вывод корректен.

Перейдите в папку tests/shortcuts/ Django и создайте новый файл test_make_toast.py. Добавьте следующий код:

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


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

Этот тест проверяет, что функция make_toast() возвращает 'toast'.

Запуск вашего нового теста

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

$ ./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'

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

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

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

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

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

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

$ ./runtests.py

...\> runtests.py 

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

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

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

Отправка коммита и создание запроса на вытягивание

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

$ git push origin ticket_99999

...\> git push origin ticket_99999

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

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

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

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

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

Дополнительная информация для новых участников

Прежде чем слишком углубляться в написание исправлений для Django, есть ещё немного информации о сотрудничестве, которую, вероятно, стоит рассмотреть:

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

Поиск вашего первого реального билета

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

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

Что дальше после создания запроса на вытягивание?

После того, как билет содержит исправление, его необходимо проверить второй парой глаз. После отправки запроса на вытягивание обновите метаданные билета, установив флажки в билете, чтобы указать «есть исправление», «не требует тестирования» и т. д., чтобы другие могли найти его для проверки. Сотрудничество не обязательно всегда означает написание исправления с нуля. Проверка существующих исправлений также является очень полезным вкладом. См. Триаж билетов для получения подробностей.