Написание вашего первого патча для 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

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

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

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

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

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

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

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

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