[Critisms] Parrot backward compatibility and docs

Christoph Otto christoph at mksig.org
Fri Jun 18 06:34:24 UTC 2010

On 06/17/2010 08:26 PM, Tyler Curtis wrote:
> On Thu, Jun 17, 2010 at 8:55 PM, Andrew Whitworth<wknight8111 at gmail.com>  wrote:
>> These are very good criticisms, and important for us to hear. By the
>> letter of the deprecation policy, a deprecation notice for the removed
>> ops was added in a supported release, but that notice was cryptic and
>> vague.
>> To sort of enumerate some conflicting problems we have:
>> 1) We need to be able to deprecate things. There are a lot of parts of
>> parrot (though the number is shrinking every month) that not good for
>> Parrot or it's users in general and need to be modified/removed. Out
>> with the old, in with the new, etc.
>> 2) Some issues aren't so pressing, but a few issues do need rapid
>> turnaround because people (especially Rakudo) end up waiting on
>> changes so they can make progress.
>> 3) Other people, such as yourself, like things to move a little bit
>> slower so you don't get the rug pulled out from under you.
>> The current prevailing wisdom is that your project should not track
>> SVN HEAD. Instead, you should pick a stable release and track that
>> until you are ready to upgrade. So, my immediate suggestion is that
>> you pick a good stable supported release (2.3, and eventually 2.6) to
>> base your work against. Obviously, if you're following the
>> bleeding-edge development repository you're going to have to deal with
>> the hassles associated with that.
>> The root issue is that we probably need to put more thought into our
>> deprecation notices. A good notice or linked ticket should, to my
>> mind, include:
>> 1) Detail about what exactly is changing or disappearing
>> 2) Detail about how to work around the changes, and where to go for
>> help if the given workarounds don't do it
>> 3) Information about the immediacy of the deprecation (important to do
>> quickly vs can take some time if necessary)
>> We should probably also have a place where wayward developers can find
>>   a listing of all recent deprecation notices, so when something does
>> change people don't have to search too hard to find the information
>> they need.
>> Thoughts?
>> --Andrew Whitworth
>> On Thu, Jun 17, 2010 at 9:22 PM, Kartik Thakore
>> <thakore.kartik at gmail.com>  wrote:
>>> Hello folks,
>>> So after taking a bit of a break from hacking I was back to try the
>>> brand spanking new Parrot. Most of all I wanted to see how it worked
>>> with my naive attempt at parrotSDL
>>> (http://github.com/kthakore/parrotSDL). parrotSDL is an attempt to bind
>>> the SDL (http://libsdl.org) library to parrot using NCI. It would bring
>>> simple multimedia (think games) functionality to parrot.
>>> When I first started parrotSDL a few months ago I was excited with the
>>> promise of learning a really cool new language and platform. I had often
>>> wondered why no one else has done this yet; or for that matter any other
>>> bindings. Surely it couldn't have been that hard. For me the SDL pir sources
>>> was already in the parrot trunk, just not working.
>>> In hindsight that should have been my hint or rather a warning bell. Anyway,
>>> I quickly fixed a bunch of minor bugs and release them against the latest
>>> parrot trunk. The last commit was on February 25, 2010. A mere 5 months
>>> ago. And now parrotSDL is completely unusable now. The cause which seems
>>> completely ridiculous (printerr, cmod, .. etc now expects a ( ) around the
>>> string after it) to me as an end user.
>>> I have no doubt that there must be a good reason for this change in
>>> syntax. But I digress, as an end user this is very disappointing. If a
>>> library written in parrot is obsolete in 5 months ... what is the
>>> point?
>>> Moreover there is hardly a notice of what has been deprecated, so now I
>>> have to walk through svn logs, or hunt in varying places. And most
>>> annoying of all the docs provided by parrot are either obsolete or just
>>> too short.
>>> For me right now I really would like to push forward with parrotSDL, but
>>> I feel as if parrot was made by core developers for core developers.
>>> Which is fine, but I really hope that was not the only point of this.
>>> Regards,
>>> Kartik Thakore
 > Something that could be helpful is a mailing list specifically for
 > deprecations. Every modification to DEPRECATED.pod could either
 > automatically or manually as a required part of the deprecation
 > process be posted to the list, and when the deprecated feature was
 > finally removed, a precise description of what has been removed, what
 > the new way of doing it is, and how to migrate existing code to use
 > the new way. So, someone developing on top of Parrot could subscribe
 > to the list, and whenever a deprecated feature is removed, they could
 > quickly use the included instructions in the message to the list to
 > check whether they need to update their code and how to do so. Of
 > course, the deprecation wiki page would also work, if it was kept
 > updated. Really, the most important thing would be to have some
 > handling of this aspect of the deprecation process, whatever that
 > handling may be, specified and followed.

I'd like to see more methodical way of dealing with compatibility breaks than 
a mailing list that users need to troll through.  Drupal does a good job of 
this with its module updating guides[1].  For each major version transition, 
they maintain a list of the API changes along with what's necessary to migrate 
code from one version to the next.  It's not perfect and the lists are huge, 
but it gives Drupal module writers a good idea of what's required to upgrade 
without all the nasty surprises that have been biting users of Parrot.  Unless 
we want strict ABI compatibility (and we don't), there will be an upgrade tax. 
  The next best option for Parrot users is to make that tax discoverable.

To that end, I propose that the current Deprecation wiki page be used as an 
index similar to Drupal's [1].  I also propose that we not consider any 
further deprecations eligible for trunk until there's a page on wiki 
describing the change and what Parrot users need to do to update their code. 
This would be in addition to the current deprecation policy, i.e. the change 
must be eligible *and* documented before it could be committed to trunk.

If this sounds like a good idea, I'm happy to get the wiki page organized, 
write some example pages and otherwise take the lead in making sure that this 
policy is documented and followed.

I want Parrot to be a great platform for HLL and library development, but this 
is an area where we've been falling short.


[1] http://drupal.org/update/modules

More information about the parrot-dev mailing list