💁🏻‍♀️ Зачем Gato GraphQL нужен монорепозиторий, и как он оптимизирован

Несколько дней назад я опубликовал статью Hosting all your PHP packages together in a monorepo, в которой объяснил, зачем использовать монорепозиторий для управления PHP-кодовой базой, и как это делается с помощью Monorepo Builder.

Здесь я хотел бы дополнить ту статью, более подробно объяснив, почему кодовая база GatoGraphQL/GatoGraphQL (в которой размещены Gato GraphQL, лежащий в её основе движок GraphQL и архитектура компонентной модели, на которой она построена) должна размещаться в монорепозитории, а также какие оптимизации я для этого применил.

​

Зачем Gato GraphQL нужен монорепозиторий

Для поддержки независимости от CMS кодовая база Gato GraphQL и связанных проектов была разделена на множество пакетов, управляемых через Composer. В общей сложности было создано более 100 пакетов! (На данный момент их число превышает 200.)

Большое количество пакетов не создаёт дополнительной сложности при их совместной сборке через Composer: достаточно выполнить composer install, и всё работает. Однако при разработке это становится проблемой, когда каждый пакет живёт в собственном репозитории — из-за версионирования.

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

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

Это было неправильно. Переход на модель монорепозитория с размещением всего кода в GatoGraphQL/GatoGraphQL эффективно решил проблему.

​

Приятный побочный эффект: снижение порога входа для контрибьюторов

Как я упомянул в статье, в те времена, когда проект использовал один репозиторий на пакет, один из участников покинул проект ещё до того, как успел присоединиться, — из-за невозможности настроить рабочее окружение.

До перехода на монорепозиторий настройка среды разработки была очень сложной. Поскольку я был автором, мне удавалось клонировать все репозитории и объединять их в одном рабочем пространстве VSCode, что кое-как работало для меня.

Я пытался упростить настройку той же среды для потенциальных контрибьюторов с помощью этого bash-скрипта. Но если честно, это никогда не могло сработать — это была проигранная битва с самого начала, и никто не мог начать вносить вклад в проект.

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

​

Оптимизация монорепозитория

Как я упомянул в статье, преимущество использования библиотеки Monorepo Builder перед альтернативами заключается в том, что она построена на PHP и её можно расширять.

Например, при push в master и разделении монорепозитория матрица в GitHub Action обычно запускает один экземпляр runner на каждый пакет, чтобы синхронизировать его код с собственным репозиторием (для распространения через Packagist).

Поскольку GatoGraphQL/GatoGraphQL содержит более 200 пакетов, это означало, что запускалось более 200 экземпляров runner.

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

Кроме того, GitHub периодически не предоставляет runner немедленно и заставляет ждать:

Всё это выливается во время ожидания. При более чем 200 пакетах слияние одного PR могло занимать до 1 часа! Эту проблему нужно было решить.

Расширение монорепозитория пользовательскими командами может решить проблему.

​

Расширение Monorepo builder

Как правило, при выполнении следующей команды мы получаем список всех пакетов в репозитории:

vendor/bin/monorepo-builder packages-jsonCopy

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

Если мы можем узнать список изменённых файлов, то сможем определить, в каких пакетах они находятся. Иными словами: выполнить git diff и передать результаты команде packages-json через входной параметр filter, вот так:

vendor/bin/monorepo-builder packages-json --filter=modified_file_1 --filter=modified_file_2 --filter=...Copy

Между тем команда packages-json, поставляемая с Monorepo Builder, не принимает входной параметр filter. Вот здесь и нужно расширить её пользовательскими командами.

Monorepo builder использует Symfony's DependencyInjection, поэтому его можно расширить, внедряя новые сервисы в его контейнер. Действительно, файл конфигурации monorepo-builder.php уже является конфигуратором сервисов.

Поэтому я расширил Monorepo builder новой командой package-entries-json, которая поддерживает входной параметр filter:

final class PackageEntriesJsonCommand extends AbstractSymplifyCommand
{
  private PackageEntriesJsonProvider $packageEntriesJsonProvider;
 
  public function __construct(PackageEntriesJsonProvider $packageEntriesJsonProvider)
  {
    $this->packageEntriesJsonProvider = $packageEntriesJsonProvider;
 
    parent::__construct();
  }
 
  protected function configure(): void
  {
    $this->setDescription('Provides package entries in json format. Useful for GitHub Actions Workflow');
    $this->addOption(
      Option::FILTER,
      null,
      InputOption::VALUE_OPTIONAL | InputOption::VALUE_IS_ARRAY,
      'Filter the packages to those from the list of files. Useful to split monorepo on modified packages only',
      []
    );
  }
 
  protected function execute(InputInterface $input, OutputInterface $output): int
  {
    /** @var string[] $fileFilter */
    $fileFilter = $input->getOption(Option::FILTER);
 
    $packageEntries = $this->packageEntriesJsonProvider->providePackageEntries($fileFilter);
 
    // must be without spaces, otherwise it breaks GitHub Actions json
    $json = Json::encode($packageEntries);
    $this->symfonyStyle->writeln($json);
 
    return ShellCode::SUCCESS;
  }
}Copy

Она внедряется в контейнер сервисов следующим образом:

return static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();
    $services->defaults()->autowire()->autoconfigure();
    $services->set(PackageEntriesJsonCommand::class);
}Copy

Теперь новая команда package-entries-json будет доступна для workflow GitHub Action.

​

Получение списка изменённых файлов в GitHub Action

Посмотрим, как обновить workflow.

Я удобно использую action technote-space/get-diff-action, которое предоставляет git diff всех изменённых файлов в PR:

# git diff to generate matrix with modified packages only
- uses: technote-space/get-diff-action@v4
  with:
    PATTERNS: layers/*/*/*/**Copy

На основе этих результатов (хранящихся в ${{ env.GIT_DIFF }}) я затем формирую вызов пользовательской команды package-entries-json и устанавливаю её как output:

- id: output_data
  name: Calculate matrix for packages
  run: |
    quote=\'
    clean_diff="$(echo "${{ env.GIT_DIFF }}" | sed -e s/$quote//g)"
    packages_in_diff="$(echo $clean_diff | grep -E -o 'layers/[A-Za-z0-9_\-]*/[A-Za-z0-9_\-]*/[A-Za-z0-9_\-]*/' | sort -u)"
    echo "[Packages in diff] $(echo $packages_in_diff | tr '\n' ' ')"
    filter_arg="--filter=$(echo $packages_in_diff | sed -e 's/ / --filter=/g')"
    echo "::set-output name=matrix::$(vendor/bin/monorepo-builder package-entries-json $(echo $filter_arg))"Copy

Полученные пакеты затем используются для создания матрицы:

outputs:
  matrix: ${{ steps.output_data.outputs.matrix }}Copy

Работает отлично! В данном случае было изменено только два пакета, поэтому в матрице было запущено только 2 экземпляра:

Теперь слияние PR занимает всего несколько минут (вместо 1 часа), так что я снова счастливый разработчик.

​

Дальнейшие оптимизации / сложности

Есть ещё одна область, где можно сэкономить время на GitHub Action: при выполнении тестов PHPUnit.

В настоящее время при загрузке нового кода запускается весь набор тестов для всех пакетов. Но это тоже можно оптимизировать.

Допустим, монорепозиторий содержит 3 пакета: A, B и C, где B зависит от A, а C зависит от B.

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

• Изменение кода A: нужно тестировать A, B и C
• Изменение кода B: нужно тестировать B и C
• Изменение кода C: нужно тестировать C

Оптимизация будет зависеть от получения списка изменённых пакетов (как в предыдущей оптимизации) и выполнения тестов для них и для всех пакетов, которые от них зависят.

Однако в настоящее время у меня нет информации о том, как каждый пакет в монорепозитории зависит от остальных.

Хотя корневой composer.json содержит все локальные пакеты, получить их зависимости через Composer, выполнив composer info ${ package_name }, не получится, потому что они определены в секции replace, а не в require.

Как вариант, можно было бы заходить в подпапку каждого пакета, выполнять composer install, а затем делать composer info. Но выполнять composer install более 200 раз — это настоящее безумие.

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

​

Подводя итоги

Должен сказать, что я чрезвычайно доволен открытием Monorepo Builder. Не думаю, что смог бы управлять кодовой базой Gato GraphQL иначе.

Я не утверждаю, что каждый проект должен его использовать. Но когда у вас более 200 пакетов, как в моём случае, или даже более 20, он абсолютно упрощает жизнь.

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