Авторы: Ори Нойман, Лиат Гофштейн

Начнем с конца - как мы сюда попали?

Наша история началась, когда мы в Kenshoo разрабатывали компонент для отображения и управления иерархической структурой элементов - React Tree.

Этот компонент был разработан в нашем частном репозитории, но мы поняли, что он может стать отличным вкладом с открытым исходным кодом для сообщества.

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

Поэтому мы решили создать это руководство для вас!

Две публикации в этой серии блогов представляют собой практическое руководство по открытию исходного кода проекта GitHub, основанное на нашем опыте работы с React Tree.

Это руководство разработано специально для Node / JavaScript и предназначено для людей, знакомых с Yarn и npm.

В этой серии мы шаг за шагом рассмотрим процесс создания открытого исходного кода с пояснениями, примерами и соответствующими ссылками.

В этом посте, часть 1, мы рассмотрим следующие шаги:

  1. Создание проекта
  2. CI\CD

Часть 2 будет охватывать:

  1. Издательский
  2. Документация

Когда вы закончите читать эти сообщения, у вас тоже будет проект с открытым исходным кодом!

Предпосылки

Прежде чем погрузиться в создание проекта с открытым исходным кодом, убедитесь, что у вас установлены Node v10 + и Yarn, а также учетная запись npm.

А теперь приступим!

Шаг 1. Создание проекта

Начнем с создания репозитория. Здесь вы будете хранить свой код и позволять другим разработчикам вносить свой вклад и оставлять отзывы.

Мы используем GitHub в качестве системы управления версиями и рекомендуем вам сделать то же самое.

Начните с установки git отсюда. Затем создайте свой репозиторий в GitHub, нажав здесь (вам необходимо войти в GitHub, чтобы эта ссылка работала), или нажав Создать + ›Новый репозиторий.

Не снимайте флажок Общедоступный, чтобы все в Интернете могли видеть ваше хранилище:

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

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

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

Теперь, когда у вас есть репозиторий, вы готовы создать свой первый коммит! В этом коммите вы будете определять структуру своего проекта.

Структура проекта

Мы рекомендуем создавать свой проект как монорепозиторий - единый репозиторий, в котором хранится множество пакетов.

Почему?

  • Возможность добавления дополнительных пакетов в ваш репозиторий в будущем всегда будет доступна.
  • Это упрощает управление версиями. Вы можете решить, хотите ли вы иметь одну версию для всех пакетов или конкретную версию для каждого пакета.
  • Он упрощает как внутреннее, так и стороннее управление зависимостями - все существует в одной базе кода.
  • Позже переключиться на конфигурацию монорепозитория будет сложнее.

В нашем дереве React Tree наш первоначальный проект включал базовый компонент (на основе @ эмоции / core) с простым стилем.

Позже мы решили опубликовать дерево материалов (с использованием компонентов UI-материала), которое зависит от основного компонента. Сделать это в монорепозитории было очень просто - мы просто добавили еще один пакет.

Итак, сегодня мы поддерживаем две необязательные темы:

  • Основная тема
  • Материальная тема

Каждая тема хранится как отдельный пакет с собственным отдельным package.json. Это позволяет нам публиковать каждый пакет независимо, а наши потребители могут просто загрузить и использовать нужную им тему.

Нашим монорепо управляет Лерна. Lerna - это инструмент, который позволяет нам легко управлять несколькими пакетами одновременно, с такими функциями, как связывание между пакетами, публикация нескольких пакетов одновременно, обновление версий пакетов и т. Д.

Лерна поддерживает два режима:

  • Фиксированный / заблокированный: этот режим связывает все версии пакета вместе. В корневом файле lerna.json хранится только одна версия, представляющая все пакеты. Это режим "по умолчанию".
    Используйте этот режим, если ваши пакеты связаны или взаимозависимы.
  • Независимо: в этом режиме версии пакетов обновляются независимо друг от друга. Используйте этот режим, если ваши пакеты не зависят друг от друга.

Как создать монорепо

  1. Установите Lerna CLI глобально:
npm install --global lerna

2. В корневой папке запустите lerna init:

lerna init

Это автоматически создает следующую структуру:

Где:

  • Следующие поля находятся в файле package.json:

Следующие поля находятся в файле lerna.json:

3. Обновите поля в lerna.json:

useWorkspaces обеспечивает интеграцию с Yarn Workspaces.
Поле пакетов больше не требуется в lerna.json, потому что, когда для useWorkspaces установлено значение true, ваши пакеты берутся из корневого package.json / workspaces.

4. Добавьте поле рабочих областей в package.json:

Чтобы просмотреть пример, просмотрите основные package.json и lerna.json дерева React Tree.

Это хорошая контрольная точка для продвижения вашего первоначального коммита. Затем мы добавим новый пакет.

Добавьте свой пакет!

Теперь, когда вы создали основную структуру своего репозитория, следующим шагом будет создание пакета, который будет опубликован. Вы делаете это, добавляя новый пакет в папку пакетов:

В папке пакеты выполните команду lerna create: lerna create ‹package_name›.

Это создает новый пакет с новым файлом package.json.

Вот несколько основных полей, которые вам следует добавить в свой package.json:

На этом этапе ваш проект должен выглядеть так:

Вы найдете свои опубликованные пакеты в папках package_1.

Например:

У нас есть 2 опубликованных пакета в React Tree:

У каждого из этих пакетов есть отдельный package.json. Они публикуются отдельно, и их версии не зависят друг от друга.

Теперь, когда у вас есть пакет для публикации, вы можете настроить свой проект для работы с CI \ CD.

Шаг 2: CI / CD с действиями GitHub

CI / CD относится к практике непрерывной интеграции и непрерывного развертывания / доставки. С GitHub Actions это сделать очень просто!

Действия GitHub - это конвейеры CI / CD внутри GitHub. Вы собираетесь использовать их для автоматической публикации пакетов при слиянии кода с основной веткой.

GitHub Actions бесплатны для проектов с открытым исходным кодом, и нам было легко управлять сборками на одной платформе. Однако есть несколько отличных альтернативных конвейеров, таких как Travis или CircleCI.

GitHub Actions помогает нам легко управлять жизненным циклом разработки в Kenshoo. Все его задания и задачи находятся в одном yaml-файле.

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

Но что такое событие? Вот несколько полезных определений этого и других терминов:

  • событие: действие, которое запускает рабочий процесс, например, когда кто-то отправляет фиксацию или создается проблема или запрос на вытягивание. Основные события, которые мы используем в Kenshoo, - это pull_request, push и release. Вы можете увидеть все определенные события здесь.
  • рабочий процесс: одно или несколько заданий, запланированных или инициированных событием.
  • работа: серия шагов.
  • шаг: отдельная индивидуальная задача.
  • действие: предопределенная команда, предоставленная GitHub, сообществом или разработанная вами.

Перейдем к пониманию файловой структуры.

Структура файла YAML:

Вот пример файла yaml:

Где:

  • В верхней части файла указано его имя.
  • Раздел on определяет событие, которое запускает это действие.

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

Ваш следующий шаг - объявить задания - серию шагов, которые вы собираетесь выполнить!

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

Для каждого задания вы определяете хост, на котором оно выполняется, и шаги, которые оно должно выполнить.

Вы делаете это, заявляя следующее:

  • выполняется: виртуальная среда хоста (в основном, версия ОС).
  • шаги: каждый шаг имеет собственное уникальное имя, за которым следует действие использует или запустить.

использует: использование заранее определенных действий, созданных сообществом.

run: команды оболочки

В нашем примере выше первые два шага используют предопределенные действия GitHub. Третий шаг просто запускает команду оболочки. Поскольку для некоторых действий GitHub требуется параметр, мы можем использовать ключ with для его передачи. Как видно выше, на этапе Настройка Node.js требуется версия узла.

Вы можете скопировать приведенный ниже yaml-файл в свой репозиторий, чтобы установить, собрать и выпустить свой коммит в свою основную ветку:

* Чтобы получить токены на этапе Создать выпуск, перейдите на вкладку секреты на странице настроек репозитория GitHub:

* Мы расскажем о команде auto shipit в следующем посте!

Резюме

В этом посте мы рассмотрели первые два шага по открытию исходного кода проекта:

  1. Создание проекта
  2. CI\CD

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

  1. Издательский
  2. Документация