Стаття

Новини та Корисні статті

Наші послуги


Oops, an error occurred! Code: 2020112802524809b53e47

docs.typo3.org отримує нову інфраструктуру

Logo

docs.typo3.org тепер розміщується на TYPO3 Inc. і отримує сучасну настройку, яка використовує рішення Bamboo as CI (Continuous Integration) для рендеринга.

Нижче наведені деякі подробиці і причини, за якими була змінена інфраструктура, а також короткий опис переваг 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. Ви можете допомогти поліпшити нашу документацію, редагуючи і коригуючи існуючі документи. Перевірте попереднє повідомлення щодо допомоги.

Переклад та коректура: Тоні Луш

ЛогоНазваТипДемоПосилання
image
image