[yt-dev] backwards compatibility issues

[Matthew Turk]

Hi Elizabeth,

(I've snipped the previous conversation out of this.)

Thanks for your thoughtful email.  I'm pleased we have a community
large enough now that we have to think about these things, and also
pleased that the community is engaged enough that talking about them
isn't so bad.

On Wed, Jun 13, 2012 at 11:57 PM, Elizabeth Tasker
<tasker at astro1.sci.hokudai.ac.jp> wrote:
> Hi Matt,
>
> I'm springing off this email, but it's a separate point, so I gave it a new
> heading.
>
> Regarding breaking of backwards compatibility, I'm definitely +1 for
> avoiding it. That said, I also appreciate that changes are necessary to make
> yt more flexible to its ever expanding user base.
>
> A few of my scripts do use some of the lower functionality of yt (e.g.
> accessing an the parents of an individual cell etc) that I could see might
> change with an overhaul of structure, invisible to most cookbook-usage. I
> actually wouldn't issue more than a passing grumble, providing it was super
> clear how to fix my code for the new set-up. (So easy that I don't need to
> re-understand my long and (undoubtedly) poorly annotated script to do it).

I suppose this is an interesting point.  There are the obvious
high-level routines in yt -- plot collection stuff, data objects,
derived quantities -- and then the low-level access, which ti sounds
like you've been using.  Changing high-level functionality should be
done very carefully with ample warning.  (And I think that's where the
interpolation thing went awry, because it did change high-level
functionality, but where the volume rendering went okay because it's
low-level and preserving high-level access.)

What we don't have right now is a process for deprecating, and notifying.

>
> How about a spin-off page from the FAQ for "I updated and my code no longer
> works, WTH?". This could show an example of new call *and* the old call (so
> it's easy to see how to update your script). An example of what might be in
> there would be the call to EnzoSimulation which has undergone a number of
> revisions over the years.

This is a very good point.  In fact, having a deprecation page is
extremely useful, and something we haven't done a very good job of in
the past; mailing list messages have largely served this purpose.

This should be a mandated part of any release.  Do you think we need
to notify between releases?

>
> I don't think this would address Cameron's issue, which I think it about the
> change in the result rather than the usage, but it might be good for the
> above related problem.

We could also make it a part of it -- there could be two sections.
Changes in functionality and changes in interface.

-Matt

>
> Elizabeth
>
>