[Cuis] Canonical test cases?

[Phil (list)]

My code migration to Cuis 4.2 has gone from a saga to an ordeal... lots
of breakage.  As I've been going through and fixing things I am thinking
that I'm possibly going from doing some things in a broken way in
Squeak/earlier Cuis to a broken way in current Cuis simply because I
don't know what the 'correct' way is.

One example is related to compression: there aren't any canonical
examples of how to compress/decompress files/streams so I poke around
the classes until I get to something that works for me right now having
no idea if what I come up with will still work a few versions from now.
Another example is package loading: I've been calling CodePackageFile
installFileStream:packageName:fullName: but that no longer appears to be
the correct entry point if I want dependency checking.  While I
understand that things are subject to change, would it make sense to
have some documented, fixed entry points that would attempt to make the
most sane choices by default going forward?

My thought was why not use test cases to help document the preferred
(and therefore, longer term supported) way of doing things.  They could
be put in Tests-Examples or something similar and could serve double
duty in the sense that they would not only help point people in the
right direction on how to use a given class, but would also serve as a
warning/reminder to anyone wanting to make changes that these are the
core calls that need to be maintained from a code compatibility
standpoint or otherwise need to be called out when compatibility needs
to be broken.  I imagine this would be a fairly small subset of
classes/methods and not try to anticipate all the edge cases, just deal
with the most common ones.

Does what I'm suggesting make sense / seem worthwhile?