Настройка непрерывной интеграции с помощью GitHub Actions

[Discourse]

Обзор

Чтобы создать надёжное расширение для Discourse, имеет смысл включить непрерывную интеграцию (CI) в ваш плагин или компонент темы. Это поможет выявлять ошибки на ранней стадии и снизит вероятность появления ошибок в вашем коде.

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

Настройка

Чтобы добавить автоматизированные рабочие процессы для GitHub Actions, вам нужно создать папку .github/workflows в корневом каталоге вашего репозитория.

Внутри папки workflows вы можете определить набор автоматизаций, которые должны выполнять GitHub Actions. Например, это могут быть файлы .yml для линтинга и тестов.

Мы создали шаблоны рабочих процессов как для плагинов, так и для компонентов тем, которые вы можете использовать. Они связаны с нашими определениями «переиспользуемых рабочих процессов» здесь.

В репозитории-шаблоне на GitHub вы можете нажать кнопку Использовать этот шаблон, чтобы создать репозиторий плагина/компонента темы на основе шаблона.

В качестве альтернативы, если у вас уже есть проект, к которому вы хотите добавить рабочие процессы, просто скопируйте соответствующий рабочий процесс в папку .github/workflows/ вашего репозитория:

Плагины: discourse-plugin.yml

Темы и компоненты тем: discourse-theme.yml

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

Готово! Всё настроено! Просто создайте коммит или PR в вашем репозитории, и GitHub Actions автоматически обнаружит рабочие процессы и начнет выполнение задач.

GitHub Actions покажет подробную информацию о каждом тесте, а после выполнения укажет или в зависимости от того, пройден тест или нет.

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

См. пример

Добавьте свои собственные тесты

Чтобы тесты для плагинов и компонентов работали эффективно, важно, чтобы вы писали тесты для вашего плагина или компонента темы.

Подробнее о том, как писать тесты фронтенда с помощью EmberJS, см.:

• Write acceptance tests and component tests for Ember code in Discourse
• Introduction - Testing - Ember Guides

Для получения дополнительной информации о написании тестов RSpec с использованием Rails см.:

• RSpec - Behavior Driven Development for Ruby

Примеры

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

Плагин / Компонент	Тесты на стороне клиента	Тесты на стороне сервера
Assign	Посмотреть папку	Посмотреть папку
Calendar	Посмотреть папку	Посмотреть папку
Reactions	Посмотреть папку	Посмотреть папку
Right Sidebar Blocks	Посмотреть папку
Tag Icons	Посмотреть папку
Table Builder	Посмотреть папку

---

Этот документ управляется системой контроля версий — предложите изменения на github.

[pfaffman (Jay Pfaffman)]

Вы можете явно упомянуть GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes · GitHub и отметить, что стоит следить за ним, чтобы замечать изменения в этих файлах.

[Simon_Manning]

@Jay Pfaffman

Вам стоит посмотреть это, чтобы отметить изменения в этих файлах

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

[keegan (Keegan George)]

Спасибо @pfaffman и @Simon_Manning, хорошие замечания. Я обновил исходный пост соответствующим образом.

[david (David Taylor)]

Я обновил исходный пост, добавив инструкции по использованию наших новых «повторно используемых рабочих процессов». Небольшие изменения, которые мы вносим в определения рабочих процессов, теперь могут автоматически применяться к вашим темам и плагинам без необходимости ручной работы.

Мы создали шаблоны рабочих процессов как для плагинов, так и для компонентов тем, которые вы можете использовать. Они подключаются к нашим определениям «повторно используемых рабочих процессов» здесь.

…

Плагины: discourse-plugin.yml

Темы и компоненты тем: discourse-theme.yml

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

[merefield (Robert)]

Нужно ли мне предпринимать какие-то особые действия, чтобы плагин был протестирован как с последними успешно пройденными тестами, так и со стабильной версией?

[Simon_Manning]

Рабочий процесс шаблона плагина использует следующее, что, как я думаю, будет тестировать по умолчанию ветку, то есть main. Повторно используемый рабочий процесс имеет необязательный входной параметр core_ref, и насколько я могу судить, без него будет проверяться ветка по умолчанию репозитория discourse/discourse.

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

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

jobs:
  ci:
    strategy:
      matrix:
        target: [tests-passed, stable]
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: ${{ matrix.target }}

[david (David Taylor)]

Да, этого должно быть достаточно. Или вы можете просто вручную прописать две задачи, не используя матрицу:

name: Discourse Plugin

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  ci:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1

  ci-stable:
    uses: discourse/.github/.github/workflows/discourse-plugin.yml@v1
    with:
      core_ref: stable

Стоит отметить, что эти задачи не будут проверять файл .discourse-compatiblity. Поэтому это имеет смысл делать только для плагинов, которые не используют этот файл и должны одновременно быть совместимы как с main, так и с stable.

Для всех публичных тем и плагинов CDCK мы добавляем запись в discourse-compatibility, чтобы «заморозить» их при каждом стабильном релизе. Тогда нам не нужно беспокоиться о совместимости со стабильной версией во время их разработки.

[merefield (Robert)]

Спасибо вам обоим.

@david

Для всех публичных тем и плагинов CDCK мы добавляем запись в discourse-compatibility, чтобы «заморозить» их при каждом стабильном релизе.

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