Написание вашего первого вклада в Django

Введение

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

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

Для кого предназначен этот учебник?

Для этого учебника мы предполагаем, что вы имеете хотя бы базовое понимание работы Django. Это означает, что вы должны быть знакомы с существующими учебниками по созданию вашего первого приложения Django. Кроме того, вы должны хорошо понимать сам Python. Но если вы этого не знаете, Dive Into Python — отличная (и бесплатная) онлайн-книга для начинающих программистов Python.

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

В основном этот учебник пытается объяснить как можно больше, чтобы он был полезен самой широкой аудитории.

Что охватывает этот учебник?

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

• Установка Git.
• Загрузка копии тестовой версии 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. Если вы никогда раньше не запускали набор тестов Django, неплохо было бы запустить его один раз предварительно, чтобы познакомиться с его выводом.

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

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

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

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

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

Создание ветки

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

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

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

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

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

Написание теста для билета #99999

Чтобы разрешить этот билет, мы добавим функцию make_toast() в модуль django.shortcuts. Сначала мы напишем тест, который пытается использовать функцию и проверяет, что её вывод выглядит правильно.

Перейдите в папку 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, чтобы убедиться, что это действительно происходит. Перейдите в каталог 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()``
================

.. 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. Вы увидите свою ветку в разделе «Ваши недавно отправленные ветки». Нажмите «Сравнить и создать запрос на вытягивание» рядом с ней.

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

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

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

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

Дополнительная информация для новых участников

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

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

Нахождение вашей первой реальной задачи

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

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

Что дальше после создания pull-запроса?

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