OpenAPI evolution methodology discussion

Let's start with the usual kudos for a great product and if my continuing participation and plugin development for your product is not stronger than my words I do not know how to tell you how I appreciate what you do to make our life easier.

However, and this is the start of my little rant... with the inexistence of proper documentation to support the openapi I believe you need to use standard mechanism to guide us plugin developer in upgrading to new revs.
Please maintain old api as much as you can and USE DEPRECATION! Several times in the past things could have been handled a lot smoother by just deprecating apis instead of changing them. You might need to build some backward compatible refactoring options (like http://www.intellij.net/tracker/idea/viewSCR?publicId=5195) but everybody would benefit.

813 is a great example:

1)fileStatusChanged renamed to refreshFileStatus.
(Note that I think the new name convey a lot better the intent of that method)


2) The new AbstractVcs api.
AbstractVcsCapabilities is no longer used. However it wasn't removed (oversight?). Now we get to implement a few XXXProvider instead of directly implementing the moveXXX and renameXXX methods in AbstractVcs.
The danger with this is (I fell for it in the ClearCasePlugin 1.20) the new API format doesn't help me detect the change. It silently go through compilation but the resulting behavior of the plugin is completely different. No more support for move/rename.
Think about your users. Make the old interface calls the new one or in this instance remove the Capabilities class and/or make the old moveXXX/renameXXX private.

Make your code self documented and backward compatible (or at least have fail-fast upgrade path to guide developer though the upgrade).

Thanks

One of your biggest supporter.

3 comments

I agree. Please, never remove methods (at least immediately) and use deprecation. It's probably something you don't care about until you encounter it and face the unpleasant options. After that you understand why Sun never (?) removed a single feature released in the public Java API (even if it's deprecated for a long time). It immediately breaks working clients written for the old version of the API. One should never remove a published feature unless you can be sure that a) there are no clients of that old version or at least b) there are few clients, majority of them upgraded long time ago, and there's a reasonable, good and tested upgrade path.

BTW, here's another case: http://www.intellij.net/tracker/idea/viewSCR?publicId=12132 (thanks again for fixing it!)

Why is it bad to remove a published feature? Even if we ignore the fact that old clients won't work with the new build/version, there's another possibility. You can write code that's targeted for several versions. For example, Ariadna and Aurora, or it could be even (of course it's less important) x01, x02 and x03 (say one user uses x02 because feature Y is broken in x03). And when you're in a situation when can't have code that works for both versions, it means that you're have to have 2 builds, 2 binaries, more classes and packages (to filter them out), etc or to use reflection, more classes again (to avoid multiple ugly "if buildNumber < 800"; version specific factories, classes). Either way it means much more code.

See also "Public versus Published Interfaces" ( http://www.martinfowler.com/ieeeSoftware/published.pdf ).


Timur

0

Please sign in to leave a comment.