[Cuis] Fwd: Re: DIRECT version number

[Phil (list)]

On Sun, 2015-07-19 at 13:18 -0700, Ken.Dickey wrote:
> On Sun, 19 Jul 2015 11:20:19 -0300
> Juan Vuletich <juan at jvuletich.org> wrote:
> 
> > As a bottom line, let me repeat: This is too big for me to do it. 
> > Please, folks, start documenting the APIs you most care about.
> 
> Let me repeat, "you don't have to do it".
> 

I would agree that *Juan* doesn't need to do much of anything at this
stage, but not that it doesn't need to be done.  If and when it does get
done, if he disregards it, it will have been a futile exercise.  So I'd
appreciate it if we could come to an agreement as to whether or not I
should bother...

> I'd like to propose a simpler model based on the Smalltalk Way.
> 
> We take any stable revision, call it a version, give it a Baseline Version Number (could be just the development version number).  Each Baseline Release has a release document which describes major changes since the previous baseline.  This document is a light-weight description.
> 

While I agree that there should be periodic major releases, there are a
lot of things in motion between major releases that will either be
forgotten about or not considered major enough to call out in the major
version release notes.

The issue is what constitutes a major change?  If your code uses it it's
major, if mine uses it it's minor?  Coin toss?  Without a public API
what is considered major is either obvious (i.e. Morphic changes from
global to local coords or changing the File/Directory API so obviously
everything using them breaks) or arbitrary (sorry to hear that you
depended on that... but it wasn't major, now it's gone)  If the image
snapshot is considered the public API, then everything must be both
considered fair game to depend on and to change in the future which is
unmanageable.

Let's look at a few examples along the spectrum of what I'm talking
about:

1)  Things that hopefully we can all agree on as being obvious and
relatively stable.  We have a class called Morph.  Is it reasonable to
assume that that is going to be supported going forward?  How about the
#drawOn: method, is that going to be around for a while?  If Juan were
to randomly decide to change these, I'd expect there would be screaming
from anyone who has a significant amount of drawing code.

2) Multiple ways to do the same thing.  Morphs support stepping to do
animated drawing etc.  There are at least two different ways (one
seemingly obvious, one less so... both different from how things used to
work) currently to do stepping.  Should this be the case, or should we
just have one way we agree that everyone uses?  What is lost by giving
up the 2nd (and 3rd...) way(s)?  Currently, if Juan were to change *any*
of the approaches, it would probably break someones code.  Why not just
have one supported way for him to be concerned with?  (if you think this
doesn't happen, one of my pull requests in the last month was related to
this)

3) Questionable usage / edge cases.  Morph also has
#resumeAfterDrawError and #resumeAfterStepError.  Now taking a few
seconds to look at them (never used myself) they seem like Morphic
implementation details, but hey they're in the image and not even marked
private so I should feel free to make my code depend on them, right?
Conversely, Juan could look at them and decide 'no one would possibly
need these' and change/remove them at any time.

It seems to me that at least 1/2 of 2 and most use cases of 3 are
unnecessary issues waiting to, and eventually will, happen.  I
personally try to stick to depending on things that are in category 1 or
the obvious use case of 2.  But imagine my surprise when I discover as
the result of an update that something I was using was actually in
category 2 (less obvious, to me at least) or 3.  Sure, there's a lot of
gray area that isn't so clear cut, but shouldn't we at least try to
minimize the amount of breakage going forward when it can easily be
avoided or manage it via documentation/communication when it can't?

I'm not trying to restrict Juan in any way from making the changes he
thinks are important for Cuis.  His taste and direction have been
generally excellent and the reason I'm here!  If for example, he decides
that #drawOn: is no longer the way to do things or that even Morph
needed to go away, that's fine as long as what's going on gets
communicated.  However, a problem I think he faces right now is that he
doesn't know who's using / depending on what.

> Each baseline release starts a new fork.  The only changes to the particular baseline release are bug fixes.
> 
> Nice users test their packages and likewise fork a Package Release which matches a Baseline Release.  This fork also only changes with bug fixes, and only in synch with its particular baseline.  Baseline packages Feature the baseline release.
> 
> So we forge ahead as usual, once in a while we say "enough has changed that we should re-baseline", do a new Baseline Release, test and release our Package Releases, then again move on forward.
> 
> Anyone can now pick any baseline release, require any associated packages, and ship/demo without fear.
> 

What you are describing is an application development model, not a
platform development model.  It handles dependencies by ignoring them.
It really comes down to what is Cuis?  Is it:

1) a minimal Smalltalk that you play around with ideas / prototype
something in the short to intermediate term

2) a platform that you can take that idea you were playing around with,
and if it proves out, build something more substantial from for the
longer term

3) a completely experimental environment.  Anything can change at any
time.  Supporting 1 is doable but 2 is doubtful.

Right now, Cuis is great at 1 but seems like it should be able to handle
both 1 and 2 if a bit of stability gets added.  I don't think it's 3 at
all, but who knows, others may disagree.  If others look at it
differently, I'd love to know how you look at Cuis.

> Anyone with the time, energy, and interest can document baseline APIs to whatever level they feel comfortable.
> 
> Anyone can forge on ahead with the latest revision(s) with the usual "here be dragons, but also gold".
> 
> $0.02
> -KenD
> 
> _______________________________________________
> Cuis mailing list
> Cuis at jvuletich.org
> http://jvuletich.org/mailman/listinfo/cuis_jvuletich.org