Введение¶

Заинтересованы в небольшой обратной помощи сообществу? Может быть Вы нашли ошибку в Django, которую хотели бы видеть исправленной, либо имеете небольшое новшество, которое хотели бы добавить.

Contributing back to Django itself is the best way to see your own concerns addressed. This may seem daunting at first, but it’s a well-traveled path with documentation, tooling, and a community to support you. We’ll walk you through the entire process, so you can learn by example.

Нормы поведения¶

Как участник, вы можете помочь нам сохранить сообщество Django открытым и инклюзивным. Пожалуйста, прочитайте и соблюдайте наш «Кодекс поведения <https://www.djangoproject.com/conduct/>»_.

Установка Git¶

Для работы с этим руководством вам понадобится установленный Git, чтобы загрузить текущую разрабатываемую версию Django и создать ветку для внесенных вами изменений.

Чтобы проверить, доступен ли git или Вы ещё не устанавливали его, введите git в командной строке. Если Вы получите сообщение о том, что эта команда не может быть найдена, Вам придется скачать и установить его, см. страницу скачивания Git.

Если Вы не знакомы с git, то всегда можете узнать подробнее о командах (после его установки) путем ввода git help в командной строке.

Получение копии разрабатываемой версии Django¶

The first step to contributing to Django is to get a copy of the source code. First, fork Django on GitHub. Then, from the command line, use the cd command to navigate to the directory where you’ll want your local copy of Django to live.

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

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

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

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

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

$ ./runtests.py

...\> runtests.py 

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

While Django’s test suite is running, you’ll see a stream of characters representing the status of each test as it completes. E indicates that an error was raised during a test, and F indicates that a test’s assertions failed. Both of these are considered to be test failures. Meanwhile, x and s indicated expected failures and skipped tests, respectively. Dots indicate passing tests.

Skipped tests are typically due to missing external libraries required to run the test; see Выполнение всех тестов for a list of dependencies and be sure to install any for tests related to the changes you are making (we won’t need any for this tutorial). Some tests are specific to a particular database backend and will be skipped if not testing with that backend. SQLite is the database backend for the default settings. To run the tests using a different backend, see Использование другого модуля settings.

Once the tests complete, you should be greeted with a message informing you whether the test suite passed or failed. Since you haven’t yet made any changes to Django’s code, the entire test suite should pass. If you get failures or errors make sure you’ve followed all of the previous steps properly. See Выполнение модульных тестов for more information.

Обратите внимание, что последняя «основная» ветка 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"

Now we need to make sure that the test we wrote earlier passes, so we can see whether the code we added is working correctly. Again, navigate to the Django tests/ directory and run:

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

Everything should pass. If it doesn’t, make sure you correctly added the function to the correct file.

Запуск коллекции тестов Django во второй раз¶

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

:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~

* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

Для более подробной информации о написании документации, в том числе объяснению того, что такое versionadded, см. Написание документации. Эта страница также включает объяснение о том, как построить копию документации локально так, чтобы Вы могли просматривать сгенерированный HTML-код.

Previewing your changes¶

Теперь пришло время рассмотреть изменения, внесенные в ветку. Чтобы подготовить все изменения к фиксации, запустите:

$ git add --all

...\> git add --all

Then display the differences between your current copy of Django (with your changes) and the revision that you initially checked out earlier in the tutorial with:

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