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

Вступление¶

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

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

Кодекс поведения¶

Как участник, вы можете помочь нам сохранить сообщество Django открытым и инклюзивным. Пожалуйста, читайте и следуйте нашим рекомендациям Code of Conduct.

Установка Git¶

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

Чтобы проверить, установлен ли у вас Git, введите git в командную строку. Если вы получите сообщение о том, что эта команда не найдена, вам придется скачать и установить ее, см. раздел Git’s download page.

Если вы не очень хорошо знакомы с Git, вы всегда можете узнать больше о его командах (после его установки), набрав git help в командной строке.

Получение копии версии Django для разработки¶

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

Before running the test suite, enter the Django tests/ directory using the cd tests command, and install test dependencies by running:

$ 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 является бэкендом базы данных для настроек по умолчанию. Чтобы запустить тесты с использованием другого бэкенда, смотрите Использование другого модуля settings.

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

Обратите внимание, что последняя ветка Django «main» не всегда может быть стабильной. При разработке на «main», вы можете проверить Django’s continuous integration builds, чтобы определить, являются ли сбои специфичными для вашей машины или они также присутствуют в официальных сборках Django. Если вы щелкните для просмотра конкретной сборки, вы можете просмотреть «Матрицу конфигурации», которая показывает сбои в разбивке по версии Python и бэкенду базы данных.

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

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

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

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

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

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

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

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

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

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'

Теперь нам нужно убедиться, что тест, который мы написали ранее, прошел, чтобы мы могли увидеть, правильно ли работает код, который мы добавили. Снова перейдите в каталог 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. Добавьте заметку под заголовком «Minor Features»:

: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

Откроется текстовый редактор для ввода сообщения о фиксации. Следуйте за commit message guidelines и напишите сообщение, например:

Fixed #99999 -- Added a shortcut function to make toast.

Передача фиксации и создание запроса на притяжение¶

После фиксации патча отправьте его в свой форк на GitHub (замените «ticket_99999» на название вашего филиала, если оно другое):

$ git push origin ticket_99999

...\> git push origin ticket_99999

Вы можете создать pull request, посетив страницу Django GitHub page. Вы увидите свою ветку в разделе «Your recently pushed branches». Нажмите «Compare & pull request» рядом с ней.

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

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

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

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