Earlier, we had a discussion about the "syntax of the resource
expression". As a result of that, we decided to do a user UX study
to help us guide the decision.
We did get the results of the UX research just in time to make a
decision and do the required corrections for the 3.7.0. The meeting did
come to a decision on PUP-3117.
TL;DR: We decided to use the '*' wildcard instead of a what looks like
an attribute-name/meta-parameter, keep the local default, but restrict
the LHS expression to only a literal name, or a Type reference.
We based the decision on the following reasoning:
-------------------------------------------------
* None of the test pilots had any issues guessing / recognizing that an
asterisk as an attribute name implies "all" / "everything". All
understood it to be an unfolding operation, just as intended.
* The * => $hash syntax for unfolding can follow the current formatting
rule "align on arrow".
* "Googlability" was not an issue for any of the test pilots, they
either came up with other words for the concept / idea, or would go to
Puppet's (excellent) documentation and navigate to the relevant section
(resource expression).
* There were more test pilots that liked * => as their first choice than
the alternative 'attributes_hash'. This was however not the primary
reason we decided to select this option as it was both a close call, and
it was a qualitative study on a smaller number of test pilots.
We did not pick the runner up of using "attributes_hash" instead of the
asterisk based on the following reasoning:
-------------------------------------
* There is no indication that it is different from the other attributes,
nor that it is different from meta parameters. You would simply have to
know this (which you only can if you know this explicitly, or know all
the existing attribute names and meta parameters).
* There is nothing indicating that it does not hold the value; i.e. you
cannot later lookup the "attributes_hash" parameter.
* This means that users have to learn that there is the concept of meta
parameters that are available on all resources, but then also learn that
one of them is special.
We did not pick the other alternatives, because:
------------------------------------------------
* They were simply not well liked.
Did the testpilots find the new syntax useful?
----------------------------------------------
All test pilots found both the local defaults, and the ability to unfold
a hash to be useful in various situations in their existing modules that
they would like to do differently.
What can go on the Left Hand side (the type)?
---------------------------------------------
We did not test the allowed left hand side expressions because it was
much harder to construct tests for it, and we did not have that much
time. We had already arrived at the conclusion that it was not a good
thing to make it possible to use any expression in this position since
it opens up for confusing errors and user mistakes.
We decided to make it more strict. It is now specified to statically
validate that:
* it is a Qualified name e.g.
notify, file
* It is a Qualified reference e.g.
Notify, File
* It is an AccessExpression with a left expression being a
QualifiedReference e.g.
Resource[file], Resource[$x]
This allows advanced users the opportunity to still have the ability to
do a dynamic reference, while keeping regular users safe for
unintentional strange effects and getting error messages that require
knowledge that the left hand side can be any expression. The requirement
to use the Resource type, gives users reading-code a clue to what is
going on when reading someone else's advanced code.
(BTW: this advanced feature was already available in regular Puppet
since long time back, via the much unliked magic munging of the title
when it contains square brackets (behavior that will be removed)).
* The keyword 'class'
* At runtime the expression must evaluate to a CatalogEntry that is not
title specific i.e.
Notify[hi]
is not allowed.
We decided to keep the specified and implemented behavior where the set
of attribute names assigned to in a resource body must be unique as a
silent override otherwise masks errors. If the effect of a default is
wanted; that is what the local defaults is for. This way concepts are
clearly separated.
The language specification has been updated with this information.
And the above is now what is available in the just released 3.7 when
--parser future is on.
We will make the UX research report available but there is some work
that needs to take place to anonymize the responses.
- henrik
--
Visit my Blog "Puppet on the Edge"
http://puppet-on-the-edge.blogspot.se/
--
You received this message because you are subscribed to the Google Groups "Puppet
Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to puppet-dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/puppet-dev/luam8h%24jfa%241%40ger.gmane.org.
For more options, visit https://groups.google.com/d/optout.
