Release a new version of a native PrestaShop module
Some modules are embedded within PrestaShop ZIP archives and loaded through Composer package manager. They consequently are listed in the
composer.json of the Core project.
This is what we call “native PrestaShop modules”. The source code of these modules is hosted on GitHub.
This page explains what is needed to release these modules.
The module should be valid which means:
- it works as expected
- it complies with modules contribution guidelines: license headers must be valid and necessary files (LICENSE, CONTRIBUTORS) must be embedded
It is recommended:
- to have enabled Release Drafter on the module to automatize the process of creating a new GitHub release
- have enabled some Continous Integration tools such as phpstan or php-cs-fixer on the module
These tools will help releasing a clean module in a smooth manner but the release can happen without them.
When multiple improvements (bug fixes, enhancements or new features) have been merged into the
dev branch of a module, we can merge them into
master to deliver a new release of the module.
Choosing the new version number
We follow SemVer guidelines:
If the new version of the module is backward compatible, you can increase the version number either by a minor version or by a patch version.
However, if the new version of the module breaks backward compatibility, it must be a new major version.
Update version number in the code
Create a Pull Request targeting
dev branch. In this PR:
Update the module version in the following files:
Commit the changes with git message:
// Version updated to v<new_version>
Get this PR approved and merge it into
dev. See an example of such PR.
Merge dev into master
Create a new PR to merge branch
dev into branch
master. See an example of such PR.
Kindly ask the QA team to perform a release test on this PR, warning them that this PR is a release PR and consequently they need to check the whole module behavior.
If QA validates the PR, it can be merged, which will update the
master branch with the new code changes from
Create a GitHub Release
If you have enabled Release Drafter, it will create a draft release for you. You can review it and publish it.
Else, you need to do it manually:
Create a new tag with “v<new_version>” that targets the last commit on
master and push it. This will publish the module version on https://packagist.org/ .
Create a release on Github based on the tag you just pushed. In the content section, write a small changelog: list the PRs merged since the last version so that people can know what is included in the release (see this example).
(by the way, GitHub is able to create the release and the tag at the same time from the “create a new release” page)
Attach to GitHub release a stand-alone ready-to-use ZIP archive of the module.
This archive must be a stand-alone running module, which means it musts embeds all necessary files for its correct behavior. This includes bundled frontend assets (JS, CSS), NPM dependencies or Composer dependencies.
Create a new milestone
Once the GitHub release is done, you can create a new milestone and close the old one.
In the module’s repository, click on
pull requests, and then on
milestones next to the search field.
To create a new milestone, click
new milestone and fill out the form, you can leave the
due date field empty if it is not relevant. Once the new milestone is created you can close the old one.
Addons and Distribution API
PrestaShop 1.7 and 1.6 instances were able to download new versions of modules through the Addons API. Addons API monitors the modules listed into the GitHub repository https://github.com/PrestaShop/PrestaShop-modules
master branch of one of these modules receives an update, Addons API will update the ZIP it delivers with the new content within 24 hours.
PrestaShop 8 now relies on PrestaShop Modules Distribution API that monitors GitHub releases and allow PrestaShop instances to poll for new module versions and download them.