On Wednesday, June 19, 2013 5:03:41 PM UTC+2, jcbollinger wrote: On Tuesday, June 18, 2013 1:19:32 PM UTC-5, Alessandro Franceschi wrote:
Some personal notes among the lines...
On Tuesday, June 18, 2013 6:35:18 PM UTC+2, Ken Barber wrote:
Although I agree that to be reusable, modules need to provide certain types
of levers, knobs, and switches, as appropriate for their scopes, I think the
case is weak for those controls needing to be called by the same
best, naming conventions for such things might improve ease of (re)use for
some people, but the key factor for reusability is not the names of the
controls so much as their presence in the first place.
Well on this I definitively do not agree :-)
For me a module is reusable when:
1- It supports many different OS (this is somehow implicit and does not
involve naming conventions)
2- It leaves to the user freedom on how to populate and customize the
provided configuration files ( I think this is the main point for most
3- It allows the user to manage some behaviours of the module (has a
service to be restarted after a file change? Do I want to manage a service
status (at runtime or boot)
4- In (somehow extreme) cases it allows the user to customize names of
package/services, paths of files and so on
5- It allows seamless addition of custom resources, not managed by the
module but related to it
6- It allows the user to decide where to place his data (also this is out
of naming convention scope)
Given these points, I think that some of the parameters names proposed in
the draft actually DO inherently enhance a module reusability:
For point 2: source, template, options (with might make useless almost
any additional application specific configuration parameter), dir_source
(and dir_* )
For point 3: status, autorestart (poor name), audits, noops
For point 4: package, service, file_path, dir_path
For point 5: my_class resources_hash
But maybe we have different semantic nuances for the term "modules'
Evidently so. For the most part, what you said does not conflict with what
I said; you were just more specific. Where we differ is that I am
distinguishing "reusability" from *ease* of reuse. I agree that all of
your items 1 - 6 are factors that improve modules' reusability. I assert,
however, that the names by which those particular knobs are referenced do
not constitute essential reusability factors, but rather ease of use
Here I really don't follow you: if you agree that the above points improves
modules' reusability, how can you say that defining naming standards for
parameters that empower those points just enhance ease of use and not the
same reusability of a module that implements them?
Basically, I am drawing the line at having to modify the code to use a
third-party module. The module is "reusable" if I do not have to modify
it, even if I have to study it to determine how to use it. It is easy to
use if it presents a coherent, intuitive external interface. Almost all
naming considerations fall into the latter category.
Well at least we agree on the definition of a reusable module.
Moreover, any ease of use advantage of such a convention is limited to
those users who buy in to the convention. Such buy-in is unlikely to arise
from a standard-setting effort alone.
I agree that the interoperability part is not fully dependent on naming
Aa a partial solution for this I have thought about the usage of a
"dependency_class" to contain in a single, replaceable, class all the
external dependencies, and eventually tweaking the Modulefile and the
puppet module command to manage soft-dependencies and reduce conflicts
modules Forge modules (more details on this on the blog post linked before).
I don't see it as a perfect solution but that's something that can be
done now (without extra code if not for the Forge integration) and very
I have some issues with that approach, but I'm going to disregard them for
now because that topic is largely beyond the stated scope of the naming
conventions and convention-drafting effort we are discussing.
I think being able to use another class in a drop-in way is not the
value I see in parameter naming 'recommendations'. I personal see
value in the ease of use more than anything, if parameters are
similarly named between classes, when you go to use them you don't
have to interrupt, double check with the docs what this class/define
uses, then modify your parameter name accordingly. Its a reduction in
surprise if anything. An example would be the 'package' parameter,
versus 'packages' ... if I didn't have to stop and check which one it
is for my XYZ class it might save time and mistakes *shrug*.
Let me clarify that hardly in my dreams I could imagine seamless drop-in
replacements, but naming standards+dependency_class pattern CAN make
interoperability much easier.
So, then, this really isn't just a question of naming things, as
previously claimed? I mean, I know I made that very observation in my
previous post, but I had assumed that it was just an aspect of the proposal
that you hadn't recognized and appreciated, not an intentional subterfuge.
Subterfuge is definitively a not appropriate and appreciated word for this
All the points of this discussion are expressed in the quoted blog post:http://www.example42.com/?q=The_handy_Grail_of_Modules_Standards
and the *draft* of a *proposal* for a *version 0.0.1* (I suppose this is
something far from being presented as definitive) :https://docs.google.com/document/d/1D4OqEI5iuGJe63ODU91N6rnFKcxVAg1sAWbaQrGBlWA/edit?usp=sharing
I can't repeat at every post or sentence the whole vision on how
appropriate module naming standards may improve modules' reusability,
interoperability and ultimately quality.
For the other benefits, least surprise is one point, not small as it
involves (let me copy and paste :-):
- Better user experience (modules are easier to use and understand)
- Quicker and more reliable Puppet manifests development (for basic
functions you can expect predictable parameters)
- More coherent and error proof Puppet setups
Least surprise applies only if I have a reason to expect particular
conventions to be followed. If not, then I cannot be surprised. In a
sense, then, the opportunity for surprise is a *cost* of such conventions
as are proposed, partially offsetting the potential ease of use advantages
for modules that conform with such a convention. And again, I do not deny
that there are potential ease of use advantages associated with shared
conventions, but that comes not from the conventions themselves, but rather
from their broad acceptance and use.
Broad acceptance and use definitively will arrive if:
- Sane naming standards are proposed that effectively enhance modules'
- PuppetLabs "suggests" and endorses them
Some of the conventions of Puppet' style language can be considered
arbitrary, still they are receiving wide acceptance because PuppetLabs has
proposed them and tools like puppet-lint (emerged later) make easier to
adapt to them.
Really I can't see why something similar can't happen for modules naming
standards (and yes, some naming conventions involve specific features and
functionality that definitively can make a module more reusable, so it's
not JUST a matter of giving names to things but also to suggest patterns
and techniques that make modules better)
but I see various other clear benefits, in the mid term:
- The possibility to have an unified approach to smoke testing of common
- The possibility to have web front-ends and ENC that leverage on the
If there were good tools available for those applications then they might
provide an impetus toward conformance with the proposed conventions.
However, I think adopting conventions on the hope that such tools will
materialize in the future is unwise. Call me "experienced", "jaded", or
even "cynical", but I know of too many instances of vaporware to be swayed
by promises of software that hasn't yet been written.
I just call you cynical. We can't do anything if we don't try to do it.
- Easier integration with superclasses that expose their own parameters
and use different modules to build up full applications stacks or complex
setups that involve multiple modules.
Sorry, I'm not seeing it.
- A PuppetLabs and/or Community driven central repository of well tested
and features rich unique Standard modules
(it might be a subset of the Forge or a set of git repos with only one
module for application)
Yes, the idea of a curated repository of interoperable modules has been
raised before. I think it's a fine idea, but I don't think it depends on
parameter naming conventions for realization. In fact, I don't think
parameter naming conventions actually bring much to that particular table.
I think exactly the contrary.
Having a curated repository of interoperable modules without a minimum set
of shared parameters would be a great drawback and a major lost occasion.
Not everybody has the skills and time to study a module's documentation or
even internal code to understand the logic of its parameters, being able to
leverage on some common parameters for the most important and common use
cases (such as defining the configuration file to use) would help and save
the time of many people, both beginners and experienced.
None of that is a fundamental reason to object to the effort, but I'm not
seeing any promise of significant benefit to motivate me to
I do have a bona fide objection, however: although the effort is cast at
this point as being aimed exclusively at parameter naming, by
also covers elements of module structure, organization, and style as well,
as the things being named have to exist for the standard to be
do understand that the intention is not to make all the standardized
controls mandatory for every module, but for those that a given module does
provide, even the standard's limited reusability and interoperability goals
are not served if those controls are not located where the standard
anticipates (which is for the most part on a single front-end class).
The assumption is that parameters are passed to the main module class or
to single specific defines.
This is the only constraint to the module structure then you can organize
the modules as you want.
It is a non-trivial constraint that all of a module's external interface
be implemented in the form of a single class and zero or more types (and
zero or more custom functions, heretofore not discussed). That it can be
expressed in one sentence does not make it less significant. Furthermore,
there is an implicit assumption even in that admission: that module
interfaces will involve parameterized classes. That in itself is probably
not a big deal any longer, but some of the prospective advantages claimed
seem predicated on the premise that parameterized-style class declarations
will be used. That *is* a big deal, especially given that a large
ecosystem of mutually interoperable modules is hypothesized as a viable and
*A really reusable module HAS to be parametrized*.
Take note, I can repeat and argument that anytime.
Parameters are the API of a module, the interface you can interact with it
without touching it.
If you don't use parameters either you are forcing inside the module
behaviours that can't be changed by users or you are forcing a specific way
to obtain the data that affects the modules behaviour and this inherently
makes it not reusable for people who provide data in other ways.
Most importantly, however, my central objection here is that a proposal
that purports to be exclusively about naming parameters in fact has any
implications at all for module organization and style.
Ok, it's not a proposal that purports to be exclusively about naming
parameters: the usage of specific parameters involve patterns that enhance
modules' reusability and interoperability.
The sample module code definitively exposes design patterns with modules
(and it demonstrates that you can follow different patterns to achieve the
Reading it again this is not so clear in the first post here, but it's
widely expressed in the linked pages.
So, sorry, now let's move a step further, let's talk, if you want, about
how to make that paper/draft/proposal better.
And if you think that such a thing should not even be discussed, well, ok,
I'll accept that and discuss it with who is interested in it.
Fair point, its a difficult document to position precisely. I guess I
foresee this as something that should be a part of a guide for writing
modules then any hard/fast rule or 'standard'.
Call it position paper or draft for a proposed standard, what's
important, imho, is the final goal:
The names of things matter, as indeed this whole discussion presupposes.
How people respond to the initiative will be colored on many levels by what
you call it and how you position it. In fact, I might not have joined the
discussion if the effort had been positioned as targeting a set of common
conventions, but setting a standard is a rather different endeavor.
some recommendations for naming conventions to use in modules
(parameters) that can help in making some order in the modules' casbah
while suggestion patterns that enhance reusability and may improve
Since it's at least 3 years that there're some sparse discussions about
modules reusability I preferred to give some solid ground upon which have a
discussion, for this reason I placed the links of the stdmod sample
modules and the Google Doc.
Please consider this as a starting point to improve and eventually
radically change (draft for 0.0.1 means that there's STILL to be a 0.0.1
and whatever comes after).
Thank you guys for the insights, hope to see your contributions to the
Doc, both for the parts that find you skeptic and the parts you agree upon.
I think it's important to do something that is well thought and shared but
is even more important to start to do it, step by step, and I hope we all
agree that is is something to do, sooner or later to avoid total chaos and
fragmentation in the modules ecosystem.
I think you have embarked on a worthy effort, but I also think your
aspirations are too grand. Build it, with as much community participation
as you can reasonably accommodate, and let the result speak for itself. If
it succeeds well in everything you envision then it is likely to be well
received and broadly implemented.
To be honest I already did something similar for my own set of modules.
I am surely biased but having common variables definitively gives a sense
to the term "least surprise".
About reusability I can say that I'm using those modules exactly as they
are on GitHub in several totally different Puppet installations and often
the implementation of a new service or role is as quick as writing few
lines of predictable code.
Somehow it also seems that some other people are doing the same with them,
given some figures from GitHub and the fact that about 100 different
committers have improved or patched them.
One of the reasons why I'm basically considering to thrash all this
"legacy" work and trying to promote and embrace wider standards is that I
definitively think that they can give great benefits to Puppet's modules
I'm well aware that such or a similar effort can really succeed only if
PuppetLabs endorses it, so I'd be ready to step aside and hand everything
to more expert and authoritative hands.
Still this idea is not only mine, I've talked and shared it with various
other Puppetteers (some of them started to make modules even before me or
you even knew what Puppet was) and the consensus is wide enough to make me
think that even without an explicit support from PuppetLabs, a robust,
coherent, shared and single repository of Puppet modules made by (some)
community members can be done and can work well.
But do not set out with the expectation of that the result will be adopted
or used otherwise, and certainly do not create a chicken-and-egg problem,
where the effort's success depends on it being successful.
Will it be successful?
We'll never know if we don't start to work on it.