New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Our work process when changing or removing a public API from the Piwik platform #8126

Open
mattab opened this Issue Jun 17, 2015 · 2 comments

Comments

Projects
None yet
1 participant
@mattab
Member

mattab commented Jun 17, 2015

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 @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 #8127
    • ideally we also document to developers how they can convert their code to the new way
@mattab

This comment has been minimized.

Show comment
Hide comment
@mattab

mattab Aug 11, 2015

Member

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

Member

mattab commented Aug 11, 2015

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

This comment has been minimized.

Show comment
Hide comment
@mattab

mattab Aug 13, 2015

Member

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

Member

mattab commented Aug 13, 2015

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

@mattab mattab self-assigned this Aug 13, 2015

@mattab mattab added c: Website matomo.org and removed RFC labels Aug 13, 2015

@mattab mattab modified the milestones: 3.0.0, 2.16.x Feb 8, 2016

@mattab mattab modified the milestones: 2.16.x (LTS), 3.0.0 Apr 1, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment