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

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

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