Frontend «Платформа». Основа. Часть #2.

Как уже написано в первой части, «Платформа» должна охватывает полный цикл разработки от инфраструктуры, до архитектуры, но чтобы начать, нужно сделать для этого… платформу 💁🏻‍♂️

Чтобы написать «Платформу», вам нужна платформа

Так что же выбрать для основы? Готовые решения? Написать самому? Ничего из вышеперечисленного!

«Основой» должны стать ваши коллеги!

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

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

Если перевести это в пунктики, то получится так:

  • Всегда держите в курсе ваших планов
  • Работайте для коллег, а не для «себя»
  • Создайте чат/канал/рассылку, проводите митапы
  • Поддерживайте постоянную обратную связь
  • Корректируйте планы в соответствии с реальной «болью»
  • Меньше документации, больше инструментов

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

В документации же мы пишем, какую CLI-команду нужно запустить и уже команда, должна сделать всё возможное и если ей что-то не хватает, запросить это, либо на худой конец дать ссылку на документацию, но это крайний случай (об это я ещё напишу).

Пример README.md

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

Фундамент

Надо понимать, что фундамент или его элементы (в том или ином виде) уже были у нас (думаю и у вас они есть). Это были как готовые пакеты/репозитории, так и разного рода инструкции, осталось только всё это собрать вместе, критически взглянуть и доработать.

Но, чтобы максимально быстро начать и принести профит, мы сузили список базы до трех пакетов/направлений, который должен был помочь как в написании самой «Платформы», так и реальным проектов, которые уже были или только создавались, и этим основание стали:

  • cli — инструментарий для написания Command Line Interface скриптов/инструментов
  • git — работа с git и его хуками
  • lint — разнообразные линтеры

Вроде ничего необычного в этом списке нет, но лично я встречал только общие линтеры. Обычно это репозиторий с конфигами для ESLint, Prettier и т.п. (у нас как раз такой и был), всё остального либо нет вообще (например для работы CLI), либо распространяется копипастом/пишется на коленке (работа с git хуками)

@mail-core/lint

Как я уже написал выше, у нас уже был общий пакет для работы с линтерами, назывался он тогда просто dev-configs, он был настроен для работы с TS и React, а интегрировался он через sharec, т.е. это был банальный копипаст конфигов в проект.

На самом деле так делают все (обратного не видел), в том или ином виде и вроде норм способ… только если в проекте уже нет линтеров и вот на этом шаге, обычно коллеги вас проклинают, что вы приехали со своими правилами, либо просто шлют куда подальше.

И в обоих случаях они правы, у них всё работало, пока вы не пришли со своими конфигами, ломая привычный code style, заставляя пофиксить проект под ваше виденье «прекрасного».

Поэтому lint и все остальные пакеты Платформы не должны пытаться нагнуть «ваш» проект, а интегрироваться в него, притом любая интеграция должна осуществляться (по возможности) одной командой (не считая установки пакета конечно ;])

В итоге lint имеет команду “sync”, для синхронизации «Платформы» и «Проекта» и делает он это честно, берёт конфиг проекта и рассчитывает diff между ним и платформой, если правила различаются (добавлены, удалены или изменены), то переходит в интерактивный режим и спрашивает разработчика согласен ли он с этими изменениями.

Выглядит это следующим образом:

Merge EditorConfig, Prettier & etc

Не буду утверждать, что работает идеально, но это позволило достаточно безболезненно внедрять новые правила линтера не «ломая» проект.

После синхронизации, будет предложено настроить и установить git-хук на pre-commit.

@mail-core/git

Это наверно самый маленький пакет в платформе, он отвечает за базовые операции с git и по факту просто реекспортирует git-rev-sync, а для управления git-hooks устанавливает husky.

Но, есть и наш «код», а именно cli-команды для:

  • sync — синхронизация универсального .gitignore
  • install-hooks — установка базовых git-hooks
  • hook — интерактивное добавление команды на git-hook (npm или произвольной)
  • commit — интерактивный конструктор коммита

Казалось бы мелочи, но из них складывается проект, например мы используем Jira и чтобы таску связать с git-веткой мы использует два основных правила:

  1. Название ветки должно содержать ID таска, т.е. mail-XXXX или mail-XXXX-feature-name
  2. Сообщение коммита должно начинаться так же с ID таска: MAIL-XXXX: Запуск CallUI v2

Такие нехитрые правила дают нам возможность связывать автоматически

Как можно заметить, имя ветки приходится писать два раза, притом в первом случае lower-case, во втором UPPER-CASE, хотя логично просто брать это из имени ветки.

И вот чтобы не забывать эти нехитрые правила, кто-то сам пишет себе такой хук, а где-то он был на уровне проекта. Это было не системно, без тестов и поэтому не всегда даже корректно отрабатывало (например когда создавали дубль-ветку с потфиксом mail-XXXXa).

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

Поэтому собрали хотелки и кейсы, как должен работать такой хук, написали тесты и добавили поддержку альтернативного варианта, а именно Conventional, опять же с тестами и авто подстановкой имени ветки.

Установка хука на проверку формата комита

@mail-core/cli

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

Но об этом я расскажу в следующей части, т.к. @mail-core/cli достоин отдельного разговора.

PS Всё, это больше не будет введение, дальше будет именно разбор, как всем этим пользоваться и что-то уже начну выкладывать в OpenSource.

Frontend originator | https://rubaxa.github.io | https://t.me/artifact_project