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

Введение

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

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

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

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

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

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

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

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

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

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

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

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

Установка Git

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

Чтобы проверить, установлен ли у вас 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

Вам необходимо активировать виртуальную среду всякий раз, когда вы открываете новое окно терминала. 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 в первый раз

При внесении изменений в 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 не всегда стабилен. При разработке с использованием мастер-ветки вы можете проверить непрерывную интеграцию 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. Вы увидите вашу ветку в разделе «Ваши недавно отправленные ветки». Нажмите «Сравнить и создать запрос на вытягивание» рядом с ней.

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

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

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

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

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

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

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

Поиск вашей первой реальной задачи

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

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

Что делать после создания pull-запроса?

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