[Contribution de Tony Evers, architecte technique principal, Adobe]{class="badge informative" title="Contribution Tony Evers"}

Modèle d’architecture de référence globale Monorepo

Ces informations s’appliquent à :

Ce guide explique comment configurer Adobe Commerce avec le modèle d’architecture de référence globale (GRA) Monorepo.

Le modèle GRA Monorepo implique un référentiel Git unique pour héberger toutes les personnalisations courantes. Ce référentiel Git unique est exposé via le compositeur en tant que packages de compositeur distincts.

{align="center"}

Avantages et inconvénients de ce modèle

Avantages :

Inconvénients :

Set up Adobe Commerce with the Separate Packages GRA pattern

La structure du répertoire

The final directory structure of a full Adobe Commerce installation with the Separate Packages GRA pattern has this directory structure:

.
├── app/
│   └── etc/
│       └── config.php
├── packages/
│   └── ...
├── composer.json
└── composer.lock

A production Git repository has this directory structucture:

.
├── app/
│   └── etc/
│       └── config.php
├── composer.json
└── composer.lock

The difference is that the production instances install from Composer, where the monorepo holds its own copy of every package inside the packages directory.

Prepare a production repository

Créez un référentiel pour la première instance d’Adobe Commerce, qui représente un magasin web pour Brand X.

mkdir gra-monorepo-brand-x
cd gra-monorepo-brand-x
composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition .
git init
git remote add origin git@github.com:AntonEvers/gra-monorepo-brand-x.git
git add composer.json composer.lock
git commit -m 'initialize Brand X repository'
git push -u origin main

Installez Adobe Commerce avec bin/magento setup:install. Commit the resulting app/etc/config.php and the composer files. Composer manages anything else so nothing else should be in Git.

Prepare the monorepo repository

The monorepo repository starts with the same steps.

mkdir gra-monorepo
cd gra-monorepo
composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition .

Install Adobe Commerce with bin/magento setup:install, commit and push.

git init
git remote add origin git@github.com:AntonEvers/gra-monorepo.git
git add composer.json composer.lock app/etc/config.php
git commit -m 'initialize monorepo GRA development repository'
git push -u origin main

Prepare for monorepo development

For monorepo development, make the following changes to your composer.json file:

The following Git diff shows the difference between a clean Adobe Commerce install and the changes mentioned above:

@@ -1,6 +1,6 @@
 {
-    "name": "magento/project-enterprise-edition",
-    "description": "eCommerce Platform for Growth (Enterprise Edition)",
+    "name": "antonevers/gra-monorepo",
+    "description": "Monorepo repository for Global Reference Architecture development",
     "type": "project",
     "license": [
         "proprietary"
@@ -15,11 +15,8 @@
         "preferred-install": "dist",
         "sort-packages": true
     },
-    "version": "2.4.7-p3",
     "require": {
-        "magento/product-enterprise-edition": "2.4.7-p3",
-        "magento/composer-dependency-version-audit-plugin": "~0.1",
-        "magento/composer-root-update-plugin": "^2.0.4"
+        "antonevers/gra-meta-brand-x": "self.version"
     },
     "autoload": {
         "exclude-from-classmap": [
@@ -69,16 +66,33 @@
             "Magento\\Tools\\Sanity\\": "dev/build/publication/sanity/Magento/Tools/Sanity/"
         }
     },
-    "minimum-stability": "stable",
+    "minimum-stability": "dev",
     "prefer-stable": true,
     "repositories": [
         {
+            "type": "path",
+            "url": "packages/*/*",
+            "options": {
+                "versions": {
+                    "antonevers/gra-meta-brand-x": "1.4.x-dev",
+                    "antonevers/gra-meta-foundation": "1.4.x-dev",
+                    "antonevers/gra-component-foundation": "1.4.x-dev",
+                    "antonevers/module-gra": "1.4.x-dev",
+                    "antonevers/module-3rdparty": "1.4.x-dev",
+                    "antonevers/module-local": "1.4.x-dev"
+                }
+            }
+        },
+        {
             "type": "composer",
             "url": "https://repo.magento.com/"
         }
     ],
     "extra": {
-        "magento-force": "override"
+        "magento-force": "override",
+        "branch-alias": {
+            "dev-main": "1.4.x-dev"
+        }
     }
 }

Use metapackages

Download the example code from AntonEvers/gra-meta-foundation on GitHub to get the metapackages and the sample modules that are used in this example.

Composer metapackages bundle multiple composer packages together under a single package. When a metapackage is required, all packages it bundles are automatically installed through the Composer require section of the metapackage.

For this example, there are two metapackages:

The brand metapackage requires the foundation metapackage. When brand metapackage is required, the foundation metapackage is automatically required as well. Please see the two composer.json files of the metapackages to see how they relate:

antonevers/gra-meta-brand-x:

{
    "name": "antonevers/gra-meta-brand-x",
    "type": "metapackage",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "require": {
        "antonevers/gra-meta-foundation": "^1.4",
        "antonevers/module-local": "^1.4"
    }
}

antonevers/gra-meta-foundation:

{
    "name": "antonevers/gra-meta-foundation",
    "type": "metapackage",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "require": {
        "antonevers/gra-component-foundation": "^1.4",
        "antonevers/module-gra": "^1.4",
        "antonevers/module-3rdparty": "^1.4",
        "magento/composer-dependency-version-audit-plugin": "~0.1",
        "magento/composer-root-update-plugin": "^2.0.4",
        "magento/product-enterprise-edition": "2.4.7-p3"
    }
}

Metapackages are a good way to organize code that belongs together. Use metapackages to define groups of packages that are regional, global, brand-specific or any grouping that makes sense for you. If you maintain multiple installations of Adobe Commerce, matapackages a safe and versatile way of defining the context in which a package is expected.

Metapackages exist in the monorepo inside the packages directory. There, the directory structure of the vendor is mirrored:

.
├── packages/
│   └── antonevers
│       ├── gra-meta-brand-x
│       │   └── composer.json
│       └── gra-meta-foundation
│           └── composer.json
├── composer.json
└── composer.lock

Add and develop modules

Modules in the monorepo exist in the packages directory. This way Composer can find them through the path type repository.

Download the example code from AntonEvers/gra-meta-foundation on GitHub to get the metapackages and the sample modules that are used in this example.

.
├── packages/
│   └── antonevers
│       ├── gra-meta-brand-x
│       ├── gra-meta-foundation
│       ├── module-3rdparty
│       ├── module-gra
│       └── module-local
├── composer.json
└── composer.lock

You can have multiple namespaces inside the packages directory if needed.

Development takes place in the packages directory. Symlinks to the packages inside the packages directory are created in the vendor directory once you run composer update. This way, the code becomes part of the Adobe Commerce installation.

Run bin/magento module:enable --all or for only specific modules to enable the modules that were added.

By now you should have a working Adobe Commerce installation with the three sample modules installed and working. You can validate if the modules are installed and working by running the commands:

bin/magento test:gra
bin/magento test:3rdparty
bin/magento test:local

Achieve automated package creation

There are multiple options to achieve automated package creation. Some options are:

Private Packagist automates recognizing packages in the Git monorepo and exposes them through Composer. It is compatible with Adobe Commerce, fast, low-maintenance and error-prone, which is why this guide focuses on the Private Packagist option.

It is beyond the scope of this guide to explain how to set up Private Packagist, please see the docs.

There is the possibility to turn a package into a monorepo once you have set up organization syncing and your Git repositories are automatically syncing to Private Packagist.

First, go to the packages tab and find the monorepo:

{align="center"}

Click on the monorepo package and click “Edit” in the details screen, which takes you to the following page:

Underneath the first input field, there is a link saying: Create a multi-package repository. Click this link.

Define the location where composer packages can be found inside your monorepo. In the example, the location is packages/**/composer.json. Change the location to limit or broaden where Private Packagist searches for packages to extract.

L’onglet Packages affiche tous les packages trouvés après l’enregistrement et le monorepo lui-même n’est plus visible en tant que package de compositeur :

Une version est créée dans le compositeur pour chaque package du monoréférentiel, pour chaque balise ou branche créée sur le monoréférentiel dans Git.

Installation des packages dans l’environnement de production

Suivez les instructions de Private Packagist pour ajouter Private Packagist en tant que référentiel de compositeur. Private Packagist peut et doit être utilisé comme miroir pour tous vos référentiels Composer et Git, y compris packagist.org. Ainsi, les informations d’identification ne doivent pas être partagées avec les développeurs et vous avez un contrôle total sur chaque package. Cet exemple ne suit pas cette bonne pratique, car il exposerait la base de code Adobe Commerce publiquement.

Téléchargez GRA Monorepo Brand X sur GitHub pour voir un exemple de magasin de production.

Dans le magasin de production, il n’existe aucun répertoire packages et tous les packages sont installés via le compositeur. Le seul package requis est :

    "require": {
        "antonevers/gra-meta-brand-x": "^1.0"
    },

Pourtant, l’intégralité d’Adobe Commerce et de GRA est installée selon les exigences de ce métapaquet.

Contrôle de version

Tous les packages du monorepo reçoivent la même version que le monorepo lui-même. Considérez cela comme la publication de nouvelles versions de l’ensemble de l’application. En production, cependant, vous pouvez installer un mélange de packages provenant de différentes versions de monorepo.

Environnements éphémères

Si vous utilisez des environnements éphémères ou si vous envisagez de les utiliser, le monorepo est un excellent choix. Chaque version et branche du monorepo contient tous les fichiers de modules Adobe Commerce, tiers et personnalisés. Avec une installation complète dans chaque branche, il est possible d’exécuter tous les types de tests, y compris les tests fonctionnels. Avec d’autres configurations GRA, telles que les packages distincts ou les packages en masse GRA, vous devez d’abord créer un environnement Adobe Commerce fonctionnel avant de pouvoir exécuter des tests fonctionnels. Du point de vue de DevOps, monorepo le rend beaucoup plus simple.

Exemples de code

Les exemples de code de cet article ont été combinés dans un ensemble de référentiels Git, que vous pouvez utiliser pour jouer avec la preuve de concept.