Составление Вашего первого патча для Django

Введение

Заинтересованы в небольшой обратной помощи сообществу? Может быть Вы нашли ошибку в 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.

Для кого это учебник?

См.также

Если вам нужна инструкция как отправлять патчи, смотрите Submitting patches.

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

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

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

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

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

Какие вопросы охватывает данный учебник?

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

  • Установка Git.
  • Downloading a copy of Django’s development version.
  • Запуск коллекции тестов Django.
  • Написание теста для патча.
  • Написание кода для патча.
  • Тестирование Вашего патча.
  • Submitting a pull request.
  • Где искать дополнительные сведения.

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

Python 3 required!

The current version of Django doesn’t support Python 2.7. Get Python 3 at Python’s download page or with your operating system’s package manager.

For Windows users

When installing Python on Windows, make sure you check the option «Add python.exe to Path», so that it is always available on the command line.

Code of Conduct

As a contributor, you can help us keep the Django community open and inclusive. Please read and follow our Code of 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.

Download the Django source code repository using the following command:

$ git clone https://github.com/YourGitHubName/django.git
...\> git clone https://github.com/YourGitHubName/django.git

Low bandwidth connection?

You can add the --depth 1 argument to git clone to skip downloading all of Django’s commit history, which reduces data transfer from ~250 MB to ~70 MB.

Now that you have a local copy of Django, you can install it just like you would install any package using pip. The most convenient way to do so is by using a virtual environment, which is a feature built into Python that allows you to keep a separate directory of installed packages for each of your projects so that they don’t interfere with each other.

It’s a good idea to keep all your virtual environments in one place, for example in .virtualenvs/ in your home directory.

Create a new virtual environment by running:

$ python3 -m venv ~/.virtualenvs/djangodev
...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev

The path is where the new environment will be saved on your computer.

The final step in setting up your virtual environment is to activate it:

$ source ~/.virtualenvs/djangodev/bin/activate

If the source command is not available, you can try using a dot instead:

$ . ~/.virtualenvs/djangodev/bin/activate

You have to activate the virtual environment whenever you open a new terminal window. virtualenvwrapper__ is a useful tool for making this more convenient.

For Windows users

To activate your virtual environment on Windows, run:

...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

or you can install a Windows version of virtualenvwrapper and then use:

...\> workon djangodev

The name of the currently activated virtual environment is displayed on the command line to help you keep track of which one you are using. Anything you install through pip while this name is displayed will be installed in that virtual environment, isolated from other environments and system-wide packages.

Go ahead and install the previously cloned copy of 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 patch.

Creating projects with a local copy of Django

It may be helpful to test your local changes with a Django project. First you have to create a new virtual environment, install the previously cloned local copy of Django in editable mode, and create a new Django project outside of your local copy of Django. You will immediately see any changes you make to Django in your new project, which is of great help when writing your first patch.

Запуск коллекции тестов Django впервые

When contributing to Django it’s very important that your code changes don’t introduce bugs into other areas of Django. One way to check that Django still works after you make your changes is by running Django’s test suite. If all the tests still pass, then you can be reasonably sure that your changes work and haven’t broken other parts Django. If you’ve never run Django’s test suite before, it’s a good idea to run it once beforehand to get familiar with its output.

Before running the test suite, install its dependencies by cd-ing into the Django tests/ directory and then running:

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

If you encounter an error during the installation, your system might be missing a dependency for one or more of the Python packages. Consult the failing package’s documentation or search the Web with the error message that you encounter.

Now we are ready to run the test suite. If you’re using GNU/Linux, macOS, or some other flavor of Unix, run:

$ ./runtests.py
...\> runtests.py 

Now sit back and relax. Django’s entire test suite has thousands of tests, and it takes at least a few minutes run, depending on the speed of your computer.

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 Running all the tests 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 Using another settings module.

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 Running the unit tests for more information.

Note that the latest Django master may not always be stable. When developing against master, you can check `Django's continuous integration builds`__ to determine if the failures are specific to your machine or if they are also present in Django’s official builds. If you click to view a particular build, you can view the «Configuration Matrix» which shows failures broken down by Python version and database backend.

Примечание

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

Working on a feature

For this tutorial, we’ll work on a «fake ticket» as a case study. Here are the imaginary details:

Ticket #99999 – Allow making toast

Django should provide a function django.shortcuts.make_toast() that returns 'toast'.

We’ll now implement this feature and associated tests.

Creating a branch for your patch

Before making any changes, create a new branch for the ticket:

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

You can choose any name that you want for the branch, «ticket_99999» is an example. All changes made in this branch will be specific to the ticket and won’t affect the main copy of the code that we cloned earlier.

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

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

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

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

Writing a test for ticket #99999

In order to resolve this ticket, we’ll add a make_toast() function to the top-level django module. First we are going to write a test that tries to use the function and check that its output looks correct.

Navigate to Django’s tests/shortcuts/ folder and create a new file test_make_toast.py. Add the following code:

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), 'toast')

This test checks that the make_toast() returns 'toast'.

Но вся эта суть тестирования выглядит сложновато…

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

Запуск Вашего нового теста

Since we haven’t made any modifications to django.shortcuts yet, our test should fail. Let’s run all the tests in the shortcuts folder to make sure that’s really what happens. cd to the Django tests/ directory and run:

$ ./runtests.py shortcuts
...\> runtests.py shortcuts

If the tests ran correctly, you should see one failure corresponding to the test method we added, with this error:

ImportError: cannot import name 'make_toast' from 'django.shortcuts'

If all of the tests passed, then you’ll want to make sure that you added the new test shown above to the appropriate folder and file name.

Написание кода для Вашего тикета

Next we’ll be adding the make_toast() function.

Navigate to the django/ folder and open the shortcuts.py file. At the bottom, add:

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

Once you’ve verified that your patch and your 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.

Чтобы запустить весь набор тестов Джанго, скомандуйте cd в Django-директорию tests/ и запустите:

$ ./runtests.py
...\> runtests.py 

Написание документации

This is a new feature, so it should be documented. Open the file docs/topics/http/shortcuts.txt and add the following at the end of the file:

``make_toast()``
================

.. versionadded:: 2.2

Returns ``'toast'``.

Since this new feature will be in an upcoming release it is also added to the release notes for the next version of Django. Open the release notes for the latest version in docs/releases/, which at time of writing is 2.2.txt. Add a note under the «Minor Features» header:

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

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

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

Previewing your changes

Now it’s time to go through all the changes made in our patch. To stage all the changes ready for commit, run:

$ 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

Use the arrow keys to move up and down.

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 patch, hit the q key to return to the command line. If the patch’s content looked okay, it’s time to commit the changes.

Committing the changes in the patch

To commit the changes:

$ git commit
...\> git commit

This opens up a text editor to type the commit message. Follow the commit message guidelines and write a message like:

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

Pushing the commit and making a pull request

After committing the patch, 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

You can create a pull request by visiting the Django GitHub page. You’ll see your branch under «Your recently pushed branches». Click «Compare & pull request» next to it.

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

Next steps

Congratulations, you’ve learned how to make a pull request to Django! Details of more advanced techniques you may need are in Working with Git and GitHub.

Now you can put those skills to good use by helping to improve Django’s codebase.

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

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

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

Поиск Вашего первого реального тикета

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

If you just want to get started already (and nobody would blame you!), try taking a look at the list of `easy tickets that need patches`__ and the `easy tickets that have patches which need improvement`__. If you’re familiar with writing tests, you can also look at the list of `easy tickets that need tests`__. Remember to follow the guidelines about claiming tickets that were mentioned in the link to Django’s documentation on claiming tickets and submitting patches.

What’s next after creating a pull request?

After a ticket has a patch, it needs to be reviewed by a second set of eyes. After submitting a pull request, update the ticket metadata by setting the flags on the ticket to say «has patch», «doesn’t need tests», etc, so others can find it for review. Contributing doesn’t necessarily always mean writing a patch from scratch. Reviewing existing patches is also a very helpful contribution. See Triaging tickets for details.