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

:mag: Обзор

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

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

:gear: Настройка

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

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

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

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

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

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

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

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

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

GitHub Actions покажет разбор каждого теста, а после выполнения укажет :white_check_mark: или :x: в зависимости от того, прошёл тест или нет.

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

Смотреть пример

:white_check_mark: Добавьте свои тесты

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

Подробнее о том, как писать фронтенд-тесты с использованием EmberJS, см.:

Подробнее о написании тестов RSpec с использованием Rails см.:

:bulb: Примеры

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


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

15 лайков

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

4 лайка

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

2 лайка

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

4 лайка

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

3 лайка

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

1 лайк

Рабочий процесс шаблона плагина использует следующее, что, как я думаю, будет тестировать по умолчанию ветку, то есть 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 }}
3 лайка

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

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, чтобы «заморозить» их при каждом стабильном релизе. Тогда нам не нужно беспокоиться о совместимости со стабильной версией во время их разработки.

5 лайков

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

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

2 лайка