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

Введение

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

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

Для кого это руководство?

Смотрите также

Если вы ищете справочную информацию о том, как отправлять исправления, см. Документацию по отправке исправлений .

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

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

Но по большей части это руководство направлено на то, чтобы объяснить как можно больше, чтобы оно могло быть подходящим для как можно большего числа людей.

Где получить помощь:

Если у вас возникнут какие-либо проблемы после этого руководства, вы можете написать (на английском языке) django-developers или использовать IRC-канал # django-dev на irc.freenode.net (или # django-fr на французском языке), чтобы поговорить с другие пользователи Django, которые могут вам помочь.

Каково содержание этого руководства?

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

  • установка Git,
  • Скачивание копии разрабатываемой версии Django.
  • запуск набора тестов Django,
  • написать тест для вашего исправления,
  • написание кода патча,
  • тестирование вашего патча,
  • подача заявки на взнос,
  • источники дополнительной информации.

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

Python 3 необходим!

Текущая версия Django больше не поддерживает Python 2.7. Получите Python 3 со страницы загрузок Python или через диспетчер пакетов вашей системы.

Для пользователей Windows

См. Раздел Установка Python в документации Windows для получения дополнительных указаний.

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

Как участник, вы можете помочь нам сохранить открытое и доброжелательное сообщество 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, что сокращает объем передаваемых данных с ~ 250 МБ до ~ 70 МБ.--depth 1 git clone

Теперь, когда у вас есть локальная копия 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

Вы должны активировать виртуальную среду каждый раз, когда открываете новое окно терминала.

Для пользователей Windows

Чтобы активировать виртуальную среду в Windows, запустите:

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

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

Заметка

Для этого руководства и заявки, над которой мы работаем, достаточно протестировать с SQLite. Однако можно (а иногда и необходимо) запускать тесты с использованием другой базы данных .

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

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

Билет № 99999 - Разрешить тост

Django должен предоставить функцию, django.shortcuts.make_toast() которая возвращает 'toast' .

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

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

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

$ git checkout -b ticket_99999
...\> git checkout -b ticket_99999

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

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

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

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

Теперь перейдем к сути дела.

Написание теста на билет № 99999

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

Зайдите в папку tests/shortcuts/ и создайте новый файл 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 - это просмотреть документацию по написанию и запуску тестов .
  • Dive Into Python (бесплатная онлайн-книга для разработчиков, плохо знакомых с Python) содержит отличный раздел, посвященный началу работы с модульным тестированием .
  • После этих чтений, если вы хотите переварить еще немного материала, вы всегда можете просмотреть документацию по Python unittest .

Запуск новых тестов

Поскольку мы не внесли никаких изменений django.shortcuts , наш тест должен завершиться неудачно. Давайте запустим все тесты файла, shortcuts чтобы убедиться, что это действительно так. Перейдите в каталог tests/ Django и запустите:

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

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

Прежде чем вы начнете больше участвовать в написании исправлений для Django, неплохо получить дополнительную информацию для участников:

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

Найдите свой первый настоящий билет

Изучив часть этой информации, вы готовы к поиску заявки, для которой вы напишете исправление. Начните с билетов, помеченных как «Легкий сбор» в качестве приоритета. Эти билеты часто имеют более простой характер и являются идеальной целью для новых участников. Когда вы освоитесь с Django, вы можете перейти к написанию исправлений для более сложных тикетов.

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

Что происходит после создания запроса на взнос?

Если в билете есть исправление, его должна перечитать вторая пара глаз. После отправки запроса на участие обновите метаданные билета, установив флажки «имеет патч», «не нужны тесты» и т. Д., Чтобы другие могли найти их для просмотра. корректура. Участие не обязательно означает написание патча с нуля. Обзор существующих исправлений также является очень полезным вкладом. Подробнее см. Сортировка билетов .

Copyright ©2021 All rights reserved