[Critisms] Parrot backward compatibility and docs

Fri Jun 18 16:58:12 UTC 2010

This I think is the best idea for this problem. My vote is for this.

Kartik Thakore

On 2010-06-18, at 2:34 AM, Christoph Otto <christoph at mksig.org> wrote:

> 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.
>
> Christoph
>
>
> [1] http://drupal.org/update/modules
> _______________________________________________
> http://lists.parrot.org/mailman/listinfo/parrot-dev