People often asks us how to do a Magento 2 Composer Module Update for their extensions whenever they want to release a new version of their modules.
There are different ways of doing it, we will show you how to do with with git tags and a semantic versioning strategy for the releases, which we thing is the most professional and reliable way.
We will continue with the example of our previous post where we showed you how to create a hello world extension in Magento 2 with composer.
For the newcomers to composer, et me quickly give you an brief explanation of how does it work, more specifically, how we use it together with Magento 2 while developing new modules:
- To install a new extension developed by ourselves (or by a third party): We normally use “composer require vendor-name/extension-name” from the root folder of Magento 2. Which, by default (depending on the value we’ve set for “minimum-stability” and “prefer-stable” in our composer.json file) will attempt to install the latest version of that extension that meets its dependencies/requirements within your system/application. This means that, for example, if you are using php 5.5.x and the latest version of the extension that you are installing has a dependency (composer.json “require” section) like:
"php":">=5.6"
Then, the latest version of the extension cannot be installed on your system. Composer will firstly try to install a newer version of the dependency, and failing that, will search backwards previous versions of the extension until it finds the most recent version that works with php 5.5. Eventually, it will fail if it cannot find any version installable (that meets all the dependencies) in your system . Normally, you just run the command and everything runs smoothly, composer will take care of everything from you, but sometimes it will fail with an error like below:
composer require lumbrales-software/magento2-first-module Using version dev-master for lumbrales-software/magento2-first-module ./composer.json has been updated Loading composer repositories with package information Updating dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages. Problem 1 - magento/project-community-edition dev-master requires magento/product-community-edition 2.0.2 -> no matching package found. - magento/project-community-edition 2.0.2 requires magento/product-community-edition 2.0.2 -> no matching package found. - magento/project-community-edition 2.0.1 requires magento/product-community-edition 2.0.1 -> no matching package found. - magento/project-community-edition 2.0.0-rc2 requires magento/product-community-edition 2.0.0-rc2 -> no matching package found.This can sometimes require a system update, or like in the above example, adding a custom repository where composer can find the required package.
- To release a new version (code changes) of your extension: This is the interesting part. People are usually confused and run “composer update” and expect it to do the job, but the problem is that the above command can often lead to undesired and unexpected results, since it will try to update every single package, which is not always (almost never) what we want. Normally, you want to update an specific package, or maybe even a whole vendor, but not everything at once. Therefore, we recommend to tell composer what to do, like in the example of our previous post:
# Update an specific package composer update lumbrales-software/magento2-first-module # Update all packages of the vendor composer update lumbrales-software/*
Having said that, now let’s focus on how to release a new version of our extension.
The process is actually simpler than it might seem, all you have to do is implement your new functionality, code changes, whatsoever, using whichever git branching strategy you want, and once you are ready, you can do the following steps:
- Merge your changes into the master branch
- Choose a version for the update/release, following the guidelines of semantic versioning:
Given a version number MAJOR.MINOR.PATCH, increment the:- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Note: If you want to release a stable version, it has to be at least 1.0.0, otherwise it will be considered unstable by composer and might lead to issues while installing it. - Update your composer.json with the new version (ie. “version”: “1.0.1”,) and commit the changes of the file.
- Create a git tag with the new version:
git tag 1.0.1
- Push the changes and the tag:
git push origin master git push --tag
- That’s it! Now, you should be able to run composer update your-vendor/your-module and it will fetch your changes:
composer update lumbrales-software/magento2-first-module -v
Loading composer repositories with package information
Reading composer.json of lumbrales-software/magento2-first-module (1.0.2)
Importing tag 1.0.2 (1.0.2.0)
Reading composer.json of lumbrales-software/magento2-first-module (1.0.1)
Importing tag 1.0.1 (1.0.1.0)
Reading composer.json of lumbrales-software/magento2-first-module (master)
Importing branch master (dev-master)
Updating dependencies (including require-dev)
- Removing lumbrales-software/magento2-first-module (1.0.1)
- Installing lumbrales-software/magento2-first-module (1.0.2)
Downloading: 100%
Extracting archive
Writing lock file
Generating autoload files
Note: Sometimes composer seems to keep cached the repository changes and won’t fetch your new code changes, I found a workaround for that by clearing the cache with the below command (run it as your own risk):
rm -fr ~/.composer/cache/*
That’s about it, you now should be able to release code changes nicely, and for every new code changes you just need to bump the version accordingly and remember to push both the version update in the composer.json and the git tag.
Good luck!
Let us know if you have any issues with it and we’ll try to assist you.
