Release Management


We follow semantic versioning where a version number looks like this: MAJOR.MINOR.PATCH.

New release (patch, minor or major)

  • We first release one or multiple beta versions while working on a release.
  • Once all features and fixes have been implemented we release an RC (release candidate).
  • Along with the RC we create a new branch called next_release.
    • Any regression fix or very important bug fixes that have a low risk for side effects can be merged into the next_release branch if this needs to be included in the next release. We then release another RC (which depends on things like time left to the release, whether other changes will be merged into next_release as well etc). The release manager should be notified to trigger a new release. It's not needed to create another PR for *.x-dev for the same change, as we merge the changes from next_release into *.x-dev after the release.
    • Any other change can be merged into *.x-dev as usual and won't be included in the upcoming release.
  • We usually run the RC for a minor release for at least a week, for major releases multiple weeks and for patch releases at least one day but better multiple days.
  • Once a new release has been released, we create a PR to merge the next_release branch into *.x-dev see changes. The release manager will do this.
  • Should a patch release be needed, then we repeat this process. We create a branch next_release off the branch of the last release (not off *.x-dev). Any patch fix will need to be made against the next_release branch.

New patch releases

We aim to only merge changes that either:

  • fix a regression
  • or they fix an important bug and there is basically no risk of introducing new regressions

The goal is to not introduce new regressions in a patch release. These releases should also be released fairly soon after a minor or patch release depending on the severity of the regressions.

If there are any other changes or even new features then we instead release a new minor version.

New major releases

Short guide on what to do when working on a new major release

Moving core plugins to the Marketplace

For any plugin that will be moved to the marketplace make sure the plugin has a plugin.json file and a fixed version number set. We would set the version number to the current core version and it should not be needed to increase that version number. This should ensure Matomo will find the plugin on the marketplace.

Users that upgrade from a version older than Matomo 3.14.1 that plugin will be deactivated after the upgrade. However, even after updating the plugin it will stay deactivated and we cannot automatically activate it because we can't know whether it was activated previously. If still too many people are on a version pre 3.14.1 then would maybe need to ship the plugin that was moved to the marketplace for a few months with core: and only later remove it. In that case we should maybe also add an update/migration similar to this for the plugin: (could refactor code to make it reusable by passing plugin names as an array). However, all this is really only needed for users upgrading from 3.14.1 or earlier. Because we now update plugins in a second step, any newly added plugin.json will be automatically found and everything should work as expected from 3.14.1.

For CustomVariables and Provider plugin the approach we went with is to include the plugins in core for say 6 months so most people will for sure not have any problem when upgrading (many users upgrade to next major version in 6 months). Then we stop and no longer include these plugins in core and people will start receiving the updates from Marketplace. If we include the plugins in the Matomo build script for say 6 months, then we also need to make sure these plugins cannot be uninstalled similar to see also

When starting to work on the next major release

The previous version becomes LTS and we take it seriously

as soon as we start working on the next major version of Matomo, we must STOP making any change to the current LTS version except critical security fixes and major data loss bugs.

If we don't stop making any change to LTS when we start working on the next major version, then we have a lot of merge pain and we cannot afford this.

Also, as soon as we start working on the next major version, we need to require every contributor to create a pull request against both branches, so we don't need to merge branches together which is too painful.


  • Create a new branch that follows our standard, eg 4.x-dev if next new major release will be 4.
  • Create this new branch also for every plugin, increase the required Matomo version to eg "matomo": ">=4.0.0-b1,<5.0.0-b1" and set the version number to 4.0.0
  • Create new release channels to give users the options to stay on Matomo 4 or Matomo 4 beta in plugins/CoreUpdater/ReleaseChannel/. Remove the previous release channel eg Matomo 3 in this case.
  • Update the notifyWhenPhpVersionIsEOL method so the notification pushes users to upgrade their PHP version to the latest. Refs
  • Update the getNextRequiredMinimumPHP so that users not on the minimum required PHP version for the next major Matomo will see a warning in the admin pages
  • Adjust required PHP version in travis tests yml
  • Travis CI, see what we did for Matomo 3 in and
  • Create the PULL_REQUEST_TEMPLATE similar to
  • Once the build for 4.x-dev succeeds, make it the default branch for Matomo and all plugins
  • Update the submodule github action, composer update action, and the CLDR action to use the new main branch.

  • In config add new release channels for this version. For example when new major release is 4 as in 4.0.0 we need to add latest_4x and latest_4x_beta release channels. We only need to add them for now, they can point to the same files as latest_beta and latest_stable for now. The Marketplace will use these release channels to check for latest available versions.
  • In the getLatestVersion API method request the required PHP version for the new major version

  • If new major release will be 4, create and make it checkout the newly created 4.x-dev branch regularly

  • Search for 5. or 7. in the codebase
  • for example in app/helpers/Api.php we have 5.3.3


When releasing a first beta

  • Follow steps as described in
  • Replace all mentions of eg. 3.x-dev by 4.x-dev in the docs (for example this page)
  • Start documenting new APIs and migration guide

  • Increase latest major version in config

When releasing a first RC

  • Merge 3.x-dev into master??

When releasing

Once a LTS version expires, we remove old plugins from the Marketplace

From the Marketplace, we will remove all plugins incompatible with the LTS version or latest stable. So around 12 months after the release of a stable version (for example Matomo 5), when the LTS for Matomo 4 period ends, we start removing plugins that are no compatible with Matomo 4 or Matomo 5.