Writing your first contribution for Django¶

Вступление¶

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

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

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

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

Установка Git¶

For this tutorial, you’ll need Git installed to download the current development version of Django and to generate a branch for the changes you make.

Чтобы проверить, установлен ли у вас 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\

The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when writing your first contribution.

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

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

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

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

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

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

Creating a branch¶

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

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

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

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

In most cases, for a contribution to be accepted into Django it has to include tests. For bug fix contributions, this means writing a regression test to ensure that the bug is never reintroduced into Django later on. A regression test should be written in such a way that it will fail while the bug still exists and pass once the bug has been fixed. For contributions containing new features, you’ll need to include tests which ensure that the new features are working correctly. They too should fail when the new feature is not present, and then pass once it has been implemented.

A good way to do this is to write your new tests first, before making any changes to the code. This style of development is called test-driven development and can be applied to both entire projects and single changes. After writing your tests, you then run them to make sure that they do indeed fail (since you haven’t fixed that bug or added that feature yet). If your new tests don’t fail, you’ll need to fix them so that they do. After all, a regression test that passes regardless of whether a bug is present is not very helpful at preventing that bug from reoccurring down the road.

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

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 во второй раз¶

Once you’ve verified that your changes and test are working correctly, it’s a good idea to run the entire Django test suite to verify that your change hasn’t introduced any bugs into other areas of Django. While successfully passing the entire test suite doesn’t guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed.

Чтобы запустить весь набор тестов 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, который будет создан.

Предварительный просмотр ваших изменений¶

Now it’s time to review the changes made in the branch. To stage all the changes ready for commit, run:

$ 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')

When you’re done previewing the changes, hit the q key to return to the command line. If the diff looked okay, it’s time to commit the changes.

Committing the changes¶

Чтобы зафиксировать изменения:

$ git commit

...\> git commit

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

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

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

After committing the changes, send it to your fork on GitHub (substitute «ticket_99999» with the name of your branch if it’s different):

$ git push origin ticket_99999

...\> git push origin ticket_99999

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

Please don’t do it for this tutorial, but on the next page that displays a preview of the changes, you would click «Create pull request».

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

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

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