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

Введение

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

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

Для кого предназначен этот учебник?

Для этого учебника мы предполагаем, что у вас есть хотя бы базовое понимание того, как работает 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 — получить копию исходного кода. Сначала cделайте форк 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 «main» не всегда может быть стабильной. При разработке на «main» вы можете проверить построения непрерывной интеграции Django, чтобы определить, связаны ли сбои с вашим компьютером или они также присутствуют в официальных сборках Django. Если вы нажмете, чтобы просмотреть конкретный сбор, вы сможете просмотреть «Матрицу конфигурации», которая показывает сбои, разбитые по версиям Python и базам данных.

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

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

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

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

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

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

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

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

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

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

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

Перейдите в папку Django tests/shortcuts/ и создайте новый файл 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 по заявке на задачи и отправке исправлений.

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

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