Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
bin
 
 
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Not only Composer tools to build a Monorepo

Downloads total

Do you maintain a monorepo with more packages?

This package has few useful tools, that will make that easier.

Install

composer require symplify/monorepo-builder --dev

Usage

0. Are you New to Monorepo?

The best to lean-in fast is to read basic intro at blog post All You Always Wanted to Know About Monorepo. We also made a simple command to make that easy for you:

vendor/bin/monorepo-builder init

And the basic setup is done!

1. Merge local composer.json to the Root One

Merges configured sections to the root composer.json, so you can only edit composer.json of particular packages and let script to synchronize it.

Sections that are needed for monorepo to work will be merged:

  • 'require'
  • 'require-dev'
  • 'autoload'
  • 'autoload-dev'
  • 'repositories'
  • 'extra'

To merge run:

vendor/bin/monorepo-builder merge

Typical location for packages is /packages. But what if you have different naming or extra /projects directory?

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();

    // where are the packages located?
    $parameters->set(Option::PACKAGE_DIRECTORIES, [
        // default vaulue
        __DIR__ . '/packages',
        // custom
        __DIR__ . '/projects',
    ]);

    // how skip packages in loaded direectories?
    $parameters->set(Option::PACKAGE_DIRECTORIES_EXCLUDES, [__DIR__ . '/packages/secret-package']);

    // "merge" command related

    // what extra parts to add after merge?
    $parameters->set(Option::DATA_TO_APPEND, [
        'autoload-dev' => [
            'psr-4' => [
                'Symplify\Tests\\' => 'tests',
            ],
        ],
        'require-dev' => [
            'phpstan/phpstan' => '^0.12',
        ],
    ]);

    $parameters->set(Option::DATA_TO_REMOVE, [
        'require' => [
            // the line is removed by key, so version is irrelevant, thus *
            'phpunit/phpunit' => '*',
        ],
    ]);
};

2. Bump Package Inter-dependencies

Let's say you release symplify/symplify 4.0 and you need package to depend on version ^4.0 for each other:

vendor/bin/monorepo-builder bump-interdependency "^4.0"

3. Keep Synchronized Package Version

In synchronized monorepo, it's common to use same package version to prevent bugs and WTFs. So if one of your package uses symfony/console 3.4 and the other symfony/console 4.1, this will tell you:

vendor/bin/monorepo-builder validate

4. Keep Package Alias Up-To-Date

You can see this even if there is already version 3.0 out:

{
    "extra": {
        "branch-alias": {
            "dev-master": "2.0-dev"
        }
    }
}

Not good. Get rid of this manual work and add this command to your release workflow:

vendor/bin/monorepo-builder package-alias

This will add alias 3.1-dev to composer.json in each package.

If you prefer 3.1.x-dev over default 3.1-dev, you can configure it:

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    // default: "<major>.<minor>-dev"
    $parameters->set(Option::PACKAGE_ALIAS_FORMAT, '<major>.<minor>.x-dev');
};

5. Split Directories to Git Repositories

Classic use case for monorepo is to synchronize last tag and the master branch to allow testing of @dev version.

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set(Option::DIRECTORIES_TO_REPOSITORIES, [
        __DIR__ . '/packages/package-builder' => 'git@github.com:symplify/package-builder.git',
        __DIR__ . '/packagages/monorepo-builder' => 'git@github.com:symplify/monorepo-builder.git',
        __DIR__ . '/packagages/coding-standard' => 'git@github.com:symplify/coding-standard.git',
    ]);
};

Or even simpler:

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set(Option::DIRECTORIES_TO_REPOSITORIES, [
        __DIR__ . '/packages/*' => 'git@github.com:symplify/*.git',
    ]);
};

And run by:

vendor/bin/monorepo-builder split

To speed up the process about 50-60 %, all repositories are synchronized in parallel.

Testing split locally

If you want to test on local machine, you can set local targets by creating bare repositories:

mkdir -p [target/path.git]
cd [target/path.git]
git init --bare
#        ^^^^^^ bare!!!

Then you can set the target using file:// prefix for absolute path:

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (ContainerConfigurator $containerConfigurator): void {
    $parameters = $containerConfigurator->parameters();
    $parameters->set(Option::DIRECTORIES_TO_REPOSITORIES, [
        __DIR__ . '/packages/package-builder' => 'file:///home/developer/git/package-builder.git',
        __DIR__ . '/packagages/monorepo-builder' => 'file:///home/developer/git/monorepo-builder.git',
    ]);
};

After that you can test the result:

vendor/bin/monorepo-builder split
cd /tmp
git clone /home/developer/git/package-builder.git
cd package-builder
git log

6. Release Flow

When a new version of your package is released, you have to do many manual steps:

  • bump mutual dependencies,
  • tag this version,
  • git push with tag,
  • change CHANGELOG.md title Unreleated to v<version> - Y-m-d format
  • bump alias and mutual dependency to next version alias

But what if you forget one or do it in wrong order? Everything will crash!

The release command will make you safe:

vendor/bin/monorepo-builder release v7.0

Are you afraid to tag and push? Use --dry-run to see only descriptions:

vendor/bin/monorepo-builder release v7.0 --dry-run

Do you want ot release next patch version, e.g. current v0.7.1 → next v0.7.2?

vendor/bin/monorepo-builder release patch

You can use minor and major too.

7. Set Your Own Release Flow

There is set of few default release workers - classes that implement Symplify\MonorepoBuilder\Release\Contract\ReleaseWorker\ReleaseWorkerInterface.

You need to register them as services. Feel free to start with default ones:

<?php

// monorepo-builder.php

declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
    $services = $containerConfigurator->services();

    // release workers - in order to execute
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\SetCurrentMutualDependenciesReleaseWorker::class);
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\AddTagToChangelogReleaseWorker::class);

    // you can extend with your own
    $services->set(App\SendPigeonToTwitterReleaseWorker::class);

    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\TagVersionReleaseWorker::class);
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\PushTagReleaseWorker::class);
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\SetNextMutualDependenciesReleaseWorker::class);
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\UpdateBranchAliasReleaseWorker::class);
    $services->set(Symplify\MonorepoBuilder\Release\ReleaseWorker\PushNextDevReleaseWorker::class);
};

Contributing

Open an issue or send a pull-request to main repository.

You can’t perform that action at this time.