I downloaded and installed version 1.3 (thankfully on a test system) and our working, production code is now broken. This makes it impossible to install the new version of Aspose.pdf on our client’s production server.
Specifically, you removed the “GetAt” method from the “Sections” class (and possibly other classes as well). We use the GetAt method to retrieve specific sections and modify them prior to writing the PDF file.
I realize the “Items” property provides an equivalent function, BUT we cannot upgrade to the new version of Aspose.pdf without changing PRODUCTION code. (Ideally we should be able to install the new version of your code without having to modify our code.)
PLEASE DO NOT MAKE INCOMPATIBLE API CHANGES WHEN RELEASING NEW VERSIONS.
(Remember the rules for modifying COM interaces – changes can add new stuff, but must never remove parameters or API calls.)
Dear Tony,
I can imagine how you’re disappointed when you tried to upgrade to the new release 1.3 and your existing code won’t compile. I believe this would be a perfect time to explain our upgrade strategy?
-
We try our best to keep existing public APIs unchanged or minimize the change to existing public APIs. Please keep in mind that this is our very primary upgrade strategy!
-
We change existing public APIs only if the change is unavoidable. For example, the change from GetAt to Indexer. [Steve]
(http://forums.aspose.com/User/UserProfile.aspx?UserName=stevew)suggested this change for Aspose.Excel, [Collection Indexer Suggestion](http://forums.aspose.com/ShowPost.aspx?PostID=532). As I believe indexer is better than GetAt, and, all Aspose products heavily make use of collection classes, we accepted this suggestion and all new release of Aspose products changed from GetAt to Indexer, including Aspose.Pdf. You may say, why not keep GetAt even though we have added Indexer? Although we considered it, we realized that it would result in confusion for all new customers, and most of our existing customers also. “Why do you offer 2 APIs for the same features?” As a basic rule, we try to keep public APIs as concise and necessary as possible, so we we decided to remove GetAt. -
For us, the best solution is to think and design public APIs as carefully and profoundly as possible, so we will not need to them later. If public APIs are unavoidably changed, we are very concerned because we know that existing customers must change their code; a very painful experience. This may cause them to rethink their decision to support Aspose! However, to keep Aspose’s products’ APIs the most competitive and innovative available, we need to explore all possibilities during analysis and design. As a result , we run the risk of changing existing public APIs later. It’s really painful for existing customers in the short term, however in the long term, their investment in Aspose is rewarded; they get the most concise, competitive and innovative APIs on the market.
Now, Tony, could you comment on our upgrade rules? We’re listening to you!
Ben:
I understand and support the move towards providing standard collection interfaces. I even agree that it is probably a better way to go. My issue is the sudden removal of a previously supported interface causing working code to stop working.
I agree that redundant and duplicate interfaces should be avoided unless it breaks existing code. If you plan to remove an interface, you need to give reasonable notice to your customers so that they can develop an appropriate upgrade and migration plan. This may mean supporting a redundant (or obsolete) interface for 1 or more versions before finally removing it.
I suggest looking at the Microsoft .NET framework documentation for some examples. In documentation for the “System.Xml.Xsl.XslTransform Class” , the members page lists the public property “XmlResolver”. The text for this member begins with the word “Obsolete” in red and identifies. Also if you examine the “Transform” method for this class, several of the alternate definitions of this method are marked obsolete.
I would recommend taking a simlar approach. Implement “GetAt” (possibly in terms of the new indexer interface). In the documentation, identify “GetAT” as osolete and scheduled to be removed in a future version (if possible specify which version). In the Release Notes include a section which specifically identifies what APIs have been removed from this versions and which APIs will be removed in a future version (again if possible identify the planned version and timeframe for that version).
Give your customers notice before removing an API to give them time to schedule in the changes to their code needed to adapt. I would recommend giving at least 6 months notice (12 would be better).
As it stands now, I cannot migrate to the new version of Aspose.pdf until I can schedule time to modify my exisiting code. What other API’s have been removed? (or changed in an incompatible fashion?)
Dear Tony,
Your suggestion is excellent and we accept it.
-
If we decide we need to change or remove an existing public API, we add a comment in the API Reference, such as: NOTE: This member is now obsolete. Please use Xyz for the same purpose, this reference will be removed in June 2004 (12 months after the posting of this note). Aspose apologizes for any inconvenience you may have experienced. Additionally, we will publish an obsolete API list at [New Release]
(http://www.aspose.com/Products/Aspose.Pdf/Intro/Newrelease.html)for each new release. Does this sound more approprate? -
For GetAt, we decided to recover it and then publish a hot fix 1.3.4.0 in this forum. I encourage you to download it and update your Aspose.Pdf.dll without changing your existing code.
Tony, thanks for all your contribution about the upgrading incompatiblility issue.
I strongly encourge you or any one else to feel free to talk to us as we’re completely customer driven and constantly redefining our products based on your feedback!
Dear Tony,
Thanks for your consideration.
Please see thread [Fix 1.3.4.0 Released – Incompatible GetAt Method Fixed](http://forums.aspose.com/ShowPost.aspx?PostID=835) and download the hot fix.