Since I had my type development epiphany a couple of days ago, I''ve decided to write down my understanding of developing simple types, at http://reductivelabs.com/trac/puppet/wiki/PracticalTypes. I''d appreciate comments from people who already know how to develop types as to correctness, and also comments from people who are new to type development about whether it''s a helpful document, and whether it''s clearer than existing references on the topic. - Matt
Matthew Palmer wrote:> Since I had my type development epiphany a couple of days ago, I''ve decided > to write down my understanding of developing simple types, at > http://reductivelabs.com/trac/puppet/wiki/PracticalTypes. > > I''d appreciate comments from people who already know how to develop types as > to correctness, and also comments from people who are new to type > development about whether it''s a helpful document, and whether it''s clearer > than existing references on the topic.Matthew This is great. The only thing I would recommend is displaying the whole type you''re creating at the end of the example so people can see the whole picture and put all the pieces together. Regards James Turnbull -- James Turnbull <james@lovedthanlost.net> --- Author of Pro Nagios 2.0 (http://www.amazon.com/gp/product/1590596099/) Hardening Linux (http://www.amazon.com/gp/product/1590594444/) --- PGP Key (http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x0C42DF40) _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Thu, Aug 23, 2007 at 06:35:07PM +1000, James Turnbull wrote:> This is great. The only thing I would recommend is displaying the whole > type you''re creating at the end of the example so people can see the > whole picture and put all the pieces together.Yeah, that''s not a bad idea. <clickety click> - Matt
On 8/23/07, Matthew Palmer <mpalmer@hezmatt.org> wrote:> I''d appreciate comments from people who already know how to develop types as > to correctness, and also comments from people who are new to type > development about whether it''s a helpful document, and whether it''s clearer > than existing references on the topic.It reads like a missing manual :D Really good stuff, now I can actually understand what happens in the code! I never could get a firm grasp on the internal model :D Now I have! (I think.) -- Gegroet, Tim
<Derek.Whayman@barclayscapital.com>
2007-Aug-23 10:22 UTC
Re: Type development for the rest of us
Very, very useful for someone trying to get into developing custom types. The barrier to entry is mostly fear from what I''ve seen. Actually, creating a custom type which controls a delimited file is even easier. The ''puppet/provider/parsedfile'' does all the hard work, you need only pass it the arguments to describe the structure and restrictions on the files. Look at $rubysitedir/puppet/{type/mount.rb,provider/mount/parsed.rb} (and ignore the hooks to the commands if you prefer) for an example. I hope to produce a few soon. Derek -----Original Message----- From: puppet-users-bounces@madstop.com [mailto:puppet-users-bounces@madstop.com] On Behalf Of Matthew Palmer Sent: 23 August 2007 09:22 To: puppet-users@madstop.com Subject: [Puppet-users] Type development for the rest of us Since I had my type development epiphany a couple of days ago, I''ve decided to write down my understanding of developing simple types, at http://reductivelabs.com/trac/puppet/wiki/PracticalTypes. I''d appreciate comments from people who already know how to develop types as to correctness, and also comments from people who are new to type development about whether it''s a helpful document, and whether it''s clearer than existing references on the topic. - Matt _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users ------------------------------------------------------------------------ For important statutory and regulatory disclosures and more information about Barclays Capital, please visit our web site at http://www.barcap.com. Internet communications are not secure and therefore the Barclays Group does not accept legal responsibility for the contents of this message. Although the Barclays Group operates anti-virus programmes, it does not accept responsibility for any damage whatsoever that is caused by viruses being passed. Any views or opinions presented are solely those of the author and do not necessarily represent those of the Barclays Group. Replies to this email may be monitored by the Barclays Group for operational or business reasons. Barclays Capital is the investment banking division of Barclays Bank PLC, a company registered in England (number 1026167) with its registered office at 1 Churchill Place, London, E14 5HP. This email may relate to or be sent from other members of the Barclays Group. ------------------------------------------------------------------------
On Thu, Aug 23, 2007 at 06:22:10PM +1000, Matthew Palmer wrote:> and also comments from people who are new to type > development about whether it''s a helpful documentSuch documentation is essential for puppet success, I think. We could really use some more documentation on code architecture, as it''s a very steep learning curve, especially if you''re not fluent in ruby. -- Marcin Owsiany Web Systems Integrator - Guardian Unlimited ------------------------------------------------------------------ Visit Guardian Unlimited - the UK''s most popular newspaper website http://guardian.co.uk http://observer.co.uk ------------------------------------------------------------------ The Newspaper Marketing Agency Opening Up Newspapers http://www.nmauk.co.uk ------------------------------------------------------------------ This e-mail and all attachments are confidential and may also be privileged. If you are not the named recipient, please notify the sender and delete the e-mail and all attachments immediately. Do not disclose the contents to another person. You may not use the information for any purpose, or store, or copy, it in any way. Guardian News & Media Limited is not liable for any computer viruses or other material transmitted with or as part of this e-mail. You should employ virus checking software. Guardian News & Media Limited A member of Guardian Media Group PLC Registered Office Number 1 Scott Place, Manchester M3 3GG Registered in England Number 908396
Marcin Owsiany schrieb:> On Thu, Aug 23, 2007 at 06:22:10PM +1000, Matthew Palmer wrote: > >> and also comments from people who are new to type >> development about whether it''s a helpful document >> > > Such documentation is essential for puppet success, I think. We could > really use some more documentation on code architecture, as it''s a very > steep learning curve, especially if you''re not fluent in ruby. > >I second that entirely (me beeing the ruby/development noob of all times). And I have to say that doc is really really great! Thanks a lot!
On Aug 23, 2007, at 3:22 AM, Matthew Palmer wrote:> Since I had my type development epiphany a couple of days ago, I''ve > decided > to write down my understanding of developing simple types, at > http://reductivelabs.com/trac/puppet/wiki/PracticalTypes. > > I''d appreciate comments from people who already know how to develop > types as > to correctness, and also comments from people who are new to type > development about whether it''s a helpful document, and whether it''s > clearer > than existing references on the topic.I''m very happy to see this document, as it''s been made clear that the existing docs are not sufficient but I''ve made them about as well as I think I can. The only other comment I have about the doc is that it might make sense to use the more standard present/absent values for ''ensure'', and it might even make sense to call the type ''line'', rather than ''append_if_no_such_line''. That is, you''d end up with resources like this: line { "some text, yo": file => "/etc/system", ensure => present } This would make it easy to remove or add lines from a file. Mostly, tho, the ''ensure'' stuff is what matters -- keeping to standard values when possible is probably worth it. Note also that the default mechanism for a resource to enact changes is to call getter/setter methods on its provider, and if there are no defined providers, then Puppet will use the resource itself. So, you could have a resource like this: newtype :line do ... newproperty :ensure do desc "Blah" newvalue :present newvalue :absent end ... def ensure if File.exists?(self[:file]) and File.read.include?(self[:name]) :present else :absent end end def ensure=(value) File.open(self[:file]) { |f| f.puts self[:name] } end end I expect these docs are exactly what users don''t want to see, which is a big part of why the existing docs are no good, but I figured I''d throw it out there, anyway. And I do realize that the current resource/property/provider system is over-complicated. That complication is a result of the state before providers (which are only a year old, compared to the 2.5+ year old type system), and my hope is to refactor the setup so that it all becomes drastically easier. -- The point of living and of being an optimist, is to be foolish enough to believe the best is yet to come. -- Peter Ustinov --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On Aug 23, 2007, at 3:39 PM, Matthew Palmer wrote:> > The important thing I''ve found when writing docs is to keep it > light and > readable, and to try really hard to put yourself in a "I know > nothing" frame > of mind. Your docs read like your target audience is people who''ve > been in > your head for the past four years. They''re like notes to yourself, > rather > than explanations to a wide audience.Yep, I know, and even though I know that, I can''t seem to fix it much. I don''t think programmers should be allowed to write docs for their own code.> I''ve had to work pretty hard at "training" myself to think like a > newbie, > and cover things in a "basics first, then build the knowledge" > structure. > Best thing for that, actually, is to teach some real introductory > classes on > a technical topic -- you''ll really get a feel for how "newbie" you > have to > talk to make yourself understood to everyone. Volunteer to teach > Ruby to a > bunch of non-programming geeks for a couple of months -- that did > wonders > for my newbie-appreciation skills.Heh, I bet that would help.> I was trying to keep parity with an existing defined type, to keep the > amount of "new stuff to learn" to a minimum.I figured. That''s why I left this commentary after the "great doc" stuff -- because it''s not that important, and is probably part of why my docs suck and yours didn''t.>> Mostly, tho, the ''ensure'' stuff is what matters -- keeping to >> standard values when possible is probably worth it. > > I don''t see why -- this type is intended to never have the ''ensure'' > property > set in a manifest. I know it''s not idiomatic Puppet, but idiomatic > hasn''t > served me well to date.> [snip example] > > Hmm, I didn''t know that. I knew it was getters and setters for > providers, > but I didn''t realise it was done like that within the type, too. > Your exec > type needs some refactoring, in that case, because everything I > (mis)learnt > about Puppet types, I learnt from exec. <grin>Yep, both exec and file need to be refactored around this.> Funnily enough, I actually prefer the per-property value methods, > because it > groups related code more closely together, and makes it easier to > handle > lots of different discrete values (rather than some monster case > statement > in the setter method). However, if the retrieve/newvalue way is > deprecated > and going away (I can see why they might be deprecated, in a provider > world), I''ll update my guide to match the getter/setter way.One of the reasons I haven''t gone through with the refactoring I''ve threatened is that I want to still enable per-value code (sorry, delving into dev talk for a minute). E.g., the ''ensure'' property uses ''create'', ''destroy'', and ''exists?'' methods, normally, rather than ''ensure=<value>''. For ensure (and possibly as a generic feature that could be used elsewhere), my plan is to support a basic state machine where you''d specify the values and the provider methods needed to transition to that value (in that values would functionally be states). Something like: newvalue :present => :create newvalue :absent => :destroy This would allow you to avoid the ugly case statement but keep your types and providers loosely coupled.>> I expect these docs are exactly what users don''t want to see, which >> is a big part of why the existing docs are no good, but I figured I''d >> throw it out there, anyway. > > Eh? What don''t users want to see?Sorry, mistype; I was up too late or something.>> And I do realize that the current resource/property/provider system >> is over-complicated. That complication is a result of the state >> before providers (which are only a year old, compared to the 2.5+ >> year old type system), and my hope is to refactor the setup so that >> it all becomes drastically easier. > > Please. > > - Matt > > -- > How many Apple Newton users does it take to change a lightbulb? > Foux. There to eat lemons, axe gravy soup. > -- Seen on the ''net > _______________________________________________ > Puppet-users mailing list > Puppet-users at madstop.com > https://mail.madstop.com/mailman/listinfo/puppet-users >-- I worry that the person who thought up Muzak may be thinking up something else. --Lily Tomlin --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On Thu, Aug 23, 2007 at 09:06:02AM -0500, Luke Kanies wrote:> I''m very happy to see this document, as it''s been made clear that the > existing docs are not sufficient but I''ve made them about as well as > I think I can.The important thing I''ve found when writing docs is to keep it light and readable, and to try really hard to put yourself in a "I know nothing" frame of mind. Your docs read like your target audience is people who''ve been in your head for the past four years. They''re like notes to yourself, rather than explanations to a wide audience. I''ve had to work pretty hard at "training" myself to think like a newbie, and cover things in a "basics first, then build the knowledge" structure. Best thing for that, actually, is to teach some real introductory classes on a technical topic -- you''ll really get a feel for how "newbie" you have to talk to make yourself understood to everyone. Volunteer to teach Ruby to a bunch of non-programming geeks for a couple of months -- that did wonders for my newbie-appreciation skills.> The only other comment I have about the doc is that it might make > sense to use the more standard present/absent values for ''ensure'', > and it might even make sense to call the type ''line'', rather than > ''append_if_no_such_line''.I was trying to keep parity with an existing defined type, to keep the amount of "new stuff to learn" to a minimum.> Mostly, tho, the ''ensure'' stuff is what matters -- keeping to > standard values when possible is probably worth it.I don''t see why -- this type is intended to never have the ''ensure'' property set in a manifest. I know it''s not idiomatic Puppet, but idiomatic hasn''t served me well to date.> Note also that the default mechanism for a resource to enact changes > is to call getter/setter methods on its provider, and if there are no > defined providers, then Puppet will use the resource itself. So, you > could have a resource like this:[snip example] Hmm, I didn''t know that. I knew it was getters and setters for providers, but I didn''t realise it was done like that within the type, too. Your exec type needs some refactoring, in that case, because everything I (mis)learnt about Puppet types, I learnt from exec. <grin> Funnily enough, I actually prefer the per-property value methods, because it groups related code more closely together, and makes it easier to handle lots of different discrete values (rather than some monster case statement in the setter method). However, if the retrieve/newvalue way is deprecated and going away (I can see why they might be deprecated, in a provider world), I''ll update my guide to match the getter/setter way.> I expect these docs are exactly what users don''t want to see, which > is a big part of why the existing docs are no good, but I figured I''d > throw it out there, anyway.Eh? What don''t users want to see?> And I do realize that the current resource/property/provider system > is over-complicated. That complication is a result of the state > before providers (which are only a year old, compared to the 2.5+ > year old type system), and my hope is to refactor the setup so that > it all becomes drastically easier.Please. - Matt -- How many Apple Newton users does it take to change a lightbulb? Foux. There to eat lemons, axe gravy soup. -- Seen on the ''net
On Thu, Aug 23, 2007 at 04:32:58PM -0500, Luke Kanies wrote:> On Aug 23, 2007, at 3:39 PM, Matthew Palmer wrote: > > > > The important thing I''ve found when writing docs is to keep it > > light and > > readable, and to try really hard to put yourself in a "I know > > nothing" frame > > of mind. Your docs read like your target audience is people who''ve > > been in > > your head for the past four years. They''re like notes to yourself, > > rather > > than explanations to a wide audience. > > Yep, I know, and even though I know that, I can''t seem to fix it > much. I don''t think programmers should be allowed to write docs for > their own code.Bah. Who else knows it as well as the author? Writing docs is a learnable skill, like any other. It''s just that programming has an anti-documentation culture, which makes writing docs seem "uncool", and most good programmers find it harder to learn good documentation skills than good coding skills, so they fob off writing docs.> E.g., the ''ensure'' property uses ''create'', ''destroy'', and ''exists?'' > methods, normally, rather than ''ensure=<value>''. For ensure (and > possibly as a generic feature that could be used elsewhere), my plan > is to support a basic state machine where you''d specify the values > and the provider methods needed to transition to that value (in that > values would functionally be states). Something like: > > newvalue :present => :create > newvalue :absent => :destroySo that would map the value :present to the type or provider method named ''create''? From a providers perspective, that''s probably a reasonable fix, but for provider-less types it just seems a bit overengineered. I suppose that, if providered types are the more common case, it''s probably worth the extra complexity, though. - Matt -- A byte walks into a bar and orders a pint. Bartender asks him "What''s wrong?" The byte says "Parity error." Bartender nods and says "Yeah, I thought you looked a bit off."
On Aug 25, 2007, at 4:48 PM, Matthew Palmer wrote:> > Bah. Who else knows it as well as the author? Writing docs is a > learnable > skill, like any other. It''s just that programming has an anti- > documentation > culture, which makes writing docs seem "uncool", and most good > programmers > find it harder to learn good documentation skills than good coding > skills, > so they fob off writing docs.I don''t think you can reasonably complain that I''ve fobbed off writing docs. I seem to be the only real source of high-level documentation, and I''ve definitely been the only source of developer documentation. No, it''s not sufficient, yes, it''s often out of date, but you could say the same thing about the code itself without being too far out of line. I also don''t think you can claim I have an anti-documentation bent, considering how thoroughly I''ve entrenched autogenerated documentation throughout the code base. You''ve got entirely complete reference documentation for essentially every part of the system the user has to touch except for the language itself, and if I could figure out how to autogenerate documentation for that, I would. You can claim a chicken and egg problem if you want, but I have never gotten much response when producing developer documentation, so I have concluded that the community has no desire for it, so it''s a waste of time. You yourself, until very recently, brushed me off when I recommended the creation of custom types, so you can''t exactly be shocked when I haven''t bothered documenting the hell out of it, especially considering that I''m hoping to refactor it ASAP.>> >> newvalue :present => :create >> newvalue :absent => :destroy > > So that would map the value :present to the type or provider method > named > ''create''? From a providers perspective, that''s probably a > reasonable fix, > but for provider-less types it just seems a bit overengineered. I > suppose > that, if providered types are the more common case, it''s probably > worth the > extra complexity, though.Yes, it would. For an idea of a more realistic definition of a state machine, look at the stuff in the Zone type; I actually created a state machine there, with methods for each state transition. The common case will be getters and setters for all parameters except ''ensure'', and it will use these state-transition methods, but the configuration of the methods will be automatic, just like it is right now if you call ''ensurable'' in your type. If you want to create a type with no provider, then as mentioned you can create your getters and setters in the type itself and the properties will use that as the stand-in provider. And if you think this is over-engineered, you should try following the current code path from ''sync()'' through to something actually getting called on the provider. Or whatever might be happening, depending on the property. The real goal is to get to the point where the property definitions are entirely data, with maybe a touch of code for validation. All of the code would either be in the type or provider. -- Good judgment comes from experience, and experience comes from bad judgment. --Barry LePatner --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
David Schmitt
2007-Aug-26 20:51 UTC
deprecating append_if_no_such_line (was: Re: Type development for the rest of us)
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi Matt, list! On Thursday 23 August 2007, Matthew Palmer wrote:> On Thu, Aug 23, 2007 at 09:06:02AM -0500, Luke Kanies wrote: > > The only other comment I have about the doc is that it might make > > sense to use the more standard present/absent values for ''ensure'', > > and it might even make sense to call the type ''line'', rather than > > ''append_if_no_such_line''. > > I was trying to keep parity with an existing defined type, to keep the > amount of "new stuff to learn" to a minimum. > > > Mostly, tho, the ''ensure'' stuff is what matters -- keeping to > > standard values when possible is probably worth it. > > I don''t see why -- this type is intended to never have the ''ensure'' > property set in a manifest. I know it''s not idiomatic Puppet, but > idiomatic hasn''t served me well to date.Using append_if_no_such_line means that you can never remove that line again. I switched to a "line" define with an ensure parameter as Luke recommends. Since it doesn''t support purging, it''s not perfect, but it is a step up. For the trivial implementation see modules/common/manifests/defines/line.pp in my git repository. Regards, David PS: This mail promted me to queue a patch to croak in my append_if_no_such_line define and set line($ensure=''present'') as default. - -- The primary freedom of open source is not the freedom from cost, but the free- dom to shape software to do what you want. This freedom is /never/ exercised without cost, but is available /at all/ only by accepting the very different costs associated with open source, costs not in money, but in time and effort. - -- http://www.schierer.org/~luke/log/20070710-1129/on-forks-and-forking -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQFG0ee9/Pp1N6Uzh0URAveyAJ9oZ/AMfzvVzIkSl9P9OBHcbAdm3ACffla7 GlPuDl7MImIKHSK/h37t2DA=yTKv -----END PGP SIGNATURE-----
On Thu, Aug 23, 2007 at 04:32:58PM -0500, Luke Kanies wrote:> I don''t think programmers should be allowed to write docs for > their own code.Off topic I know, but this gave me a serious fright. I stand on the far other end of the spectrum on this one. I don''t think programmers should be allowed to show their code to anyone else unless they have documented it fully. You cannot truly understand something until you have explained it to someone else. The process of documenting code allows the author to uncover problems, primarily those of unnecessary complexity and false assumptions. Undocumented code is difficult to understand and maintain. Writing good documentation is just as important and difficult to learn as writing good code. Of course, pragmatic reasons often prevent documentation from being produced, sacrificing long-term for short-term. Alex
On Aug 27, 2007, at 3:14 AM, Alexander Taler wrote:> > Off topic I know, but this gave me a serious fright. > > I stand on the far other end of the spectrum on this one. I don''t > think programmers should be allowed to show their code to anyone > else unless they have documented it fully. You cannot truly > understand something until you have explained it to someone else. > The process of documenting code allows the author to uncover > problems, primarily those of unnecessary complexity and false > assumptions. Undocumented code is difficult to understand and > maintain. Writing good documentation is just as important and > difficult to learn as writing good code.If there were unit tests for documentation sufficiency, I''d feel pretty differently about it, but there aren''t. I''ve often written documentation that I thought was sufficient only to have it either entirely ignored, for who-knows-why, or castigated as being entirely unrelated to what people want. There''s a pretty tight feedback mechanism when writing code -- you know what you want it to do, so you test whether it does that. It''s entirely different when writing documentation, especially when the wider world is looking at the docs and generally just ignoring bad documentation rather than mentioning it at all. About every six months or so, I go on a documentation binge, attempting to turn whatever pile of docs we have into something good, and I don''t think anyone would say I''ve yet succeeded. On the other hand, we have a large, active community full of people who know the product and care about good docs. It''s conceivable that if I switched my focus from development to documentation, or spent 3 months trying to becoming a better documenter, then I would be able to turn out good docs, but I''m not convinced (it''s not like this is my first crack at writing docs). -- It is well to remember that the entire universe, with one trifling exception, is composed of others. --John Andrew Holmes --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
I seem to have given the impression that I am criticising the state of the Puppet documentation. However this wasn''t my intention at all, so for that I apologise. I was trying to make a more philosophical point about producing documentation.
On Aug 28, 2007, at 9:22 PM, Alexander Taler wrote:> I seem to have given the impression that I am criticising the > state of the Puppet documentation. However this wasn''t my intention > at all, so for that I apologise. I was trying to make a more > philosophical point about producing documentation.I understand, and I apologize for reacting to vehemently. Puppet seems to be reaching a much wider audience right now, and I''m getting a heckuva lot more bug tickets and complaints about the documentation than offers of help and patches, so it''s overwhelming me a bit.> From the existing Puppet documenation, I have been very well > served by the Type Reference and Function Reference documents, > and found the Language Tutorial to be a handy introduction. > If I were to ask for more, it would be a Language Reference, > and a comprehensive index, because I find search tools > generally lacking.I also largely prefer references to tutorials, which is why I''ve tried to create good ones. I''ve toyed with the idea of creating a language reference, but my definition of reference is ''autogenerated from the code'', and I''m not sure I''ll be able to do that for the language. I might try again, though.> As someone who compulsively writes documenation, I know exactly what > you mean. It seems that no one appreciates the effort invested. > But when I look at things from my perspective, I find it so much > more rewarding working with software that is well documented, and > so I try to emulate that. OpenBSD is an excellent example of how > thorough documentation can really help.Yeah, I really have spent a lot of time on documentation, but in some ways I think it''s backfired -- I think people have kind of gotten used to me making the small edits, so they have been hesitant to do so themselves. I''m currently focusing on pushing people to make changes themselves, so that everyone understands that my goal is great docs, not ownership or whatever. I''m hoping this will get a lot more people involved and make everyone feel more comfortable adding their $.02.> As for it not being what people want, it might be because different > people want different things. I want reference documents, and only > grudgingly use tutorials, while there are others who swear by > tutorials > and shun reference documents.I think beginners usually want tutorials, but I know it''s the references that I keep going back to.> If our project decides to use Puppet long term (we are evaluating it > still), then I may have some time to commit to the documentation. In > the mean time, I wouldn''t presume to tell you what to do, only what > I as one potential user, consider valuable.That''s certainly the kind of information I need, although just doing it yourself instead of telling me what to do is always even more appreciated. :) Hopefully you''ll decide to stick with Puppet and we''ll see the docs starting pouring out. -- It''s not to control, but to protect the citizens of Singapore. In our society, you can state your views, but they have to be correct. -- Ernie Hai, co-ordinator of the Singapore Government Internet Project --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
Speaking as a recent n00b that has switched over to the reference point of view, I would like to see the following tutorials. 1) A small example that shows how to manage a single machine (perhaps a laptop) that just barely touches on some of the mid-level concepts and doesn''t mention the really fancy stuff at all. 2) A medium example that barely touches the fancy stuff and might be adequate for managing a small lab (say 20 systems that are all within 5 classes). Introduce modules here. 3) A large example that uses the fancy stuff and a bunch of inheritance that would be good for potentially managing 100 or more systems with at least 15 classes of systems, including multiple OS types (to show how the same manifests/modules can be used for different OSs) The tutorials should stay up to date with the latest stable version of Puppet and perhaps become part of the basis for testing each new release. Personally, I like tutorials because I can see the answer and get started with things right away and then dig backwards into the guts as time progresses and I need to make changes. I also like them because I can see what the community generally views as ''best practice'' or the ''right way'' to do things. Especially, when their way might actually be scalable as opposed to mine :-). So....after all that, yes, I am interested in trying to make something like this but for now I''m going to have to just throw this out as a suggestion since I''m blessed with an overabundance of no spare time :-/. Trevor On 8/31/07, Luke Kanies <luke@madstop.com> wrote:> On Aug 28, 2007, at 9:22 PM, Alexander Taler wrote: > > > I seem to have given the impression that I am criticising the > > state of the Puppet documentation. However this wasn''t my intention > > at all, so for that I apologise. I was trying to make a more > > philosophical point about producing documentation. > > I understand, and I apologize for reacting to vehemently. Puppet > seems to be reaching a much wider audience right now, and I''m getting > a heckuva lot more bug tickets and complaints about the documentation > than offers of help and patches, so it''s overwhelming me a bit. > > > From the existing Puppet documenation, I have been very well > > served by the Type Reference and Function Reference documents, > > and found the Language Tutorial to be a handy introduction. > > If I were to ask for more, it would be a Language Reference, > > and a comprehensive index, because I find search tools > > generally lacking. > > I also largely prefer references to tutorials, which is why I''ve > tried to create good ones. I''ve toyed with the idea of creating a > language reference, but my definition of reference is ''autogenerated > from the code'', and I''m not sure I''ll be able to do that for the > language. I might try again, though. > > > As someone who compulsively writes documenation, I know exactly what > > you mean. It seems that no one appreciates the effort invested. > > But when I look at things from my perspective, I find it so much > > more rewarding working with software that is well documented, and > > so I try to emulate that. OpenBSD is an excellent example of how > > thorough documentation can really help. > > Yeah, I really have spent a lot of time on documentation, but in some > ways I think it''s backfired -- I think people have kind of gotten > used to me making the small edits, so they have been hesitant to do > so themselves. > > I''m currently focusing on pushing people to make changes themselves, > so that everyone understands that my goal is great docs, not > ownership or whatever. I''m hoping this will get a lot more people > involved and make everyone feel more comfortable adding their $.02. > > > As for it not being what people want, it might be because different > > people want different things. I want reference documents, and only > > grudgingly use tutorials, while there are others who swear by > > tutorials > > and shun reference documents. > > I think beginners usually want tutorials, but I know it''s the > references that I keep going back to. > > > If our project decides to use Puppet long term (we are evaluating it > > still), then I may have some time to commit to the documentation. In > > the mean time, I wouldn''t presume to tell you what to do, only what > > I as one potential user, consider valuable. > > That''s certainly the kind of information I need, although just doing > it yourself instead of telling me what to do is always even more > appreciated. :) > > Hopefully you''ll decide to stick with Puppet and we''ll see the docs > starting pouring out. > > -- > It''s not to control, but to protect the citizens of Singapore. In our > society, you can state your views, but they have to be correct. > -- Ernie Hai, co-ordinator of the Singapore Government > Internet Project > --------------------------------------------------------------------- > Luke Kanies | http://reductivelabs.com | http://madstop.com > > > _______________________________________________ > Puppet-users mailing list > Puppet-users@madstop.com > https://mail.madstop.com/mailman/listinfo/puppet-users >
On Fri, 31 Aug 2007, Trevor Vaughan wrote:> 1) A small example that shows how to manage a single machine (perhaps > a laptop) that just barely touches on some of the mid-level concepts > and doesn''t mention the really fancy stuff at all.This would be great. I''ve been trawling the web and this list a bit and while there are several "Howto install puppet and manage the permission of /etc/sudoers" tutorials there seems to be a learning cliff just past that (which I am working up). This file hints at interesting things: http://reductivelabs.com/trac/puppet/wiki/PuppetBestPractice and the recent git links posted hint at other useful stuff ( I have not used git much so I have not downloaded them yet). I would guess that people who are using puppet to look after servers are either (a) Installing images that are 99% right and just configuring a couple of additional services per server or (b) Taking very generic installs and configuring many things ( Say 20+ ). If (b) is common then I was thinking about creating a sample setup that should be fairly easy for people to adapt to their own site and get them 80% of the way there. However that I can''t find any sign of this existing already probably indicate that (a) is the most common case. -- Simon J. Lyall | Very Busy | Web: http://www.darkmere.gen.nz/ "To stay awake all night adds a day to your life" - Stilgar | eMT.
> > The tutorials should stay up to date with the latest stable version of > Puppet and perhaps become part of the basis for testing each new > release.Good point. If the examples are kept in the Puppet source tree, they can be parsed as part of an automated acceptance test suite. J. _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Sunday 02 September 2007, Julian Simpson wrote:> > The tutorials should stay up to date with the latest stable version of > > Puppet and perhaps become part of the basis for testing each new > > release. > > Good point. If the examples are kept in the Puppet source tree, they can > be parsed as part of an automated acceptance test suite.That sounds like a great idea! I always keep wondering when trying out a new puppetmaster, whether my (newly detected) syntax errors are because I overlooked a recent development or something else. Regards, David - -- The primary freedom of open source is not the freedom from cost, but the free- dom to shape software to do what you want. This freedom is /never/ exercised without cost, but is available /at all/ only by accepting the very different costs associated with open source, costs not in money, but in time and effort. - -- http://www.schierer.org/~luke/log/20070710-1129/on-forks-and-forking -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQFG2tie/Pp1N6Uzh0URAvOoAJ9+kum3uA096B7IYIC6XJ/CQ/i6qQCgkmWd 9r2ATw5lGlW+tVara56qZxA=wU4q -----END PGP SIGNATURE-----
Simon Lyall <simon@darkmere.gen.nz> writes:> I would guess that people who are using puppet to look after servers are > either (a) Installing images that are 99% right and just configuring a > couple of additional services per server or (b) Taking very generic > installs and configuring many things ( Say 20+ ).> If (b) is common then I was thinking about creating a sample setup that > should be fairly easy for people to adapt to their own site and get them > 80% of the way there. However that I can''t find any sign of this > existing already probably indicate that (a) is the most common case.Stanford University is definitely using Puppet in mode (b), but I''m not sure that I agree that this would make it eassy to put together an 80% template. It''s probably due to lack of good factoring on our part, but most of our modules have a fair bit of local knowledge embedded that wouldn''t be appropriate for a lot of other sites. For example, any module that installs a service also installs an iptables rule and a filter-syslog fragment to exclude its log messages, we occasionally assume the existence of daemontools, we use newsyslog for log rotation, etc. -- Russ Allbery (rra@stanford.edu) <http://www.eyrie.org/~eagle/>
On Sep 2, 2007, at 8:15 AM, Julian Simpson wrote:> Good point. If the examples are kept in the Puppet source tree, > they can be parsed as part of an automated acceptance test suite.The examples are not kept in the Puppet source tree; they''re in the Trac wiki, and they''re inline with the wiki documents. If anyone can figure out a way to pull the samples into separate documents, such that they still show up in-line in the tutorials but are available for testing, I''d love to set this up. -- oH for Pete''s sake, use a real filter. ;-) -- Tom Christiansen Look, I refuse to install any filter which looks like it''s more highly evolved than homo sapiens, it will just get embarassing when it starts critiquing the literrary style of my friends mail to me. -- Richard Caley, in comp.lang.perl.misc --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
2007/9/3, Luke Kanies <luke@madstop.com>:> On Sep 2, 2007, at 8:15 AM, Julian Simpson wrote: > > > Good point. If the examples are kept in the Puppet source tree, > > they can be parsed as part of an automated acceptance test suite. > > The examples are not kept in the Puppet source tree; they''re in the > Trac wiki, and they''re inline with the wiki documents. > > If anyone can figure out a way to pull the samples into separate > documents, such that they still show up in-line in the tutorials but > are available for testing, I''d love to set this up.Maybe the Trac IncludeMacro Plugin does what you need by including the samples from an URL: http://trac-hacks.org/wiki/IncludeMacro> --------------------------------------------------------------------- > Luke Kanies | http://reductivelabs.com | http://madstop.com-- Andreas
On Sep 3, 2007, at 2:33 PM, Andreas Hochsteger wrote:> Maybe the Trac IncludeMacro Plugin does what you need by including the > samples from an URL: > http://trac-hacks.org/wiki/IncludeMacroYeah, that looks like it would do it. Anyone want to come up with a plan for how this would work? We need to pick a place in the source repository and then write the tests that run the code and make sure the code does what we think it does. Any volunteers? If someone can commit to getting that to happen, I can get the IncludeMacro installed. -- You only have to be open minded if you''re wrong. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com