[Cuis] Canonical test cases?

[Phil (list)]

Hi Hannes,

On Sun, 2015-02-22 at 08:08 +0000, H. Hirzel wrote:
> Hi Phil and Wolfgang
> 
> Test cases mentioned by Phil are
> 
> T1. canonical examples of how to compress/decompress files/streams
> 
> T2. package loading. Phil writes "I've been calling CodePackageFile
> installFileStream:packageName:fullName: but that no longer appears to be
> the correct entry point if I want dependency checking"
> 
> Are there more?
> 

Definitely.  But rather than adding more details right now, I was
hoping to stay on the larger question of if trying to get to a
documented, stable set of APIs makes sense and if so how (where
possible... I understand there are areas that are still works in
progress)

> There is as well a workspace called 'useful expressions' which might
> be used to add a few of these test cases.
> 
> And updates to these files
> 
> https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/tree/master/Documentation
> (just fork the Cuis repo, update the md file and issue a pull request)
> 
> You may as well add an issue
> https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/issues
> 
> like I just did for T1 and T2
> https://github.com/Cuis-Smalltalk/Cuis-Smalltalk-Dev/issues/39
> 

I thought about that and the documentation is excellent general
primer/tutorial material.  However, I think we'd want to keep that short and
sweet both to encourage people to actually read it as well as minimizing
the risk of 'documentation drift' where the docs no longer match the
reality of the code (or am I the only one who's ever seen that :-)

The advantages of doing the API documentation in test cases would be
that it both ensures that the example code works and that it keeps
working. Anyone making a change, provided they re-run the tests, will
know immediately if they've broken anything and if it is in one of the
'black box' tests that it should be subject to a bit more consideration
(or at least communicating what's changing) since it will likely break
code if it needs to change.

Pull requests are definitely the way to handle whatever, if anything,
gets decided as it's not something that would be reasonable to ask Juan
to do himself.  However, he would need to review said test cases to
validate that, in fact, they are correct in terms of where he sees
things going. (i.e. I can easily produce some test cases for the compression
package but, due to it involving a bit of guesswork on my end, they may
not in fact be canonical examples)

(P.S. thanks for the SQLite package... I'm using it quite a bit
recently)