[Squeakfoundation]RE: Your stewardship(s)

[goran.hultgren at bluefish.se]

Hi!

(do I need to cc Hannes, Brent, Doug? Whatever)

"Andreas Raab" <andreas.raab at gmx.de> wrote:
> Göran,
> 
> > > With SM, we need a more declarative style that tells both, 
> > > clients and framework developers which methods can be relied
> > > upon and which can't.
> > > Without this, maintaining a package simply becomes a nightmare.
> > 
> > Are you sure? I mean, don't you think a little bit of 
> > documentation on a package might suffice? So that it is
> > obvious what classes/messages are meant to be used from
> > outside? And if we combine this with a more unit
> > test centric model perhaps it would be enough.
> 
> Honestly, I doubt it. The working style doesn't go that way. If you are a
> user of some package you need to read the documentation first. That's fine
> as far as it goes. But then you start screwing around and see that "perfect
> method" which solves your problem immediately. And so you use it. There's
> nothing in the _code_ that tells you "don't use me, I am private to that
> package and using me means you're doomed to fail a couple of releases down
> the road". The same on the other end. If you're a package developer you have
> to constantly go to a different place and update your documentation. And
> naturally, you will forget to do this because it's awkward. If you want to
> solve this problem by documentation then this documentation must be
> intrinsically linked to the code involved. And once you do that it _is_
> essentially a more declarative style of programming - even if you would put
> it into comments (which I wouldn't).

Yes, I buy this. At least in principle. I am not certain this is how it
would play out because I tend to think that people do try to stay within
the "public API" given enough info what that is. And I mean class
comments, method categories and method comments - not external docs.
Personally I think those *should* be there - it is IMHO your *darn* duty
as a programmer to keep those updated and in shape.

But anyway, I still think you have a valid point - a little idea is
further below.

> Also, the big issue with "all remote senders" which you were proposing is
> not the fact that you can find those senders. Again, that's fine but the
> problem is you can't _fix_ them. And that means you have to rely on the

No true, but you can *find* them. And that may be enough to catch a lot.
If I thus find out that package X uses a private method (or is highly
likely to given the rarity of the method name) then I can mail him/her
about it etc.

It would also put a bit of pressure on people to stay within the APIs.

> implementors of that other package that they only use what you have declared
> to be the "public API" which brings us back to the above issue. At this
> point you could in fact say that everyone who uses any "private messages" to
> that package be screwed but you can carefully phase out obsolete public
> messages without the fear to break anything that has been written according
> to your design (e.g., using public messages).

Yes, but one little point here: soon (gah, need to hack on that....) we
will have package releases and dependencies between them. Without those
things will definitely turn hairy.

> The key issue is that both implementors and clients of a framework need to
> be able to tell what interfaces exactly they can rely on. If you can't tell
> this, handling large decentralized packages _will_ be a nightmare before
> long. We cannot expect people to lock-step in the development if those
> packages are individually developed, we cannot rely on having that "large
> synchronized base" (e.g., monolithic image). If we want to allow evolution
> then we must find a model of determining what we promise to support "long
> term" (e.g., across minor versions) and what we don't.

Sounds fair to me. Two ideas, the first one I have described earlier and
it is the compatibility level rating that developers should give their
new releases. I thougt out a six level rating earlier, but don't have
them handy now. The point is that you can (using SM categories) find out
if the new release breaks the API or not, only includes bug fixes etc.
This will make it much easier to maintain packages *AND* for the user to
take "acceptable chances" by using Comanche 1.01 instead of Comanche 1.0
even though Seaside depends on Comanche 1.0. Since the Comanche
maintainer classified 1.01 to be only bug fixes I can as a user "take a
chance" that it will work.

The other more important idea is that we could perhaps use unit tests as
a way to describe the public API. Rather neat actually! If we mark some
tests as the "public" tests for example then perhaps we somehow can
extract the allowed public protocol from those tests. Or something
similar. What do you think?

I mean - if we are serious about maintaing "public APIs" then we really
should have tests for them anyway and not just a list of methods, right?

regards, Göran