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

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

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

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

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

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

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

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

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

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

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

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

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

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