Написание вашего первого патча для 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 «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 , чтобы убедиться, что это действительно происходит. Перейдите в каталог 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 bit, см. Написание документации. На этой странице также объясняется, как создать локальную копию документации для предварительного просмотра сгенерированного 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. Ваша ветка будет отображаться в разделе «Ваши недавно отправленные ветки». Нажмите «Compare & pull request» рядом с ней.

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

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

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

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

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

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

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

Нахождение вашего первого реального билета

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

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

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

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