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. 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. 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. > 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. > 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. > - 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. > > >> > 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. 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. 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. 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. John -- 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.
