Code management best practices for Adobe Commerce
This topic is designed to help you decide whether to use Git or Composer to distribute custom code, with consideration for release management, code complexity, and dependency management.
Affected products and versions
- Adobe Commerce on cloud infrastructure
- Adobe Commerce on-premises
Definitions
- Global Reference Architecture (GRA): Also known as White Label Architecture or Common Code Base. This is the module distribution architecture for a multi-instance setup.
- Multi-instance setup: The same client uses separate Adobe Commerce installations for separate regions or brands. Each installation has shared as well as unique modules.
- Single-instance setup: There is only one Adobe Commerce installation. Multiple copies of the source code may exist for different test environments, but there is only one version of the production code.
When to use Git or Composer
- Standard approach for managing code for a single-instance setup
- When the code base will not be part of a multi-brand GRA in the future
- When all brands run on a single instance as websites
- When the code base can or will become part of a multi-instance setup in the future
- When almost all modules are interlinked (not recommended)
- When the code is maintained by a team that is not familiar with Composer
- Standard approach for managing code for a multi-instance setup
- When Adobe maintains the code base or the maintaining team is familiar with Composer
Feature matrix
Each single Composer package is represented by a Git repository
app/
directoryvendor/
directoryvendor/
if they are installed through the marketplace or packagist.org. Otherwise they are installed in app/
vendor/
directorygit merge
and git pull
or git checkout
commandscomposer update
and git pull
or git checkout
commandsmodule.xml
, limited functionality
composer.json
Solutions to avoid
-
Combining Composer and
app/code
for your modulesResult in having all the disadvantages of both code management styles combined in your project. It adds unnecessary complexity, instability, and lack of flexibility.
For example:
- Explain both Git and Composer workflows (instead of only one of them) to the development team.
- Install incompatible modules in
app/code
as there is nothing in place to stop that from happening. - Moving a module from
app/code
to Composer (or conversely) is cumbersome, especially with ongoing development.
-
Satis Package Manager
Private Packagist costs ± €600 per year. This cost is for the whole GRA combined, not per brand. Don’t try to avoid these costs by using the free solution Satis. Satis does not automatically update your packages whenever you push commits to git. Also Satis has no built in authorization. You must maintain a web server to run Satis. You end up spending a multitude of the Private Packagist subscription fee maintaining Satis.
-
Start with Git, then move to Composer
Make the choice for a code management approach at the start of your project. Switching from Git to Composer or conversely, with ongoing development is cumbersome and could lead to code loss and or revision history loss.