@mattab opened this Issue on June 17th 2015 Owner

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 (#4796)
  • Piwik is an open platform that developers can trust,
  • term API is used to refer to many types of APIs (see #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 <a class='mention' href='https://github.com/deprecated'>@deprecated</a> 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 <a class='mention' href='https://github.com/deprecated'>@deprecated</a> code and therefore break BC.
    • we announce the details of code removed in the developer changelog #8127
    • ideally we also document to developers how they can convert their code to the new way
@mattab commented on August 11th 2015 Owner

We are proposing serious changes in our release cycle in order to not break BC in a major release cycle. Join in at #8547

@mattab commented on August 13th 2015 Owner

I need to create a new guide on developer.piwik.org and this can then be closed, because we have found a way to maintain backward compatibility in Piwik with our mix of LTS #8546 and new release cycle #8547

Powered by GitHub Issue Mirror