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?
Massive API changes
Moderator: General Moderators
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
- Christopher
- Site Administrator
- Posts: 13596
- Joined: Wed Aug 25, 2004 7:54 pm
- Location: New York, NY, US
Re: Massive API changes
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.Chris Corbyn wrote:We'd be talking about a small amount of code that people would need to change in reality.
(#10850)
Re: Massive API changes
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.
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
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.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?
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
- VirtuosiMedia
- Forum Contributor
- Posts: 133
- Joined: Thu Jun 12, 2008 6:16 pm
Re: Massive API changes
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
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.
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.
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
Re: Massive API changes
That's an idea I hadn't considered. At least that's more of a one-time check than a continuously used tool.arborint wrote: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.Chris Corbyn wrote:We'd be talking about a small amount of code that people would need to change in reality.
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.matthijs wrote:But if it's not an obligatory upgrade, it's not as bad if things change
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.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.
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 aboutVirtuosiMedia 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.
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
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.