[Critisms] Parrot backward compatibility and docs

[Will Coleda]

On Thu, Jun 17, 2010 at 9: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
>> _______________________________________________
>> http://lists.parrot.org/mailman/listinfo/parrot-dev
>>
> _______________________________________________
> http://lists.parrot.org/mailman/listinfo/parrot-dev
>

>From DEPRECATED.pod -
--
If you find a feature you once used was removed after a deprecation
cycle, L<https://trac.parrot.org/parrot/wiki/Deprecation>. Otherwise
please open a documentation ticket via Trac[1].
--

There used to be directions in here to the developers to add to that
page, but I removed it, as this is supposed to be a user-facing
document.

When developers remove something that was deprecated, information on
what the replacement is should be documented on that wiki page, along
with the version the removal would have hit in. (So if you remove
something after 2.4, mention it as being removed in 2.5)

-- 
Will "Coke" Coleda