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
@deprecatedthen 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?