Как внести свой вклад в исправление¶

Основы¶

Основной рабочий процесс для внесения кода обычно выглядит следующим образом:

1. Форк репозитория django CMS project GitHub на собственную учетную запись GitHub

2. Клонируйте свой форк локально:

   git clone git@github.com:YOUR_USERNAME/django-cms.git
   

3. Создайте виртуальную среду:

   virtualenv cms-develop
   source cms-develop/bin/activate
   

4. Установите его зависимости:

   cd django-cms
   pip install -r test_requirements/django-X.Y.txt
   

   Замените X.Y на ту версию Django, с которой вы хотите работать.

5. Создайте новую ветку для вашей работы:

   git checkout -b my_fix
   

6. Отредактируйте кодовую базу django CMS для реализации исправления или функции.

7. Запустите набор тестов:

   python manage.py test
   

8. Зафиксируйте и продвиньте свой код:

   git commit
   git push origin my_fix
   

9. Откройте запрос на выделение средств на GitHub.

Как написать тест¶

Набор тестов django CMS содержит смесь модульных тестов, функциональных тестов, тестов регрессии и интеграционных тестов.

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

Давайте начнем с чего-то простого. Будем считать, что вы правильно настроили свое окружение described above.

Допустим, вы хотите проверить поведение метода CMSPluginBase.render:

class CMSPluginBase(admin.ModelAdmin, metaclass=CMSPluginBaseMetaclass):

    ...

    def render(self, context, instance, placeholder):
        context['instance'] = instance
        context['placeholder'] = placeholder
        return context

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

Мы начнем с нового класса в существующем тестовом модуле django CMS (cms.tests.plugins в данном случае):

class SimplePluginTestCase(CMSTestCase):
    pass

Давайте попробуем запустить его:

python manage.py test cms.tests.test_plugins.SimplePluginTestCase

Это вызовет только новый класс тестового примера, что удобно при создании новых тестов и быстрой итерации по шагам. Перед открытием запроса на исправление необходимо выполнить полный тест (python manage.py test).

Вот какой результат вы получите:

Creating test database for alias 'default'...

----------------------------------------------------------------------
Ran 0 tests in 0.000s

OK

Это правильно, поскольку в нашем тестовом примере нет теста. Давайте добавим пустой:

class SimplePluginTestCase(CMSTestCase):

    def test_render_method(self):
        pass

Повторное выполнение команды проверки даст немного другой результат:

Creating test database for alias 'default'...
.
----------------------------------------------------------------------
Ran 1 test in 0.001s

OK

Это выглядит лучше, но это не так значимо, поскольку мы ничего не тестируем.

Напишите настоящий тест:

class SimplePluginTestCase(CMSTestCase):

    def test_render_method(self):
        """
        Tests the CMSPluginBase.render method by checking that the appropriate variables
        are set in the returned context
        """
        from cms.api import create_page
        my_page = create_page('home', language='en', template='col_two.html')
        placeholder = my_page.placeholders.get(slot='col_left')
        context = self.get_context('/', page=my_page)
        plugin = CMSPluginBase()

        new_context = plugin.render(context, None, placeholder)
        self.assertTrue('placeholder' in new_context)
        self.assertEqual(placeholder, context['placeholder'])
        self.assertTrue('instance' in new_context)
        self.assertIsNone(new_context['instance'])

и запустите его:

Creating test database for alias 'default'...
.
----------------------------------------------------------------------
Ran 1 test in 0.044s

OK

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

Давайте быстро проверим тестовый код.

Для тестирования метода CMSPluginBase.render нам понадобится экземпляр RequestContext и заполнитель. Поскольку CMSPluginBase не имеет configuration model, аргументом экземпляра может быть None.

1. Создайте экземпляр страницы для получения заполнителя

2. Получите местодержатель, отфильтровав местодержатели экземпляра страницы по ожидаемому имени местодержателя

3. Создайте экземпляр контекста, используя предоставленный метод суперкласса

4. Вызов метода render на экземпляре CMSPluginBase; будучи без статического состояния, легко вызвать render на голом экземпляре класса CMSPluginBase, что помогает в тестах

5. Утверждение нескольких вещей, которые метод должен обеспечить для возвращаемого экземпляра контекста

Как видите, даже такой простой тест предполагает и использует многие возможности тестовых утилит, предоставляемых django CMS. Прежде чем пытаться написать тест, потратьте время на изучение содержимого пакета cms.test_utils и проверьте поставляемые шаблоны, примеры приложений и, самое главное, базу testcases, определенную в cms.test_utils.testscases, которая предоставляет множество полезных методов для подготовки среды для наших тестов или для создания полезных тестовых данных.

Представление вашего кода¶

После того, как код и тесты готовы и упакованы в коммиты, вы должны отправить их на проверку и слияние в проекте django CMS на GitHub.

Как отмечалось выше, всегда создавайте новую ветку для вашего кода, будь то исправление или новая функция, перед фиксацией изменений, затем создайте запрос на вытягивание из вашей ветки в target branch на django CMS.