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

Перед запуском набора тестов установите его зависимости, cd-ing в tests/каталог Django, а затем запустив:

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

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

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

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

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

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

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

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

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

Теперь наш практический пример.

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), 'toast')

$ ./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'

Теперь нам нужно убедиться, что тест, который мы написали ранее, прошел, чтобы мы могли видеть, правильно ли работает добавленный код. Снова перейдите в tests/каталог Django и запустите:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Все должно пройти. Если это не так, убедитесь, что вы правильно добавили функцию в правильный файл.

Второй запуск тестового пакета Django ¶

Убедившись, что ваш патч и ваш тест работают правильно, рекомендуется запустить весь набор тестов Django, чтобы убедиться, что ваше изменение не внесло никаких ошибок в другие области Django. Хотя успешное прохождение всего набора тестов не гарантирует, что ваш код не содержит ошибок, это помогает выявить множество ошибок и регрессов, которые в противном случае могли бы остаться незамеченными.

Чтобы запустить весь набор тестов Django, cdперейдите в tests/ каталог Django и запустите:

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