6

From what I understood from the official documentation classes, interfaces, methods or constants annotated with @api are going to be backwards compatible and will be announced as @deprecated before being removed.

We promise to be backward compatible for classes and methods annotated with @api within MINOR and PATCH updates to our components. As changes are introduced, we will annotate methods with @deprecated. The methods will be removed only with the next MAJOR component version. MAJOR changes will be scheduled no more than once per year; likely during the holiday season when site changes are unlikely.

How should I handle this for my own interfaces?
Let's say I'm building a proper extension that I distribute and I have a Data API interface similar to this one in the code.
But at one point I decide to improve (or fix) something in my extension.
How should I handle these 3 cases?

  • I need to add some methods to the interface. I assume I can simply add them because the old methods still exist. But what If someone is using my extension and is using his own implementation of my interface?
  • I need to remove some method.. I could follow the same guidelines as the core team does and mark it first as @deprecated then remove it in a future release. But not sure about this since I don't release major versions once a year because I'm not consistent.
  • I need to remove the interface completely - Could this mean I made a false promise and my new upgraded extension should a totally different extension?
5

Actually the way we wrote our backwards compatibility policy was centered on that promise for client users of that interface not implementors. During our market research we heard from a # of community members that majority will be using plugins on interfaces to customize behavior and would likely avoid creating an implementation of an interface* ( exceptions being shipping, payments and search adapters where it makes more sense to be an implementor of the interface(s)).

Having said that internally we're doing as much as possible to limit disruptions; communicate ahead of time future disruptions/etc.

Some suggestions to minimize disruptions (based on our market research and what we're doing internally):

  • Q4 is least disruptive time to make wide spread 'breaking change'; if communicate ahead of time to the community/ecosystem ( 3 months ahead if possible ). This is a good time period for sweeping changes/breaking changes
  • Try using extensible objects rather then adding methods; this isn't disruptive to an implementor of the interface
  • If you've created an interface that's more likely to be implemented by others; try to keep it as stable as possible/at most change 1 per year with lots of warning ( cough alternatively introduce new interfaces using our declared function syntax that we're introducing in 2.1 to add new functionality; basically that's how we support global synonyms in 2.1 for MySQL & Elastic but not for Solr adapters. We'll use that pattern go forward where it makes sense ).
  • Communicate, Communicate, Communicate :)
1

I'm just going to give my opinion, I don't pretend to have the answers to your questions:

I need to add some methods to the interface.

As you said, I reckon you can simply add them. If someone is using his own implementation of your interface, he/she probably extended your interface to implement his own. Apart if he/she used the exact same method name, that should be alright.

I need to remove some method

Well I learnt as a general development good practice, one should never remove code from a software (except for comments). So Magento is going away from this as they say they will remove deprecated code in future release. To me, marking it as @deprecated is definitely the way to go but I disagree with the code removal.

I need to remove the interface completely

Could this mean I made a false promise and my new upgraded extension should a totally different extension?

In that case you're a liar and I will never get your extensions ever again!!!! ^^ No to me that is a super particular case and in theory it should never happen. The only case that I can imagine is that you are forced to remove it (for copyright issues for instance) and if that's the case, you're already in trouble anyway.

1

How should I handle this for my own interfaces?

You really have two options when releasing updates. You either care about how other people interact with your code or you don't. If you don't you would just release as you see fit. If you do it's all about how you communicate changes to the code to the users.

Generally you want to keep a change log. Semantic Versioning can help in quickly communicating what type of changes are included in the new version. For me the easiest to remember Semantic Versioning is that I need to increase the numbers like this Breaking.Feature.Fix (instead of Major.Minor.Fix)

I need to add some methods to the interface. I assume I can simply add them because the old methods still exist. But what If someone is using my extension and is using his own implementation of my interface?

I would consider this a breaking change - hence a major version update if using Semantic Versioning.

I need to remove some method.. I could follow the same guidelines as the core team does and mark it first as @deprecated then remove it in a future release. But not sure about this since I don't release major versions once a year because I'm not consistent.

Giving people a heads up with an @deprecated notice is considerate. It doesn't matter how often you release.

I need to remove the interface completely - Could this mean I made a false promise and my new upgraded extension should a totally different extension?

No, again just make sure you communicate this breaking change appropriately.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.