Весь фронтэнд Дискурса в одном репозитории!

Дискурс (Пока что на старом проекте) | Бэта Дискурс (собирается из develop) | Сторибук Дискурса

• Cheat Sheet
• Манифест разработки Дискурса
• Storybook
• Тестирование
• Поддержка браузеров
• npm run commit
• Git flow
• Зависимости

Cheat Sheet

Быстрый справочник по разработке проекта

• Проект должен запускаться в IE9 и выше, но заботимся о поддержке Edge и выше. О поддержке браузеров.
• npm run commit вместо git commit (Выводит интерактивный промпт для коммита). Подробнее.
• PR в ветку develop из веток feature/#id или bugfix/#id. Подробнее.
• storybook для верстки компонентов и страниц очень помогает. А что у вас там есть?
• react-testing-library для интеграционного тестирования компонентов (если там есть какая-то логика) для полной уверенности в своём коде. Про тестирование.
• Стили пишем в .css файлах, но активно используем переменные из стандарта css-custom-properties и css-custom-media. О вёрстке.
• UI Kit компоненты в src/components/discours-ui-kit, вёрстка — в src/components/modules, логика — в src/layouts и в src/pages. О структуре проекта.
• Свойства .css идеоматически сортируются перед коммитом. Зачем?
• Всё, что нужно для сборки приложения, устанавливается в production dependencies. Но не красиво же!

Оригинал

Манифест разработки Дискурса

1. Дискурс — открытый проект. Каждый желающий имеет право стать контрибьютором проекта, внести изменения в любой из сервисов проекта и отправить Pull Request.
2. Дискурс — общий проект. Вы всегда можете пообщаться с другими членами команды в Gitter чате Дискурса. Там Вы можете узнать, что сейчас лучше сделать, а также задать любой вопрос по поводу разработки проекта.
3. Дискурс — проект для читателя. В первую очередь команда выполняет те таски, за которые проголосовали пользователи на публичной доске задач проекта.
4. Дискурс — проект для любого разработчика. Мы принимаем микросервисы для backend на любом языке программирования. Но стоит понимать, что мэйнтейнеры проекта не могут знать всех языков, поэтому Dockerfile для запуска микросервиса, понятная документация и тесты (с настроенным CI для их прогона) обязательны в каждом микросервисе.
5. Дискурс — проект для приятной разработки. Команда следит за качеством кода в проекте для того, чтобы новым контрибьюторам было максимально просто влиться в проект. Качество кода - это не только code style и тесты, но и такие субъективные показатели, как читаемость кода и архитектура. Мэйнтейнеры проекта имеют право попросить автора PR изменить код в целях повышения его качества.
6. Дискурс — проект для удобной разработки новых features. Команда Дискурса стремится создать проект, в котором не надо читать весь код для реализации конкретной функциональности. Мы стремимся создать максимально изолированную среду разработки, используя которую каждая фича разрабатывается отдельно. На frontend проектах мы используем storybook для разработки компонентов и react-testing-library для интеграционного тестирования функциональности компонентов. На backend проектах — разрабатываем используя тесты.
7. Дискурс — проект с открытым манифестом разработки. Каждый желающий может прислать изменения в данный манифест.
8. Дискурс — проект доступный. Верстка в проекте должна учитывать пользователей с ограниченными возможностями, то есть необходимо использовать ARIA аттрибуты. В storybooks всех фронтэнд проектов установлен плагин @storybook/addon-a11y, который показывает недостающие ARIA аттрибуты.
9. Дискурс — проект без гос. цензуры. Но большая часть наших читателей из РФ, где РосКомНадзор частенько бомбит славный город Воронеж и даже иногда блокирует сам себя. Инфраструктура проекта должна быть распределенной, но должна поддерживать быструю смену IP адресов всего, до чего необходимо достучаться пользователю (фронтэнд, бэкэнд, rss микросервис, другие микросервисы доступные пользователю). Нельзя создавать vendor lock на решения, которые не позволяют быстро сменить IP (Cloudflare, Netlify).

Storybook

npm run storybook для запуска или посмотреть он-лайн

Основной инструмент разработки компонентов в этом проекте — Storybook. С помощью сторибука мы можем разрабатывать компоненты по отдельности, не думая как и откуда нам должны приходить данные.

Tutorial по сторибукам, если вы никогда не работали с этим инструментом.

В сторибуке мы можем видеть наш компонент во всех возможных вариантах отображения. Например, если у нас есть кнопка с тремя стилями, можно создать три сторибука под каждый конкретный стиль.

В наших сторибуках есть несколько весьма полезных инструментов:

• Информация о компоненте. У многих компонентов (особенно в discours-ui-kit) есть файл README.md с описанием функциональности и дизайна компонента. В таком случае, оно отображается, если нажать на кнопку Show info в правом верхнем углу сторибука.

• Выбор тем. Каждый компонент можно посмотреть в разных темах. При разработке компонента, нам надо быть уверенным в том, что он смотрится хорошо во всех темах.

• Предпросмотр в размер мобильного экрана. Не лучше родного функционала, что есть в Developer Tools любого браузера, но быстрее и удобно вызываются.

Тестирование

Функциональный код

Тут всё весьма стандартно: jest в качестве test runner. В проекте установлен jest-extended, но импортировать его надо в каждый тест отдельно для исключения сайд эффектов.

Компоненты и контейнеры

Для интеграционного тестирования компонентов используется react-testing-library + jest-dom для дополнительных мэтчеров в тестах.

Писать тесты ко всем компонентам не надо - мы не стремимся к 100% покрытию. В компонентах можно затестить правильную передачу классов и пропов.

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

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

Если тестируется HOC и эл-тов интерфейса нет, можно написать в тесте специальный компонент, который будет вызывать функции HOC'а по нажатию на кнопки.

E2E

Используется Cypress и тестируется сайт с точки зрения не залогиненного посетителя.

Поддержка браузеров

Статистика Дискурса взята за январь-июль 2019

• Edge 0.96%
• IE 0.73%
  • IE11 0.67%
  • IE8 0.04%
  • IE10 0.0074%
  • IE9 0.002%
  • IE7 0.001%
  • IE6 0.0007%

Следим за правильным отображением и работой мы в браузере Edge и выше. То есть в Edge должен работать весь функционал сайта и отображаться он должен правильно.

npm run commit

В проекте есть специальный commit prompt, который помогает отформатировать commit message в соответствии с Conventional Commits. Для его запуска необходимо выполнить npm run commit. Он спросит про тип коммита, scope (не обязательно), описание коммита (мы используем present simple в описании, напр. "Create the Button component"), а в конце попробует достать номер issue на GitHub из имени ветки автоматически и добавить его в commit message в следующем формате: [#10]. Таким образом создастся ссылка из коммита на issue.

Что такое scope? Это объект изменения кода. Если мы пишем commit message без scope, мы часто пишем .. in something в конце. Вот этот something и есть scope, который выносится в начало коммит сообщения. То есть Add onPress event handler in Button component превратится в feat(Button component): ✨ Add onPress event handler. scope не обязательный, но желательный параметр.

Использования скрипта npm run commit необязательно, но тогда надо писать коммит сообщение в соответствии с Conventional Commits самому (эмодзи не обязательны).

Git flow

Для работы в репозитории мы используем Git flow.

• master — текущая production версия
• develop — текущая beta версия

Перед началом работы нужно создать новую ветку из develop:

• feature/#10 — новый функционал, описанный в GitHub Issue #10
• bugfix/#10 — баг фикс, описанный в GitHub Issue #10

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

Зависимости

Все зависимости, что необходимы для сборки проекта (webpack, typescript, postcss) стоят в production dependencies, что выглядит весьма нестандартно и режет глаз. Дело в том, что мы хотим более быструю сборку на CD (Netlify), поэтому не хотим там ставить зависимости, нужные только для development (jest, tslint и особенно cypress, который долго скачивается). И для этого есть стандартный механизм в npm - production зависимости! Но в таком случае, всё, что надо для сборки должно быть там.

Так же мы стараемся следить за размером бандла и не ставить зависимости на каждых чих. Быстрая загрузка сайта и его работа — основной наш приоритет! В любом деплое этого сайта (production, staging, PR review), можно добавить /report.html в адрес и увидеть отчёт по размеру бандла от webpack-bundle-analyzer.