Разработка

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

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

Вы также можете настроить облачную среду разработки, с которой можно работать в браузерном IDE, используя проект gitpod-wagtail-develop.

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

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

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

Лучший способ установить правильную версию Node – использовать Node Version Manager (nvm) или Fast Node Manager (fnm), что всегда будет согласовывать версию с предоставленным файлом .nvmrc в корне проекта. Чтобы убедиться, что вы используете правильную версию Node, выполните nvm install или fnm install из корня проекта. В качестве альтернативы, вы можете установить Node.js напрямую, убедившись, что вы установили версию, указанную в файле .nvmrc проекта в корне.

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

Скопируйте репозиторий Wagtail:

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

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

pip install -e '.[testing,docs]' -U

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

npm ci

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

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
# In a separate terminal:
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 Phone	Последние 2
Mobile Safari	iOS Tablet	Последние 2
Chrome	Android	Последние 2
Chrome	Desktop	Последние 2
MS Edge	Windows	Последние 2
Firefox	Desktop	Последняя
Firefox ESR	Desktop	Последняя
Safari	macOS	Последние 3

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

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

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

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

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

Цели по обеспечению доступности

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

NVDA в Windows с Firefox ESR
VoiceOver в macOS с Safari
Magnifier Windows и Zoom macOS
Распознавание речи Windows и Dictation 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 должен запускаться при каждом вашем коммите.