💁🏻‍♀️ 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 にホストするモノレポモデルへ移行することで、その問題は効果的に解決されました。

​

歓迎すべき副作用：コントリビューションのハードルが下がる

記事でも述べましたが、プロジェクトがパッケージごとに1つのリポジトリを使っていた頃、1人のコントリビューターが開発環境のセットアップができず、参加する前にプロジェクトを離れてしまいました。

モノレポに移行する前は、開発環境のセットアップは非常に困難でした。私は作者だったので、すべてのリポジトリをクローンして1つの VSCode ワークスペースにまとめることで、なんとか機能させることができました。

潜在的なコントリビューターが同じ環境をセットアップしやすくするため、この bash スクリプトで試みました。しかし正直なところ、それは最初から無理な話で、誰もプロジェクトへの貢献を始めることができませんでした。

モノレポによって、もし誰かが参加したいと思った場合に、不合理な官僚主義でコントリビューターを拒否しないことを確信しながら、夜ぐっすり眠れるようになりました。

​

モノレポの最適化

記事で述べた通り、代替手段と比較して Monorepo Builder ライブラリを使う利点は、PHP で構築されており、拡張可能であることです。

例えば、master へのプッシュ時にモノレポを分割する場合、GitHub Action のマトリックスは通常、各パッケージに対して1つのランナーインスタンスを起動し、そのコードを独自のリポジトリと同期します（Packagist 経由の配布のため）。

GatoGraphQL/GatoGraphQL には200以上のパッケージが含まれているため、200以上のランナーインスタンスが起動されていました。

ここでの問題は、GitHub が並列で実行できるジョブ数を20に制限していることです。すべてのアクションはキューに入れられるため、他のアクションを続行するために完了を待つ必要がありました。

さらに、GitHub がランナーをすぐにプロビジョニングせず、後で待たせることもありました：

これらすべてが待機時間につながります。200以上のパッケージがあると、1つの 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

ところが、Monorepo Builder に付属している packages-json コマンドは filter 入力を受け付けません。ここがカスタムコマンドで拡張しなければならない部分です。

Monorepo Builder は Symfony の DependencyInjection を使用しているため、コンテナに新しいサービスを注入することで拡張できます。実際、設定ファイル monorepo-builder.php はすでにサービスコンフィギュレーターになっています。

そこで、filter 入力をサポートする package-entries-json という新しいコマンドで Monorepo Builder を拡張しました：

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 という新しいコマンドが GitHub Action ワークフローで利用できるようになります。

​

GitHub Action で変更されたファイルの一覧を取得する

次に、ワークフローを更新する方法を見ていきましょう。

私は便利なアクション technote-space/get-diff-action を使用しています。このアクションは、PR で変更されたすべてのファイルの git diff を提供します：

# 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 への呼び出しを生成し、出力として設定します：

- 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つだけだったため、マトリックスで起動されたインスタンスも2つだけでした：

これで PR のマージが1時間からわずか数分に短縮され、再び幸せな開発者になれました。

​

さらなる最適化と課題

GitHub Action の時間を削減できるもう1つの場面があります：PHPUnit テストの実行時です。

現在は、新しいコードがアップロードされるたびに、すべてのパッケージの全テストが実行されます。しかし、これも最適化できます。

モノレポに A、B、C の3つのパッケージがあり、B が A に依存し、C が B に依存しているとします。

この場合、1つのパッケージのコードを変更すると、実行が必要なテストは次のように変わります：

• A のコードを変更した場合：A、B、C をテストする必要がある
• B のコードを変更した場合：B と C をテストする必要がある
• C のコードを変更した場合：C をテストする必要がある

最適化は、変更されたパッケージの一覧（前の最適化と同様）を取得し、それらと依存するすべてのパッケージのテストを実行することに依存します。

しかし現在、モノレポ内の各パッケージが互いにどのように依存しているかの情報を持っていません。

ルートの composer.json にはすべてのローカルパッケージが含まれていますが、require ではなく replace セクションで定義されているため、composer info ${ package_name } を実行して Composer 経由でその依存関係を取得することができません。

代替として、各パッケージのサブフォルダに入り、composer install を実行してから composer info を行うことも考えられます。しかし、200回以上 composer install を実行するのはまったく非現実的です。

そのため、このシナリオはまだ最適化していません。これまでにイシューを作成しており、いつか解決策を見つけることを願っています。

​

まとめ

Monorepo Builder を発見できたことを、非常に嬉しく思っています。これなしでは Gato GraphQL のコードベースを管理できなかったと思います。

すべてのプロジェクトがこれを使うべきだと言っているわけではありません。しかし、私のように200以上のパッケージがある場合、あるいは20以上のパッケージがある場合でも、間違いなく生活が楽になります。

モノレポの管理にはセットアップと維持に少し時間と労力が必要ですが、日々の継続的な開発だけで、その時間と労力を何倍にも取り戻せています。