Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Maintaining backwards compatibility for our public APIs in Piwik & our release cycles #8547
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:
There will be some "disadvantages"
Some random thoughts:
referenced this issue
Aug 11, 2015
referenced this issue
Aug 13, 2015
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