[Critisms] Parrot backward compatibility and docs

[Andrew Whitworth]

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
>