Разработка

Настройка локальной копии репозитория Wagtail с GitHub немного сложнее, чем использование готового релиза Wagtail, так как требуется Node.js и NPM для сборки JavaScript и CSS-активов. (При использовании релиза это не нужно, так как скомпилированные активы включены в пакет релиза.)

Если вы предпочитаете работать на виртуальной машине, скрипты vagrant-wagtail-develop и docker-wagtail-develop — самый быстрый способ начать работу. Они предоставят вам запущенный экземпляр демонстрационного сайта Wagtail Bakery с кодовыми базами Wagtail и bakerydemo, доступными в качестве общих папок для редактирования на вашем хост-компьютере.

(Скрипты сборки для других платформ будут очень полезны — если вы создадите такой, сообщите нам, пожалуйста, в рабочем пространстве Slack!)

Если вы предпочитаете настроить все компоненты вручную, читайте дальше. Эти инструкции предполагают, что вы знакомы с использованием pip и virtualenv для управления пакетами Python.

Настройка кодовой базы Wagtail

Предпочтительный вариант — установить правильную версию Node с помощью Node Version Manager (nvm), которая всегда будет соответствовать версии, указанной в файле .nvmrc в корне проекта. См. инструкции по установке nvm. В качестве альтернативы, вы можете установить Node.js напрямую, убедившись, что вы устанавливаете версию, указанную в корневом файле проекта .nvmrc.

Вам также потребуется установить библиотеки libjpeg и zlib, если вы этого еще не сделали — см. платформенно-специфические инструкции по установке для Pillow.

Создайте копию кодовой базы Wagtail:

$ git clone https://github.com/wagtail/wagtail.git
$ cd wagtail

При активированной вашей виртуальной среде virtualenv установите пакет Wagtail в режиме разработки с включенными зависимостями для тестирования и документации:

$ pip install -e .[testing,docs] -U
$ # or if using zsh as your shell:
$ #    pip install -e '.[testing,docs]' -U

Установите Node через nvm (необязательно):

$ nvm install

Установите инструмент для сборки статических активов:

$ npm install --no-save

Скомпилируйте активы:

$ npm run build

Любые сайты Wagtail, которые вы запустите в этой виртуальной среде, теперь будут работать с этим экземпляром разработки Wagtail. Мы рекомендуем использовать демонстрационный сайт Wagtail Bakery в качестве основы для разработки Wagtail. Имейте в виду, что шаги настройки сайта Wagtail могут включать установку релиза Wagtail, который перепишет установленный вами режим разработки. В этом случае вы должны установить сайт перед выполнением шага pip install -e, или выполнить этот шаг повторно после установки сайта.

Тестирование

Из корневой директории кодовой базы Wagtail запустите следующую команду для выполнения всех тестов Python:

$ python runtests.py

Запуск только некоторых тестов

На момент написания у Wagtail более 2500 тестов, которые занимают много времени при запуске. Вы можете запустить тесты только для одной части Wagtail, передав путь в качестве аргумента к runtests.py или tox.

$ # Running in the current environment
$ python runtests.py wagtail

$ # Running in a specified Tox environment
$ tox -e py39-dj32-sqlite-noelasticsearch wagtail

$ # See a list of available Tox environments
$ tox -l

Вы также можете запустить тесты для отдельных TestCases, передав путь в качестве аргумента к runtests.py.

$ # Running in the current environment
$ python runtests.py wagtail.tests.test_blocks.TestIntegerBlock

$ # Running in a specified Tox environment
$ tox -e py39-dj32-sqlite-noelasticsearch wagtail.tests.test_blocks.TestIntegerBlock

Запуск миграций для моделей приложения тестов

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

$ django-admin makemigrations --settings=wagtail.test.settings

Тестирование против PostgreSQL

Примечание

Для запуска этих тестов необходимо установить необходимые модули для PostgreSQL, как описано в документации Django по базам данных.

По умолчанию Wagtail использует SQLite. Вы можете переключиться на PostgreSQL, используя аргумент --postgres.

$ python runtests.py --postgres

Если вам нужно использовать другого пользователя, пароль, хост или порт, используйте переменные среды PGUSER, PGPASSWORD, PGHOST и PGPORT соответственно.

Тестирование против другой базы данных

Примечание

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

Если вам нужно протестировать против другой базы данных, установите переменную среды DATABASE_ENGINE в имя бэкэнда базы данных Django, с которым необходимо протестировать:

$ DATABASE_ENGINE=django.db.backends.mysql python runtests.py

Это создаст новую базу данных под названием test_wagtail в MySQL и запустит тесты против неё.

Если вам нужны разные параметры подключения, используйте следующие переменные среды, которые соответствуют соответствующим ключам в словаре настроек базы данных Django DATABASES:

DATABASE_ENGINE
DATABASE_NAME
DATABASE_PASSWORD
DATABASE_HOST
- Обратите внимание, что для MySQL это должно быть 127.0.0.1, а не localhost, если вам нужно подключиться через TCP-сокет.
DATABASE_PORT

Также можно установить DATABASE_DRIVER, что соответствует значению driver в OPTIONS, если используется движок SQL Server.

Тестирование Elasticsearch

Вы можете протестировать Wagtail против Elasticsearch, передав аргумент --elasticsearch в runtests.py:

$ python runtests.py --elasticsearch

Wagtail попытается подключиться к локальной инстанции Elasticsearch (http://localhost:9200) и использовать индекс test_wagtail.

Если ваша инстанция Elasticsearch расположена где-то еще, вы можете установить переменную среды ELASTICSEARCH_URL для указания её местоположения:

$ ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py --elasticsearch

Единые тесты для JavaScript

Для модульного тестирования клиентской бизнес-логики или компонентов пользовательского интерфейса мы используем Jest. Из корневой директории кодовой базы Wagtail запустите следующую команду для запуска всех фронтенд-модульных тестов:

$ npm run test:unit

Интеграционные тесты

Наш набор тестов браузера также использует Jest в сочетании с Puppeteer. Мы настроили его для отдельной установки, чтобы не увеличивать размер установки существующих инструментов Node. Для запуска тестов вам необходимо установить зависимости и запустить сервер Django для разработки тестов:

$ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
$ # Assumes the current environment contains a valid installation of Wagtail for local development.
$ ./wagtail/test/manage.py migrate
$ ./wagtail/test/manage.py createcachetable
$ DJANGO_SUPERUSER_EMAIL=admin@example.com DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=changeme ./wagtail/test/manage.py createsuperuser --noinput
$ ./wagtail/test/manage.py runserver 0:8000
$ npm --prefix client/tests/integration install
$ npm run test:integration

Интеграционные тесты по умолчанию нацелены на http://localhost:8000. Используйте переменную среды TEST_ORIGIN для использования другого порта или тестирования удалённой инстанции Wagtail: TEST_ORIGIN=http://localhost:9000 npm run test:integration.

Поддержка браузеров и устройств

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

Браузер	Устройство/ОС	Версия(и)
Mobile Safari	iOS Телефон	Последние 2
Mobile Safari	iOS Планшет	Последние 2
Chrome	Android	Последние 2
Chrome	Рабочий стол	Последние 2
MS Edge	Windows	Последние 2
Firefox	Рабочий стол	Последняя
Firefox ESR	Рабочий стол	Последняя
Safari	macOS	Последние 3

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

Поддержка IE 11 была официально прекращена в версии 2.15, так как она постепенно выходит из употребления. К известным проблемам относятся:

Копирование и вставка форматированного текста в редакторе форматированного текста.
Прилипающая панель инструментов в редакторе форматированного текста.
Стиль контура фокуса в главном меню и меню проводника.
Доступ с клавиатуры к действиям в таблицах с перечислением страниц.

Неподдерживаемые браузеры / устройства включают:

Браузер	Устройство/ОС	Версия(и)
Стандартный браузер	Android	Все
IE	Рабочий стол	Все
Safari	Windows	Все

Цели доступности

Мы хотим сделать Wagtail доступным для пользователей широкого спектра вспомогательных технологий. Установленный стандарт - WCAG2.1, уровень AA. Вот конкретные вспомогательные технологии, которые мы нацелены протестировать и в конечном итоге поддерживать:

NVDA на Windows с Firefox ESR
VoiceOver на macOS с Safari
Масштабирование экрана Windows и macOS
Распознавание речи Windows и Диктовка macOS
Мобильный VoiceOver на iOS или TalkBack на Android
Windows Режим высокой контрастности

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

react-axe интегрирован непосредственно в наши инструменты сборки для выявления проблем, которые можно исправить. Результаты отображаются в консоли браузера.
@wordpress/jest-puppeteer-axe выполняет проверки Axe в рамках интеграционных тестов.
Axe расширение для Chrome для более всеобъемлющих автоматизированных тестов конкретной страницы.
Accessibility Insights for Web расширение для Chrome для полуавтоматических тестов и ручных проверок.

Известные проблемы с доступностью

В настоящее время администрирование Wagtail не полностью доступно. Мы активно работаем над устранением проблем, как в рамках текущего обслуживания, так и в рамках более крупных переработок. Чтобы узнать о известных проблемах, посетите:

Список задач WCAG2.1 AA для CMS администрирования.
Наш аудит доступности 2021 года.

В аудиторском отчете также указано, какие части Wagtail были и не были протестированы, как проблемы влияют на соответствие WCAG 2.1 и вероятное влияние на пользователей.

Компиляция статических ресурсов

Все статические ресурсы, такие как JavaScript, CSS, изображения и шрифты для администрирования Wagtail, компилируются из исходных файлов с помощью webpack. Скомпилированные ресурсы не коммитные в репозиторий и компилируются перед пакетированием каждого нового релиза. Скомпилированные ресурсы не должны отправляться в составе запроса на добавление изменений.

Для компиляции ресурсов выполните:

$ npm run build

Это необходимо делать после каждого изменения исходных файлов. Чтобы следить за изменениями в исходных файлах и автоматически перекомпилировать ресурсы, выполните:

$ npm start

Использование библиотеки шаблонов

Библиотека компонентов пользовательского интерфейса Wagtail создана с использованием Storybook и django-pattern-library. Для запуска локально:

$ export DJANGO_SETTINGS_MODULE=wagtail.test.settings_ui
$ # Assumes the current environment contains a valid installation of Wagtail for local development.
$ ./wagtail/test/manage.py migrate
$ ./wagtail/test/manage.py createcachetable
$ ./wagtail/test/manage.py runserver 0:8000
$ # In a separate terminal:
$ npm run storybook

Последняя команда запустит Storybook на http://localhost:6006/. По умолчанию она будет проксировать определённые запросы в Django на http://localhost:8000. Используйте переменную среды TEST_ORIGIN для использования другого порта для Django: TEST_ORIGIN=http://localhost:9000 npm run storybook.

Компиляция документации

Документация Wagtail создается с помощью Sphinx. Для установки Sphinx и компиляции документации выполните:

$ cd /path/to/wagtail
$ # Install the documentation dependencies
$ pip install -e .[docs]
$ # or if using zsh as your shell:
$ #    pip install -e '.[docs]' -U
$ # Compile the docs
$ cd docs/
$ make html

Скомпилированная документация теперь находится в docs/_build/html. Откройте эту директорию в веб-браузере, чтобы увидеть ее. Python поставляется с модулем, который значительно упрощает предварительный просмотр статических файлов в веб-браузере. Чтобы запустить этот простой сервер, выполните следующие команды:

$ cd docs/_build/html/
$ python -m http.server 8080

Теперь вы можете открыть <http://localhost:8080/> в вашем веб-браузере, чтобы увидеть скомпилированную документацию.

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

$ cd docs/
$ make clean
$ make html

Wagtail также предоставляет возможность автоматической компиляции документации при каждом изменении. Для этого вы можете выполнить следующую команду, чтобы увидеть изменения автоматически в localhost:4000:

$ cd docs/
$ make livehtml

Автоматическая проверка кода и форматирование при коммитах

pre-commit настроен на автоматическое выполнение проверок кода и форматирования при каждом коммите. Чтобы установить pre-commit в ваши git хуки, выполните:

$ pre-commit install

pre-commit теперь должен выполняться при каждом вашем коммите.