DocumentationCommerceImplementation Playbook

Code management best practices for Adobe Commerce

Last update: Fri Sep 29 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Developer

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.

NOTE
These best practices are most suitable for migrations and implementations; less so for single module development.

Affected products and versions

All supported versions of:

  • Adobe Commerce on cloud infrastructure
  • Adobe Commerce on-premises

It covers both global reference architecture (GRA) and single instance installations.

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

Code managed primarily through Git
Code managed primarily through Composer
When to use for a single-instance setup
  • 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 to use for a multi-instance setup
  • 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

Feature
Git
Composer
Main code repository
All code resides in one single, or a few Git repositories
All code resides in the packages in a Composer repository
Each single Composer package is represented by a Git repository
Code location
Development happens in the app/ directory
Development happens in the vendor/ directory
Core upgrade management
Adobe Commerce core is installed and upgraded using Composer, the result is committed in Git
Adobe Commerce core is installed and upgraded using Composer; the result is committed in Git
Third-party module management
Third-party modules are installed in vendor/ if they are installed through the marketplace or packagist.org. Otherwise they are installed in app/
All third-party modules are installed in the vendor/ directory
Releases
Releasing is characterized by git merge and git pull or git checkout commands
Releasing is characterized by composer update and git pull or git checkout commands
Number of Git repositories
Few
Many
Development complexity
Simple
Complex
Pull request complexity
Simple
Complex
Code review complexity
Simple
Simple
Dev/QA/UAT environment update complexity
Simple
Complex
GRA support
Yes icon
Yes icon
Modules can automatically install external libraries
No icon
Yes icon
Flexibility in GRA composition
No icon
Yes icon
Module dependency management
Yes icon Only through module.xml, limited functionality
Yes icon Full dependency management through composer.json
Module versioning
Yes icon You can define a version, but you cannot install a specific version
Yes icon Full version support
Paid services needed
Git repository
Git repository, Private Packagist (± €600 per year)
Bitbucket integration with Jira possible
Yes icon
Yes icon
Changes to code instantly available for installation
Yes icon
Yes icon

Solutions to avoid

  1. Combining Composer and app/code for your modules

    Result 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.

  2. 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.

  3. 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.

recommendation-more-help
754cbbf3-3a3c-4af3-b6ce-9d34390f3a60