We (probably) need Rakudo specs

[JJ]

Whatever is not in roast is not really specified. That leaves a big chunk of Rakudo functionality that does not have specification, sometimes is not tested, in some cases it's been used "in the wild", in most it's not because it's complicated to know what it really does (and how long it's going to behave that way).

I (along with some other people that have tried to find fast and efficient ways to work with Pod6) have clashed repeatedly with CompUnits, for instance. It looks like a very powerful feature, and would be nice to use it to pre-comp pods, or even re-use pods that have already been precomped. Our (and other's, including mainly @finanalyst's) attempt to use it have repeatedly bumped into misunderstandings of (mainly) the source, or sudden changes in behaviors that eventually impact generation of the documentation, or imply lots of changes all across the board. For the time being, Raku/Documentable#150 has opened a whole Pandora's box that seems to have no easy way out.

[JJ]

I am proposing the existence of a "rakudo/roast" repo along "raku/roast", if only for the purposes of freezing what we consider to be usable and what's not. I don't think "nothing that's not in roast should be in other place" because even if we don't intend internal classes and APIs for external consumption, it would help anyone working on Rakudo find their way there, and know what should be used and what not. It would also help to have a more solid ground for refactoring, should it be needed, and, in general, improve developer experience, either internal or external to Rakudo (by external, I mean mainly the people creating applications for production or the ecosystem).

[niner]

Sound to me like your problem is that only a small part of the module loading infrastructure is covered by roast. This prevents you from using on this infrastructure or at least from relying on it.

Wouldn't the simple solution be to just add any missing tests to roast? Creating pull requests with such tests sounds like a great way to ask "is this a supported API and am I using it correctly?".

FWIW the parts of the module loading API that are meant to be a public API are usually covered by roles, e.g. CompUnit::Repository, CompUnit::PrecompilationDependency, CompUnit::PrecompilationRepository, CompUnit::PrecompilationUnit, etc.

[MasterDuke17]

Or a more fleshed out https://github.com/rakudo/rakudo/tree/master/t?

[JJ]

Sound to me like your problem is that only a small part of the module loading infrastructure is covered by roast. This prevents you from using on this infrastructure or at least from relying on it.

Wouldn't the simple solution be to just add any missing tests to roast? Creating pull requests with such tests sounds like a great way to ask "is this a supported API and am I using it correctly?".

Well, if roast is the way to go, I'd be happy to at least try and do that.

FWIW the parts of the module loading API that are meant to be a public API are usually covered by roles, e.g. CompUnit::Repository, CompUnit::PrecompilationDependency, CompUnit::PrecompilationRepository, CompUnit::PrecompilationUnit, etc.

OK, but what about the rest? tests would help to, at least, know what's a "private API" (if there's such a thing)

[jnthn]

Whatever is not in roast is not really specified. That leaves a big chunk of Rakudo functionality that does not have specification, sometimes is not tested, in some cases it's been used "in the wild", in most it's not because it's complicated to know what it really does (and how long it's going to behave that way).

If something is complicated to use and we're not sure it's going to stay that way, that's an excellent reason for it not to be specified (as in, in roast), otherwise our hands our tied when it comes to making things better. On the other hand, it's hard to reach better designs without there being at least enough of a clue about how to use them that people can try, find the rough edges, etc. On the third hand, if people do that and have code depending on it, making improvements based on that input may be difficult even though it's wasn't really spec, because we don't really like breaking stuff in modules.

I've seen some language and library docs attach a "stability level" to each API, which conveys what expectations somebody considering using it should have about its longevity and reliability. For example, we might have:

• Unsupported (it's there today, it might not be tomorrow, if you use it you get to keep all the pieces, tell us if you actually need a supported way)
• Experimental (we're not convinced this is entirely right yet, it may yet change, use it cautiously, feedback welcome)
• Proposed specification (this has tests in roast for a future language release, thus we think it's about right)
• Specified (this has appeared in a language release)
• Deprecated (this was once specified behavior, it was a mistake, it will eventually go away)

In the rakuast branch, I have a bunch to tests under t/12-rakuast/, which I considered candidates for roast in the future. I guess today those would be at Experimental on the above scale (at least, if they weren't off in a branch). I don't really think having another repository to put these tests in would be an improvement (in fact, the opposite). But maybe we want to organize t/ in the Rakudo repository a bit better in order to reflect what is:

• Tests for experimental things that may yet make it to roast
• Tests of internal implementation details
• Performance tests to help us identify lost optimizations

And maybe some further categories.

[b2gills]

… But maybe we want to organize t/ in the Rakudo repository a bit better in order to reflect what is…

To be fair, Roast isn't that well organized (for Raku) either. It was originally organized based on the Synopses. Which were based on the Apocalypses. Which was based on chapters in the book Learning Programming Perl. Which was first written for Perl4, Which was really just the version of Perl3 that was stabile when Learning Programming Perl was printed.

I don't think that Roast really needs to be organized based on a book written for Perl3.

[pmichaud]

My historical recollection: The genesis for roast came from the Pugs project. After (re)-working tests from Pugs there were also efforts made to somewhat use the Synopses as an organizing framework, but it'd be wrong to say that the Synopses were the original organization principle. (Also, I recall that the Synopses were organized based on the camel book ("Programming Perl"), not "Learning Perl".) I'd say that roast was started in Pugs, then re-organized loosely based on the Synopses but there was also some resistance from various projects to keep from overly refactoring things too much in ways that might impact others. It took some time before roast received its own repository separate from any specific implementation, so synchronization among implementation efforts was something of a factor. Pm

…

On Mon, Jun 07, 2021 at 07:46:17PM -0700, Brad Gilbert wrote: > … But maybe we want to organize t/ in the Rakudo repository a bit better in order to reflect what is… To be fair, Roast isn't that well organized either. It was originally organized based on the Synopses. Which were based on the Apocalypses. Which was based on chapters in the book Learning Perl. Which was first written for Perl4, Which was really just the version of Perl3 that was stabile when Learning Perl was printed. I don't think that Roast really needs to be organized based on a book written for Perl3. -- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: #277 (comment)