Ниже приведены некоторые подробности и причины, по которым была изменена инфраструктура, а также краткое описание преимуществ TYPO3.

История

До изменения docs.typo3.org фактически была системой разработки для группы документации. Это никогда не предназначалось, чтобы быть производственной средой. Система была загромождена множеством различных сценариев и решений разными членами команды, накопленными за эти годы.

Некоторые могут принять эту ситуацию и думать о технических сложностях. Существующая инфраструктура помешала нам изменить некоторые части docs.typo3.org. Например, многие запросы 404 Not Found были сгенерированы после перемещения руководств и разделов. Пользователи справки ViewHelper видели это, особенно в декабре 2018 года и январе 2019 года. Эти проблемы было практически невозможно решить для нас как команды из-за устаревшей системы.

Система также помешала нам использовать Docker. Прямо сейчас мы предоставляем Docker Container для рендеринга. Этот контейнер не может быть использован на производстве из-за старой системы.

Была необходимость перемен.

Требования

Группа по документации (Мартин Блесс и Даниэль Сипманн) направились в штаб-квартиру TYPO3 Inc. и встретились с Матиасом Шрайбером и Кристианом Куном. Мы сидели вместе целый день и обсуждали будущее docs.typo3.org. В ходе этой встречи были определены требования, и были высказаны некоторые идеи о том, как выполнить эти требования. Требования были:

Поддержка Composer

TYPO3 как проект хочет улучшить поддержку Composer в сторонних расширениях. Для решения этой проблемы требуется, чтобы каждый проект (руководства и расширения) немедленно предоставил действительный файл composer.json для визуализации.

Масштабируемость

docs.typo3.org нужно масштабировать. Этот пункт состоит из нескольких самодостаточных требований. Команда документации состоит из трех человек, у которых уже есть много работы. Для масштабирования некоторые повторяющиеся процедуры должны быть автоматическими или легко решаемыми:

1. Упростите автоматическую визуализацию документации.

Теперь каждый может включить хук в свой репозиторий GitHub, GitLab и Bitbucket. Также поддерживаются "пользовательские" хостеры. Каждое нажатие может вызвать рендеринг через web hook. Если у вас возникнут какие-либо проблемы, сообщите об этом в отдел документации.

2. Разрешить предварительный просмотр предоставленной документации перед выпуском.

Некоторые авторы расширений уже знают эту боль. Выпущена новая версия, и внутри документации есть проблема. Теперь авторы могут визуализировать документацию заранее, используя Docker Container.

Теперь они также могут вносить изменения в черновой вариант документа для создания неиндексированного предварительного просмотра документации.

3. Разрешить управление перекрестными ссылками. Теперь можно добавлять перенаправления для целых руководств и отдельных URL-адресов через веб-интерфейс.

Также можно переписать больше, настроив веб-сервер nginx.

Почему нам нужно беспокоиться о масштабе? TYPO3 планирует расширение в других странах, где больше людей будут читать и вносить свой вклад в docs.typo3.org. Также могут быть разработаны дополнительные расширения, требующие дополнительной поддержки их документации.

Самодокументированная среда

Теперь у нас есть самодокументированная среда. Это делается с помощью  Bamboo и Intercept. Bamboo содержит CI и определяет способ визуализации документации. Люди могут заглянуть в скрипт bash и точно знать, что происходит.

Intercept, промежуточное программное обеспечение, разработанное TYPO3 Inc., также обеспечивает связь между всеми системами. Весь исходный код открыт. Каждый может смотреть и делать пулл-запросы.

На сервере больше нет скрытого исходного кода или нестандартных заданий cron, скрывающих знания от сообщества.

Многоязычная поддержка

Перевод руководств уже был поддержан, но редко работал. Это теперь решено с чистой новой структурой URL. Авторы могут предоставить конкретный язык по локали, например, en-US или de-AT, в своей документации.

Сделать добавления проще

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

Знание содержания docs.typo3.org

Это делается Intercept. Будучи единственной точкой истины, Intercept знает о каждом отдельном запросе на предоставление документации. Также все результаты Bamboo возвращаются в Intercept. Таким образом, Intercept может знать содержание docs.typo3.org. Группа документации может удалять и повторно отображать любую доступную документацию через простой веб-интерфейс.

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

Поддержка Surf и Fluid Документация

TYPO3 предоставляет не только CMS и сторонние расширения, но также Surf в качестве решения для развертывания и Fluid в качестве механизма шаблонов. Оба продукта нуждаются в месте для предоставления собственной документации.

Теперь это выполняется с помощью тех же самых рабочих процессов, за исключением того, что у них есть собственный план сборки в Bamboo. Использование этой системы Surf и Fluid ViewHelper Ссылки уже предоставлены.

Работа

Оказывается, у нас было много требований, которые требовали много времени для решения. К счастью, TYPO3 Inc. смогла подключиться и приложила необходимые усилия. Они объединили имеющиеся знания команды документации с существующими системами TYPO3. TYPO3 Inc. передала систему группе документации, и она полностью контролирует ее.

Результат

Теперь у нас есть современная инфраструктура. Каждый автор может добавить Webhook в свой репозиторий, чтобы запустить рендеринг своей документации. Отображаются только теги версий в виде Major.Minor.Patch, а также основной ветвь и черновой вариант ветки.

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

Новый docs.typo3.org также предоставляет новую каноническую маршрутизацию в форме / type / vendor / name / version / locale, например, /p/typo3/form/9.5/en-US.

ПРИМЕЧАНИЕ. Нет доступных версий уровня патча.

Призыв к действию

Чтобы разрешить рендеринг для вашего расширения, добавьте в ваш проект действительный файл composer.json. Это должно обеспечить зависимость от typo3/cms-core с поддерживаемыми версиями. Добавьте новый webhook в ваш репозиторий (удалите старый, если он существует).

Команда документации также приветствует помощь всего сообщества TYPO3. Вы можете помочь улучшить нашу документацию, редактируя и корректируя существующие документы. Проверьте предыдущее сообщение относительно помощи.

 Копирование и корректура: Тони Луш