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

Перед запуском набора тестов войдите в каталог Django tests/ с помощью команды cd 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.shortcuts. Сначала мы напишем тест, который попытается использовать функцию и проверит, что ее вывод выглядит правильно.

Перейдите в папку 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()``
================

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

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

После фиксации изменения отправьте его на свой форк на 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 по заявке на тикеты и отправке патчей.

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

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