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". > > > I see implications for interoperability only insomuch as one imagines > > facilitating one module being a drop-in replacement for another, but (1) > > there's a lot more to that than just common naming, so (2) that kind of > > interoperability is unlikely to come about except by specific intention > > anyway, so in that case shared naming comes out as a project > requirement. > > To me, that moots any general parameter-naming standard as far as > > interoperability goes. > 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 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. 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 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 - 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. - 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) > > Is that valuable? Alas, I'm more of developer then user these days so > I would defer that to our users. As a developer though - I would find > it handy to have a guide for common things, I'm a pedant when it comes > to naming and if someone already came up with a name for me, I would > probably use it, presuming others have thought through any naming > consequences. > > > 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. These are two sample modules that honour the same standard parameters with totally different implementations for a typical package/service/file module type: https://github.com/example42/puppet-stdmod https://github.com/example42/puppet-stdmodalt I've been pondering this situation as well. I presume in a world where > such recommendations become commonly used, the outcome would be > surprise at a missing 'recommended' parameter, then a subsequent bug > raised on the module due to its lack. This might be considered a > positive or negative. If the parameter name was named 'something else' > due to a feeling that the 'standard' is not covering a developers > needs, then this could be annoying to have that discussion _yet > again_. If however the functionality is simply missing - this becomes > a BAU patch (like the lint patches we see all the time) and probably a > positive feature request. > To ease the migration of modules to the standard namings, for overlapping parameters it could be useful to create a function and provide some sample code to manage duplicated parameters and notify the user with a deprecation notice when the "old" parameter is used I definitively would not throw away all the current modules work for the reckless seek of some standard fanciness. We can think of tools, methods and suggestions to ease the migration of existing modules and to speed the creation of new standard modules (the above sample modules are made to be easily clonable and may serve as blueprint for new modules). > Of course, this all depends on how good the recommendations are. > Having looked through the document I think some of them are obvious, > and require less debate while other recommendations are less > obvious/contentious. > The intention of the shared google doc is exactly to start to enumerate what are possible sane "standard" parameters and give them a good and coherent name. Please comment on the doc what are the params for which you'd choose a different name and, most important, what are the ones that should not be there (and obviously add some missing ones you may think about) > > > Personally, I would rather see a white paper explaining what kinds of > > controls need to be available to facilitate reusability of various kinds > of > > modules, and, optionally, setting out one or more models of how a module > can > > provide those controls. Regardless of the nature of the paper's > authorship, > > this feels like it should be a position paper, not a proposed standard. > > 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: 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. my2c 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.
