[racket-dev] Adding the new plot library [was: Re: Plot?]

11 hours ago, Neil Toronto wrote:
> On 09/29/2011 12:28 PM, Eli Barzilay wrote:
> >
> > Because you wanted to have a completely compatible interface?
> > (Excluding pixels.)
> >
> > My point was that if you don't keep it (which I very strongly
> > prefer), then you don't have a compatible interface to plot
> > anyway, and changing the name from `plot' to `plot/compat' makes
> > more sense.
> 
> The pixels that make up the plots generated by the compatibility
> library are quite different. But I can't imagine that nicer plots
> will be anything but a pleasant surprise.

By "(Excluding pixels.)" I meant that the compatibility that I'm
talking about is *not* about them.  I definitely don't want to talk
about them.  (I should have added "in any way shape or form"...)


> The first is what happens when users run old code that uses the
> 'plot' library.
> 
>   - (Robby/Sam) The compatibility library is 'collects/plot' and the
>     new library is 'collects/rackplot' (or 'collects/omg-raph' or
>     whatever): their code just runs.
> 
>   - (Eli) The compatibility library is 'collects/plot/compat' and
>     the new library is 'collects/plot': some code will run with more
>     changes than just pixels ("semantic errors" in the plots), some
>     will give runtime errors, and most will give compile-time
>     errors.

Yes, except that the compatibility library (under any name) will not
be completely compatible, hence code will need to be adapted, and
therefore I view the change in the code from (require plot) to
(require plot/compat) as an acceptable one.


> The second interaction is what happens when new users look for
> "plot" in the manual.
> 
>   - (Robby/Sam): They get the old 'plot'. Clicking on it reveals a
>     big red deprecation warning, and a link to the new stuff. Of
>     course, that doesn't guarantee that they will *read* the
>     warning.

Very much so.  Specifically, if you look for a `plot' function and
click it, you get directly to its documentation, and won't see the
deprecated message at the top.  The obvious solution being adding it
in all functions, but even that my guess is that people will miss it.


> Observations: With Robby/Sam's idea, the apparent bait-and-switch,
> and needing two clicks to get to the right library, is also
> fail. And it lasts for years until we finally decide to rip out the
> compatibility library, and thus break more code.

+1 -- but that's nothing new for this case.  In general, compatibility
is a good thing for obvious reasons, but it also has a dark side that
we're already into: when things are "very compatible" up to including
the docs and not showing any warnings, then code will exist, and will
grow more code that uses the compatibility layers.

(There were some good examples that I finally cleaned up recently:
lots of "foo.ss" requires, uses of `@scheme' in scribble files, etc.
The main reason I cleaned it up is that I don't want to see these
things spread further, and given that code in the repository is often
used for templates, having those things in there mean that they will
linger on.)

And BTW, re "finally decide to rip out": it's questionable if such a
future exist.  There are some extremely ancient things that are still
in.  (Look in `syntax/zodiac' for a live demo.)


> To me, the ideal would be to name the compatibility library
> 'collects/plot', and then somehow keep it from showing up in
> searches.

Actually, that would be a good step towards proper deprecation: just
drop the documentation for the deprecated bindings.  I'd be in favor
of that.  (But somehow I think that won't be a popular vote.)


11 hours ago, Neil Toronto wrote:
> On 09/29/2011 12:27 PM, Sam Tobin-Hochstadt wrote:
> > You're referring to the code that implements `fit', right?
> >
> > Shouldn't we just keep that until someone does the same thing that
> > Neil has done for that code too?
> 
> Yes. I'll likely convert that one as well, but not right now. I've
> got quite a bit of experience with nonlinear function fitting, from
> another graduate program, a lifetime ago. (Or 3-4 years ago. or
> whatever.)

I still think that a poll is the best way to go.  It is unlikely that
the fit code is used, and wasting precious resources (your time) on
writing code that won't get used is IMO a bad investment.  (Yes,
"unlikely" is my opinion -- hence the poll suggestion.)


10 hours ago, Robby Findler wrote:
> On Thu, Sep 29, 2011 at 5:25 PM, Neil Toronto <neil.toronto at gmail.com> wrote:
> > Observations: With Robby/Sam's idea, the apparent bait-and-switch,
> > and needing two clicks to get to the right library, is also
> > fail. And it lasts for years until we finally decide to rip out
> > the compatibility library, and thus break more code.
> 
> No _more_ code, hopefully. And in the meantime we give people time
> to switch to the new thing.
> 
> Giving people no time (ie zero releases) in which to port their code
> is unwise.

BTW, to further clarify my opinion: if "meantime" above was a known
reasonable period, then I'd say something completely different.  (For
example, it could be `plot' and `plot/new', then `plot/compat' and
`plot'.)  But judging from similar cases in the past, this period is
some unknown N years, with a rough growth of 1 year per year.


> > To me, the ideal would be to name the compatibility library
> > 'collects/plot', and then somehow keep it from showing up in
> > searches.
> > [...]
> 
> I don't think that's possible.

Another potential path if the period was unknown: since we have a
mostly deterministic release cycle, the documentation for deprecated
bindings could be explict and have a note saying:

  This binding is for backward compatibility, and will disappear in
  [some date].

Then, one release before that date, the documentation can be modified
to have *only* that note, and then it would be removed.  (Possibly
adding more steps, like dropping the documentation completely, or
maybe adding some noisy stderr warning printout two releases before
the deletion, etc.)



9 hours ago, James Vega wrote:
> Eli Barzilay <eli at ...> writes:
> > The thing is that keeping things completely backward compatible
> > means keeping some C code (the fit thing), and that translates to
> > a real problem with linux distributions (see the Fedora point
> > earlier).  Not being completely backward compatible has the
> > advantage of moving at least the Fedora distribution faster (and I
> > won't be surprised if Debian/Ubuntu would have issues with this
> > too -- I'm surprised they didn't say anything about it so far).
> 
> I did -- http://bugs.racket-lang.org/query/?cmd=view&pr=10756. :)
> You convinced me that the status quo was good enough for now and
> that it'd eventually be replaced by scheme^Wracket.  Glad to see
> that's happening.

Actually, since then Matthew changed the rendering to go through
racket, so the zlib code is already gone.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!