Massive API changes

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Massive API changes

Post 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?
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Massive API changes

Post 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.
(#10850)
matthijs
DevNet Master
Posts: 3360
Joined: Thu Oct 06, 2005 3:57 pm

Re: Massive API changes

Post 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.
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: Massive API changes

Post 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
User avatar
VirtuosiMedia
Forum Contributor
Posts: 133
Joined: Thu Jun 12, 2008 6:16 pm

Re: Massive API changes

Post 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.
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: Massive API changes

Post 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.
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Re: Massive API changes

Post 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.
josh
DevNet Master
Posts: 4872
Joined: Wed Feb 11, 2004 3:23 pm
Location: Palm beach, Florida

Re: Massive API changes

Post 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.
Post Reply