In this issue we describe our process when we want to change or remove a public API. The goal is to put this knowledge in a guide on developer.piwik.org so it is easy to spread this knowledge to all team members including new ones in the future.

Our Backwards Compatibility Promise

All popular software platforms have a process to ensure Backward Compatibility (BC) is kept between Minor and Patch releases (see Semantic Versioning 2.0.0). when BC is kept, it means users can be confident to upgrade to a newer version (Minor or Patch release) that their platform will still work (including any installed third party plugins.). For example Symfony have a very advanced BC guide: Our Backwards Compatibility Promise .

Process to keep BC, and deprecate APIs

Here are the notes how our current process work:

Given:

• Piwik uses Semver (Piwik will now use Semantic Versioning 2.0.0 #4796)
• Piwik is an open platform that developers can trust,
• term API is used to refer to many types of APIs (see The Matomo platform, our public APIs, and maintaining backward compatibility #8125 for details),

Then:

• We do not break BC in a Minor or Patch release
  • we may break BC in a Minor or Patch release, in rare cases only when BC break is necessary for Security reasons or for Performance reasons
• When we need to change an API, or remove an API, before removing or changing the API, we deprecate it:
  • this can usually be done by adding @deprecated tag in the API, event name, etc.
  • we announce the deprecation in the Developer Changelog at least 3-6 months early
• As defined in SemVer, Major releases are our only chance to remove our deprecated code.
  • When we release a Major version (eg. Piwik 3.0.0) then we are will remove all @deprecated code and therefore break BC.
  • we announce the details of code removed in the developer changelog Developer Changelog and documenting changes in the Matomo Platform #8127
  • ideally we also document to developers how they can convert their code to the new way