Puppet users - Aug 2007 - 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

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

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

-- 
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 => :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.

- 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

-----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/IncludeMacro
Yeah, 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