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

[Discourse]

Обзор

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

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