• en
  • Language: ru
  • 3.7.x
  • Documentation version: 3.9

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

Примечание

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

django CMS является открытым проектом и приветствует участие всех желающих, независимо от уровня их знаний.

Помимо кода, мы приветствуем вклад в django CMS documentation и translations.

Примечание

Не стесняйтесь погружаться в кодирование для django CMS тем способом, который вам подходит. Однако, вы должны знать guidelines и policies для разработки проекта django CMS. Придерживаясь их, разработчикам ядра будет гораздо легче подтвердить и принять ваш вклад.

Основы

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

  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.

Критерии приемлемости

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

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

Характеристики

Чтобы быть принятыми, предлагаемые функции должны иметь по крайней мере:

  • документация на естественном языке в папке docs, описывающая функцию, ее использование и потенциально обратные несовместимости.

  • встроенная документация (комментарии и docstrings) в критических областях кода, объясняющая поведение

  • соответствующее тестовое покрытие

  • Совместимость с Python 2/3

  • Миграции South и Django (где это применимо)

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

Жучки

Чтобы быть принятым, предлагаемые исправления ошибок должны иметь по крайней мере:

  • встроенная документация (комментарии и docstrings) в критических областях кода, объясняющая поведение

  • как минимум 1 регрессионный тест, демонстрирующий проблему и ее устранение

  • Совместимость с Python 2/3

  • Миграции South и Django (где это применимо)

Описание заявки должно кратко описывать ошибку и шаги по ее решению; в случае, если ошибка была открыта в другом месте, на нее должна быть ссылка в описании заявки с описанием исправления.