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

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

Вы должны знать, что master (самая последняя) версия Django не всегда стабильна. При разработке этого выпуска вы можете проверить сборки непрерывной интеграции 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, перейдите в каталог 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.