Maintaining backwards compatibility for our public APIs in Piwik & our release cycles

[tsteur]

Today we had a session about keeping BC for our public APIs and to avoid regressions in patch and minor releases.

The current release cycle is to release a new version about every month. Eg 2.0, 2.1, 2.2 ... 2.15. At this point we stop and work for eg 6 months on the 3.0 release. 2.X updates contain all kind of changes so we also broke some API's. A few on purpose, and a few more accidentally.

It is very easy to break BC see eg Semantic Versioning and Public Interfaces re our PHP API but also for our HTTP APIs etc. Basically the only way to not break BC is to not make any changes to anything that is somehow considered a public API.

An idea that we discussed was to not make any changes to any public APIs (basically almost the whole core, APIs defined in plugins, commands, etc) once we released Piwik 3.0. In Piwik 3.X we will only push security fixes, bugfixes, and some features that can be solved in new plugins or in existing plugins but without breaking anything. This means there will be still some patch and minor releases but maybe not as many as before or at least each release will contain less to no changes but only new features (features that can be developed in plugins) and bugfixes. This way each 3.X release should be quite stable and not break any API.

At the same time of releasing Piwik 3.0 we will create a branch for all the work on Piwik 4.X. Here we will make changes in core and public API's etc. We will also regularly rebase the Piwik 3.X branch onto Piwik 4.X. This means we will work on two different versions at the same time. The stable Piwik 3.X and the bleeding edge 4.X version containing simpler / better APIs for our platform. The 4.X branch should be quite stable as well but is only considered as beta from day one. At some point we will decide to release a Piwik 4.0 version, for example after 6 or 12 months. At this moment we will freeze the work on Piwik 4.X, release an RC and only fix bugs and security issues after this point. The RC cycle will be probably 2 or 3 months to give everyone some time to test plugins against new versions, to update existing Piwik and Piwik PRO plugins, and to fix bugs. Once we release Piwik 4.0 we will create a branch for 5.X.

This has some advantages:

• Stable 3.X version, with less regressions, hopefully no BC breaks, less annoying updates
• Plugin developers don't have to updates and test their plugins as often as they have to currently
• Users get a more reliable platform
• We won't have a phase where there are no updates for 5-10 months or longer like we will have between 2.15 and 3.0 as it will take us that long to work on Piwik 3.0. At any point we can decide to release a new Piwik 4.0 version and it will take max 2-3 months for the RC cycle
• We (developers) can use newer PHP versions earlier under circumstances. Instead of having to wait for 1 year after Piwik 3.0 release we will be able to work with newer PHP version immediately in the 4.X branch. Eg Piwik 4.0 might require PHP 5.5 or PHP 5.6. So we can make use of those features earlier
• Refactorings will be much easier and faster since we won't have to take care of keeping BC and can develop better API's directly. Eg we can just deprecate or remove API's in the 4.X branch. Often we can currently not develop as nice API's as we would like to as we have to find solutions that are backwards compatible as well.

There will be some "disadvantages"

• We cannot make all kind of changes to Piwik core etc in 3.X
• It takes more time to maintain 2 different branches, to rebase regularly, to switch between versions etc
• It will take longer until new API's or API changes are available

Some random thoughts:

• Users will be able to choose between
  • Stable Piwik (2.X) (while LTS version is supported)
  • Stable Piwik (3.X)
  • Beta/RC 3.X
  • Beta/RC 4.X
    • Covered in in Update settings, let user choose "Use the latest release" or "Use the Long Term Support release" #8549
• We will add a Piwik version selector to developer.piwik.org so users can choose between 2.X, 3.X and 4.X.
• We need to adjust the marketplace to be able to offer correct updates for correct Piwik version. Eg if someone is still using 2.X one would not get any updates currently. We will adjust the Marketplace so plugin developers can still provide updates for different versions.

[tsteur]

Another advantage by this method is that we could possibly develop/enable automatic updates for minor and patch updates

[tsteur]

Can we close that one or for how long do we leave such issues open?

[tsteur]

It's always possible to reopen at any point...

[mattab]

The solution laid out in the description above is exactly what we need to solve many of our problems with regards to unstable APIs! We can close the issue.

The next step to make this official and visible to users will be to add the version selector (LTS/Latest) in the App, discussed in #8549