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 >>> names. At >>> > 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 >> reusability cases) >> 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' >> reusability". >> > > > 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 > factors. >
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 >> standards. >> 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 >> quickly. >> > > > 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 case 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' reusability - 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 >> features >> >> - The possibility to have web front-ends and ENC that leverage on the >> standardized parameters >> > > 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 >>> participate >>> > actively. >>> > >>> > I do have a bona fide objection, however: although the effort is cast >>> at >>> > this point as being aimed exclusively at parameter naming, by >>> implication it >>> > also covers elements of module structure, organization, and style as >>> well, >>> > as the things being named have to exist for the standard to be >>> relevant. I >>> > 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 > likely outcome. > *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 same behaviour. 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 >> interoperabiity. >> >> 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 ecosystem. 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. Al -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-users+unsubscr...@googlegroups.com. To post to this group, send email to puppet-users@googlegroups.com. Visit this group at http://groups.google.com/group/puppet-users. For more options, visit https://groups.google.com/groups/opt_out.
