Перевести tlroadmap в честный веб

[b0g3r]

tlroadmap -> https://tlroadmap.io

Кажется, пришло время оформить наполовину сделаную работу в виде полноценного ишью.

Зачем tlroadmap уезжать в веб?

tlroadmap из небольшого .mm файла и набора статей превратился в базу знаний, которая усложнялась и будет постепенно усложняться дальше: генерация артефактов, проверки, шаблонные файлы, перекрёстные связи, переводы, глоссарий, ...

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

Какое решение?

Сейчас источником истины для дерева компетенций служит .puml файл с ссылками на .mm файлы, которые лежат в достаточно плоской структуре директорий. Из этого .puml-файла генерируются связанные артефакты: .png, .svg, .mm, часть .md и кладутся в репозиторий.

Что я предлагаю:

• Источником истины считать структуру папок и .md файлы в ней.
• Мета-информацию (тайтл, теги, цвет ветки, расположение ветки, ...) хранить в .md файлах в frontmatter-формате или любом другом
• Чтобы поддерживать i18n каждая ветка содержит ru.md, en.md, %anylocale%.md файл
• Утилита при сборке извлекает дерево и нужные мета-данные из файлов и структуре папок и кладёт его в какой-нибудь структурированный формат (json, yaml)
• Утилита генерирует артефакты дерева (картинки, .mm файлы, т.д.)
• Утилита генерирует статический сайт

Например из такой структуры файлов:

Должен генерироваться сайт с такой структурой:

Что нужно предусмотреть:

• Минимальную боль для писателя (контрибьютора) — в идеальном случае единственное, с чем он должен работать — это с редактором .md файла.
• Генерация должна быть лёгковесной и быстрой: чтобы иметь возможность разворачивать тестовые окружения под каждое изменение
• Генератор статического сайта должен быть достаточно мощным и расширяемым, чтобы иметь возможность быстро добавлять интерактивные компоненты
• Сгенерированный статический сайт должен иметь удобную мобильную версию, быть быстрым (PageSpeed > 65), поддерживать кеширование
• Сгенерированный статический сайт должен быть SEO-friendly: иметь статичную meta-информацию, возможность настроить её для каждой страницы
• Сайт должен трекать перемещение пользователя по страницам, строить статистику
• Возможность интеграции с сервисами по менеджементу переводов (crowdin, gitlocalize)

Какие технические детали?

Я и @teners реализовали большую часть из озвученных выше штук, использовав следующую магию:

• Мы распихали весь текущий родмап по вложенным папкам и назвали их ru.md
• В "ветки", у которых нет описания мы добавили мета-информацию с переводом заголовка
• Мы сгенерировали из этой структуры статический сайт на VuePress
• Мы сгенерировали из этой структуры .json дерево специальным vuepress-плагином
• Мы добились красивых URL-ов другим специальным vuepress-плагином
• Мы вывели всю генерацию артефактов в Github Actions, и прикрутили автодеплой в netlify с ревью-окружениями для каждого PR

Есть и подводные камни:

• Репозиторий tlroadmap — база знаний, а не ПО. Лицензия CC-BY-SA 4.0 плохо подходит для свободного ПО, и с этим есть очевидные проблемы. Весь код мы максимально вынесли за пределы репозитория под MIT-лицензиями, и это нужно будет продолжать делать.
• Мы взяли VuePress в качестве генератора и сейчас достаточно сильно от него зависим, написали специальные плагины, подкрутили всё что можно подкрутить и будем продолжать подкручивать. Весь интерактив, кастомные компоненты, SEO-магия и другие штуки часто будут зависеть от Vue как фреймворка. Впрочем, такую структуру файлов легко съест любой другой генератор статических файлов (Hugo, Jekyll, Gatsby), поэтому переезд возможен в любой момент.

Что теперь?

Когда все из обязательных условий будут выполнены форк b0g3r/tlroadmap будет влит в tlbootcamp/tlroadmap, и структура файлов в репозитории изменится.

Скорее всего вместе с этим сломаются все текущие PR :(

Чтобы отслеживать будущие ишью по сайту предлагаю создать лейбл website, и перенести оставшиеся в форке ишью в апстрим.

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

[b0g3r]

В идеале эти требования выше и сам сайт отдать на растерзание и поиск ошибок в комьюнити, многое мы наверняка не учли

[etolstoy]

@b0g3r кажется, можем закрывать уже?

[b0g3r]

Я бы как эпик оставил