Написание вашего первого вклада в 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 tests/ с помощью команды cd tests и установите зависимости тестов, выполнив:

$ python -m pip install -r requirements/py3.txt

...\> py -m pip install -r requirements\py3.txt

Если во время установки возникнет ошибка, на вашем компьютере может отсутствовать зависимость для одного или нескольких пакетов Python. Обратитесь к документации по неисправному пакету или выполните поиск в Интернете с сообщением об ошибке, которое вы получили.

Теперь мы готовы запустить набор тестов:

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

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

Теперь для нашего практического примера.

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