[tap-l] User Supplied YAML Diagnostic Keys: Descriptive Version

[Michael G Schwern]

chromatic wrote:
> On Thursday 17 April 2008 16:17:48 Michael G Schwern wrote:
> 
>> chromatic wrote:
> 
>>>> We'd like folks to be able to add their own keys as they need without
>>>> first wondering whether it might be useful for others or worrying if we
>>>> might add a key of the same name, but different functionality, later. 
>>>> Thus the separation of local from official keys.
>>> This part I think will not work.  You can't pave the cow paths if you
>>> never see the pasture, and you can't not break the DarkPAN because the
>>> only way to know if the DarkPAN even exists is to see if light bends in
>>> its vicinity.
>> I don't understand, what will we break on the DarkPAN?  The whole point of
>> separating user from official keys is so we don't break the DarkPAN.
> 
> I've never thought there was an upgrade problem, but everyone else keeps 
> saying that there's an upgrade problem and that there absolutely must be a 
> separation between TAP keys and everything else because there's an upgrade 
> problem and we don't want to break the DarkPAN.
> 
> If we agree that that's not actually the real problem, good.

I think I get it now, but I want to take it from the top anyway.

We don't want a new, official TAP key to clash with something being used in 
the wild.  Why?

We're working around the same issue Perl 5 is having adding new keywords.  In 
Perl 5, since keywords and user-defined subroutines share the same space, we 
can't add a new keyword without risking clashing with a user-defined 
subroutine and giving it new meaning.  Thus the "use feature" shame.  By 
reserving all the lower case keys for official TAP keys and leaving everything 
else for users, TAP is free to add new keys.

The issue of name collisions is only an issue between official TAP keys and 
user-defined keys.  Collisions between user-defined keys is actually 
beneficial.  Lemme 'splain.

Let's pretend that we make everyone prefix their user keys to avoid collision. 
   Test::Stuff's "time" key might be "Test.Stuff-time" and Test::Thing's 
"time" key might be "Test.Thing-time".  They mean slightly different things, 
maybe one is in Unix time and one is an ISO datetime, but they serve the same 
purpose.  With the prefix, they can go on being slightly different.  This is 
not what we want.

We want convergence.  If user defined keys are to have meaning for more than 
just the user or group that defined them, they must converge on a common 
meaning.  User key collisions encourage that.  Users and test producer authors 
can spot the collision and work it out.  Lists of common keys and meanings can 
be published.  TAP displayers can make use of this and start to do things with 
common, user defined keys.

As the wide-spread utility of a key becomes apparent, they can be lower cased 
and made official.

It's much like tagging, with most of the chaotic problems and benefits, except 
that there will be a growing set of well-defined, official keys to provide 
some stability.

However, if collision is your main concern and what you really want is unique 
keys, you're free to prefix yours.


Prefixing is undesirable for other reasons...

Human readability of the raw diagnostics is important.  If you prefix every 
key it makes all the keys output by a given producer look the same.  This 
emphasizes who output the key and deemphasizes the key itself.  The important 
thing the reader of the diagnostics wants to know is why their test failed, 
not what output the diagnostics.

It's also annoying to write.  Though that's not nearly as important as 
diagnostics should usually be generated, not hand-written, for each test.

Also, we'd have to define what a prefix should look like to avoid collisions 
amongst prefixes.  Perl namespaces would seem obvious, but this is the Test 
Anything Protocol, and other languages have their own ideas about namespaces 
and might collide.  So now it's "Perl.Test.Stuff-time" or maybe by author 
instead but what if two authors have the same name?  The issue of avoiding 
conflicts amongst user keys continues and I'd rather just avoid it entirely.

With readability problems, specification complications and inhibiting 
convergence, prefixing adds more problems than it solves.


-- 
29. The Irish MPs are not after “Me frosted lucky charms”.
     -- The 213 Things Skippy Is No Longer Allowed To Do In The U.S. Army
            http://skippyslist.com/list/