Page 1 of 1
Massive API changes
Posted: Fri Dec 19, 2008 10:54 pm
by Chris Corbyn
So you've got a project such as a library that's used by a lot of people and you decide that it's for the best to scrap huge parts of the interface and start-over with a new, more suitable interface. You make a full version leap as you do so (in order to make it clear it's not just the same as the old version).
Do you think it's in your best interests as a developer to provide compatability wrappers for the new API, despite the full version leap, or do you prefer to just let your end users update their code? If I was makign changes to live, stable version I'd be forced to @deprecate the old interface and wrap it in some way for a short while. But moving across major versions I'm not sure I should feel so pressured to do this.
I can see both sides to it. On the one hand I don't want to <span style='color:blue' title='I'm naughty, are you naughty?'>smurf</span> off my existing users by "breaking" their current code. But on the other hand I don't want to have to keep supporting a deprecated interface and so I think that by providing compat wrappers I'd be creating extra work for myself (support-wise, and code-maintenance wise).
We'd be talking about a small amount of code that people would need to change in reality.
Does anyone have any opinions to share on this topic?
Re: Massive API changes
Posted: Sat Dec 20, 2008 1:43 am
by Christopher
Chris Corbyn wrote:We'd be talking about a small amount of code that people would need to change in reality.
The goal seems to be how to ease the process of upgrading. Breaking out of your two choices, perhaps it might be better to provide a tool that would search PHP scripts and identify the places where the "small amount of code" is that needs to be changed.
Re: Massive API changes
Posted: Sat Dec 20, 2008 3:22 am
by matthijs
Hard to say. As a user I hate it when I have to upgrade and things break. But if it's not an obligatory upgrade, it's not as bad if things change. Then I can always keep using the old version, until I feel like doing the work to upgrade.
So my guess is: let the new version break the old API. Just make it clear that it changes.
Re: Massive API changes
Posted: Sat Dec 20, 2008 11:49 am
by alex.barylski
Do you think it's in your best interests as a developer to provide compatability wrappers for the new API, despite the full version leap, or do you prefer to just let your end users update their code?
I use Swift in a personal project I have been working on for a while. Honestly I believe (as I have done) it's the client developers responsibility to provide the wrapper, so I would prefer you change the interface and not waste time on wrappers to support deprecated interfaces.
All my Swift code is in a single Helper_Mailer class so any changes you make are easily applied/updated in my own code. I never use a third party library without providing some kind of facade or helper interface to actually interact with the library.
On the rare occassion that my code uses some specific part of an API, I do so knowing that if I change mailer's or whatever, that I will have to go back and modify that peice of code. It's easier for me to drop commentray notes reminding me of what needs to be done. As opposed to you having to maintain wrappers for backwards compatability.
I am of the mind set:
"If it's not broke, fix it anyway, otherwise it'll never improve"
Cheers,
Alex
Re: Massive API changes
Posted: Sat Dec 20, 2008 1:03 pm
by VirtuosiMedia
The MooTools project recently rolled out a new version that had a lot of API changes. They had a compatibility layer, which helped, but where they may have mis-stepped, I think, is that they didn't have a definitive list of API changes. I'd say make the changes, but just document everything as clearly and explicitly as you can.
Re: Massive API changes
Posted: Sat Dec 20, 2008 1:34 pm
by alex.barylski
Moo tools is a little different from Swift, if that is the project CC is refering to I don't really know, but I assumed.
A framework whose API changes will break an entire application, whereas a library or toolkit like Swift can easily be "wrapped" internally and removed from the concrete implementation of a project.
In those cases, like Zend or Mootools, etc...you would have little choice but to provide a compatability wrapper.
Re: Massive API changes
Posted: Sat Dec 20, 2008 9:13 pm
by Chris Corbyn
arborint wrote:Chris Corbyn wrote:We'd be talking about a small amount of code that people would need to change in reality.
The goal seems to be how to ease the process of upgrading. Breaking out of your two choices, perhaps it might be better to provide a tool that would search PHP scripts and identify the places where the "small amount of code" is that needs to be changed.
That's an idea I hadn't considered. At least that's more of a one-time check than a continuously used tool.
matthijs wrote:But if it's not an obligatory upgrade, it's not as bad if things change
It's certainly not obligatory, but strongly advised, especially if you're having issues with v3 since they'll probably have been resolved in v4.
PCSpectra wrote:I use Swift in a personal project I have been working on for a while. Honestly I believe (as I have done) it's the client developers responsibility to provide the wrapper, so I would prefer you change the interface and not waste time on wrappers to support deprecated interfaces.
While I also wrap any third party code I use "just in case", I do feel a certain amount of responsibility to make the transition as clean as possible. I know the majority of users will not have written wrappers, but I also know the majority of users will not have Swift-specific code littered throughout their app.
VirtuosiMedia wrote:The MooTools project recently rolled out a new version that had a lot of API changes. They had a compatibility layer, which helped, but where they may have mis-stepped, I think, is that they didn't have a definitive list of API changes. I'd say make the changes, but just document everything as clearly and explicitly as you can.
I tend to separate my project from something along the lines of MooTools. MooTools is a framework and it's more than likely it will be tightly integrated with the app it's supporting. Swift on the other hand (that's what we're talking about

) is likely to be kept to isolated areas of an app. If I knew the code was so tightly integrated into an application I'd be forced to:
a) Roll my planned changes out over a long period of time so that people aren't overwhelmed with breaking changes
b) Provide compatibility wrappers for each of those small changes for at least a short while
However, I had planned exactly what you describe. A list of common tasks in version 3, along with the new way of doing it in v4. This would be a clear section of the documentation devoted to migrating from version 3 to version 4.
I was also planning to include more "general" topics in the documentation, such as encouraging users to writer wrapper classes for 3rd party code, including my own code.
Re: Massive API changes
Posted: Sun Dec 21, 2008 12:47 am
by josh
I agree with matthijs, they don't have to upgrade, if there's some important feature or security fix couldn't you just add it to both versions easier than writing wrappers around deprecated code? I'd never waste my time doing that unless I had a really good reason, time is much better spent creating new stuff, not maintaining old stuff. All the compatibility wrapper does is enables procrastination on the user's part. The only reason I'd bother writing all that machinery [that is going to be deprecated as soon as its written] is if I was a commercial software vendor, where I had direct compensation for the time investment.