While I was at Adobe MAX the other week, Adobe released Adobe AIR Beta 2. That sounds like great news, unless you happened to have written an application using Adobe AIR Beta 1.
See…Adobe completely laid dynamite to the AJAX security model between AIR Beta 1 and AIR Beta 2. While I can respect wanting to get the security model right, that seems like the kind of thing you want to be getting right early. Making major changes to fix the security model during the Beta stage doesn’t give you that warm and fuzzy feeling. Additionally, it’s irritating when you have to rewrite whole portions of your application to cope with this fresh security model.
Not content with making non-backwards compatible changes to the security model, Adobe took it a step further by making non-compatible changes to the ActionScript library as well. I had to discover this one the hard way. Air Mail uses File.applicationStorageDirectory to drop session files into user-specific application directories. In order to find the path to such a directory, Air Mail called the File.resolve() method. After upgrading to the latest Flex SDK Beta (that goes with the latest AIR Beta), my app stopped compiling saying there was no such method.
I returned to the documentation for File.resolve(), saw that the method was clearly present and marked “public” and proceeded to: a) scratch my head, b) mutter obscenities, c) call Miss Cleo or d) all of the above. This went on for a while.
Through some miracle, I managed to invoke a web search that pointed me to the real answer…File.resolvePath(). But…that’s odd. If I check the list of methods available on the File object, there’s no File.resolve(). What gives? On closer inspection, enlightenment strikes me like an anvil:
File.resolve(): http://livedocs.adobe.com/labs/flex/3/langref/flash/filesystem/File.html#resolve()
File.resolvePath(): http://livedocs.adobe.com/labs/flex3/langref/flash/filesystem/File.html#resolvePath()
Did you catch it? The ever so subtle “haha, you’re fucked” in the URL? No? Here…let me get out my magnifying glass:
File.resolve(): labs/flex/3
File.resolvePath(): labs/flex3
Evidently, when Beta 2 was released they published the documentation to a different, yet very similar URL. Since I had the language reference bookmarked…I was still visiting the “old” language reference. Also…when they went from Beta 1 to Beta 2 they renamed File.resolve() to File.resolvePath(). While it’s nice that Adobe wanted to make the method name more specific, I’m lost as to why they would want to change a method name right in the middle of the Beta program. Seems like a pretty Alpha move to me.
Adobe…get your shit together. When you release public APIs…they’re out. You don’t get to push the magic “recall” button anytime you like with a public API, not even during your Beta period. Not when you’re encouraging companies to build products with your software. When you release HTML documentation, expect it to be bookmarked. Either clearly label the old documentation as being “Beta 1 Only” or take it down. Don’t leave it under a URL that looks almost indistinguishable from the new documentation.
It’s … a … beta.
Yes, if the Beta 1 documentation is indistinguishable as such, that’s a legitimate issue, but you HAVE to expect changes between betas. That’s why they’re beta, and not “gold masters”.
Sorry, but I don’t have a lot of anger for Adobe here.
“Either clearly label the old documentation as being “Beta 1 Only” or take it down. ”
Yes!
How hard would it be to add a note to the top of every page?
And is it really that bad to have one method alias to another, like String.length() and String.size() in Ruby?
Derek, there’s a difference between “changes” and “you have to rewrite your app to make it work”. The change from resolve() to resolvePath() was annoying and amplified by the confusion created by the documentation. But entirely redoing the whole security model so virtually any AJAX application was going to require a large refactoring and rewriting…that’s not the kind of change you make once you’ve reached the Beta stage.
Ryan–
Welcome to web^H^H^Hsoftware development, where documentation is the last thing to get shipped. Let me tell you a little story about Netscape Communicator 4.0 beta 1, when the html tag (and supporting Javascript to manipulate layers) was added. The dev shop I was working for at the time was about to release one of the first commercial websites that made use of the layer tag, and the night before the site launch, beta 5 comes out and changes all the Javascript for moving layers around. Needless to say, the documentation didn’t change, and it took a phone call to the Netscape Javascript team (luckily, our shop had a contact there) to find out what code to change.
Moral of the story– don’t write applications for beta platforms. You will get burned, repeatedly.
Ryan,
I’m sorry to hear about the snags you hit when migrating to Beta 2. Your blog posting has been forwarded around to some of our internal teams and we know we can do better.
I’d like to follow-up with you to get your thoughts and invite you into our prerelease program. I’d appreciate if you could send me an email.
Thanks,
- Rob
Rob Christensen
Product Manager, Adobe AIR