Just a idea to float out here among puppet forge users,
Can we have a readme standard? For example, we could have a format like
the following
# Developer - Bob@example.com
# URL http://forge.puppetlabs.com/bob/packagename
#
# Description:
# This does module will install packagename on node.example.com,
# and provide this feature
#
# Example usage:
# node testnode.example.com {
#
# include packagename
# }
If the developers added that to the their modules, that would be great
for the new guys :) Just something for everyone to think about.
---
Latest Article :- The Puppet Module Tool
The Puppet Apprentice :- http://puppetnewbie.blogspot.com
Follow me on twitter :- http://twitter.com/mritguru
Puppet #tags on twitter :- #puppet #puppetforge
IRC :- itguru ON irc.freenode.org (feel free to say
hi!)
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.
On Sun, May 30, 2010 at 11:56 AM, Gabriel - IP Guys < Gabriel@impactteachers.com> wrote:> Can we have a readme standard? For example, we could have a format like > the following >+1 Good idea! I will be easier to know what is the module''s feature -- Carla -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
"Gabriel - IP Guys" <Gabriel@impactteachers.com> writes:> Just a idea to float out here among puppet forge users, > > Can we have a readme standard? For example, we could have a format like the > followingFWIW, a *great* model to follow is probably the standard Unix manual page format, which has had thirty years of working reasonably well for documenting this sort of thing. If you forgive my linking into a Perl tool, this is probably the most user-friendly documentation about the structure of a good manual page for software tools I know of: http://search.cpan.org/~jhi/perl-5.8.1/pod/pod2man.PL#NOTES Specifically, the ''NOTES'' section includes the details on how to structure the manual page and what to include in each section. Using a model like that means the puppet community can work from the base of a good, solid existing practice rather than inventing their own standards — and, of course, having to rediscover the same problems everyone else ran into. :) Regards, Daniel -- ✣ Daniel Pittman ✉ daniel@rimspace.net ☎ +61 401 155 707 ♽ made with 100 percent post-consumer electrons -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
+1 to any well-formed data about modules. FWIW, there was a discussion last year about storing metadata in JSON or YAML format. J. On 31 May 2010 03:10, Daniel Pittman <daniel@rimspace.net> wrote:> "Gabriel - IP Guys" <Gabriel@impactteachers.com> writes: > > > Just a idea to float out here among puppet forge users, > > > > Can we have a readme standard? For example, we could have a format like > the > > following > > FWIW, a *great* model to follow is probably the standard Unix manual page > format, which has had thirty years of working reasonably well for > documenting > this sort of thing. > > If you forgive my linking into a Perl tool, this is probably the most > user-friendly documentation about the structure of a good manual page for > software tools I know of: > > http://search.cpan.org/~jhi/perl-5.8.1/pod/pod2man.PL#NOTES > > Specifically, the ''NOTES'' section includes the details on how to structure > the > manual page and what to include in each section. > > > Using a model like that means the puppet community can work from the base > of a > good, solid existing practice rather than inventing their own standards — > and, > of course, having to rediscover the same problems everyone else ran into. > :) > > Regards, > Daniel > > -- > ✣ Daniel Pittman ✉ daniel@rimspace.net ☎ +61 401 155 > 707 > ♽ made with 100 percent post-consumer electrons > > -- > You received this message because you are subscribed to the Google Groups > "Puppet Users" group. > To post to this group, send email to puppet-users@googlegroups.com. > To unsubscribe from this group, send email to > puppet-users+unsubscribe@googlegroups.com<puppet-users%2Bunsubscribe@googlegroups.com> > . > For more options, visit this group at > http://groups.google.com/group/puppet-users?hl=en. > >-- Julian Simpson Software Build and Deployment http://www.build-doctor.com http://twitter.com/builddoctor -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Julian Simpson wrote:> +1 to any well-formed data about modules. FWIW, there was a discussion > last year about storing metadata in JSON or YAML format.And there in fact was a metdata.json file added to modules after Puppet Camp. The proposed format was pretty much: { "license": "GPL2", "author": "author", "version": "1.0", "puppetversion": "0.25", "source": "http://foo/" } See: http://projects.reductivelabs.com/issues/3778 http://github.com/plathrop/puppet-module-supervisor/blob/master/metadata.json http://www.mail-archive.com/puppet-dev@googlegroups.com/msg07280.html http://www.lab42.it/presentations/puppetmodules/puppetmodules.html Cheers James Turnbull -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
[Mr Gabriel Says ...] +1 - It seems that some work has already been done to make a standard, but maybe a little more response for some of the people who have actually made modules for public release -- That would be helpful. My feelings on this - so long as the end result allows the user to a find out who wrote it, where the module came from, the version, what it does, and how to use it. So long as that information is communicated for each module, in an easy to use and standard manner, I will support it. Be it via the README txt file, or some other mechanism, so long as that information is packaged with each module, I think it would be a good step forward. Personally, I say start with putting the info into the README txt file which should be found with each module, and then we can see where we go from there. On a final note - I know sysadmins are a lazy bunch of people (hence why we write scripts, and automate stuff!), but it would be nice to get a little traction in this area. If I have to bug that cr*p out of the module writers, then that''s something I''m prepared to do. With a greater user base, and an easy path to adopting puppet, this project can only get better. --- Latest Article :- The Puppet Module Tool The Puppet Apprentice :- http://puppetnewbie.blogspot.com Follow me on twitter :- http://twitter.com/mritguru Puppet #tags on twitter :- #puppet #puppetforge IRC :- itguru ON irc.freenode.org (feel free to say hi!) -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
"Gabriel - IP Guys" <Gabriel@impactteachers.com> writes:> [Mr Gabriel Says ...] > +1 - It seems that some work has already been done to make a standard,[...]> On a final note - I know sysadmins are a lazy bunch of people (hence why we > write scripts, and automate stuff!), but it would be nice to get a little > traction in this area. If I have to bug that cr*p out of the module writers, > then that''s something I''m prepared to do.You would probably get better results, generally speaking, by ensuring that there are good, standard documents about how to do this visible to community members. Then, you go ahead and submit changes to modules to bring their docs into conformance with the standards, and build technical tools to work with those standards and generate better results, and the rest flows pretty naturally. FWIW, having a list for "module authors" aside from user concerns is often helpful, so that people can ask questions like "how do I document blah" rather than "how do I achieve blah" in a space focused on the topic. From my experience, obviously, and based on my background in more conservative, traditional communities like Perl rather than some of the newer communities like Ruby. They may behave differently... Daniel -- ✣ Daniel Pittman ✉ daniel@rimspace.net ☎ +61 401 155 707 ♽ made with 100 percent post-consumer electrons -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
"Gabriel - IP Guys" <Gabriel@impactteachers.com> writes:> [Mr Gabriel Says ...] > +1 - It seems that some work has already been done to make a standard,[...]> On a final note - I know sysadmins are a lazy bunch of people (hence why we > write scripts, and automate stuff!), but it would be nice to get a little > traction in this area. If I have to bug that cr*p out of the module writers, > then that''s something I''m prepared to do.You would probably get better results, generally speaking, by ensuring that there are good, standard documents about how to do this visible to community members. [Mr Gabriel Says ...] Are you suggesting that I publish a quick document on how to do a readme? A document, on how to write a document? Well, if that what it takes to get people working from the same page, then sure I''ll do it. (Didn''t I do that with the example posting? Maybe a blog post to go with it would help - Or an open posting to this list? Ideas? To be honest with you, I don''t see what is so hard to grasp, it''s just one more point on the checklist before releasing a module, take 20 seconds to write a README that explains how to use this module, where it came from, and who made it. Honestly speaking, how much debate needs to go into this? Type 15 lines after you''ve finished coding your module - help out those of us who didn''t code your module. Developing a standard is fine, and I''ll ''vote'' for that anyday of the week, but this is a request to help those coming into this community. [/Mr Gabriel] Then, you go ahead and submit changes to modules to bring their docs into conformance with the standards, and build technical tools to work with those standards and generate better results, and the rest flows pretty naturally. [Mr Gabriel Says ...] Again, this is something I would ''vote'' for, but not as a first step. Lets get something basic up and running and in use, and if there are any issues with the method, then we can expand on it, and form a true standard. For now, I just want module authors to LABEL their product. When I go shopping, all the tinned produce looks the same, but I know what''s in each! Just by reading the LABEL [/Mr Gabriel] FWIW, having a list for "module authors" aside from user concerns is often helpful, so that people can ask questions like "how do I document blah" rather than "how do I achieve blah" in a space focused on the topic. [Mr Gabriel Says ...] Does such a list exist? If not, then I think this would be a good time to create such a list - Look to be honest, we just need a few module writers to begin to adopt using a basic readme format for their modules. I''ll put my neck on the line, and say I''ll the write the damn readmes if you want! ...... Actually, I think that''s what this needs - Talk is cheap, action is priceless -- Maybe two or three examples in the wild will help to get this moving. --- Latest Article :- The Puppet Module Tool The Puppet Apprentice :- http://puppetnewbie.blogspot.com Follow me on twitter :- http://twitter.com/mritguru Puppet #tags on twitter :- #puppet #puppetforge IRC :- itguru ON irc.freenode.org (feel free to say hi!) -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On 5/30/2010 4:56 PM, Gabriel - IP Guys wrote:> Just a idea to float out here among puppet forge users, > > Can we have a readme standard? For example, we could have a format like > the following > > # Developer - Bob@example.com > # URL http://forge.puppetlabs.com/bob/packagename > # > # Description: > # This does module will install packagename on node.example.com, > # and provide this feature > # > # Example usage: > # node testnode.example.com { > # > # include packagename > # } > > If the developers added that to the their modules, that would be great > for the new guys :) Just something for everyone to think about.Hi, [sorry for butting in late] I''d prefer to have all this metadata in Modulefile (and metadata.json). This could include author info, copyright, license, readme, changelog, and so on. This way the information is machine readable and human writeable and the forge site can automatically use this to populate the web interface, instead of having to duplicate the data on upload. I''ve already posted a bug about this: http://projects.reductivelabs.com/issues/3876 Please watch it to help prioritise it. Best Regards, David -- dasz.at OG Tel: +43 (0)664 2602670 Web: http://dasz.at Klosterneuburg UID: ATU64260999 FB-Nr.: FN 309285 g FB-Gericht: LG Korneuburg -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
----- "David Schmitt" <david@dasz.at> wrote:> I''d prefer to have all this metadata in Modulefile (and > metadata.json). This could include author info, copyright, license, readme, changelog, > and so on. This way the information is machine readable and human > writeable and the forge site can automatically use this to populate > the web interface, instead of having to duplicate the data on upload.+1, structured data ftw. -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
> > > +1, structured data ftw. >Ditto. Takes Gabriel''s intent of accurately describing modules and makes it machine-parsable. J.> > -- > You received this message because you are subscribed to the Google Groups > "Puppet Users" group. > To post to this group, send email to puppet-users@googlegroups.com. > To unsubscribe from this group, send email to > puppet-users+unsubscribe@googlegroups.com<puppet-users%2Bunsubscribe@googlegroups.com> > . > For more options, visit this group at > http://groups.google.com/group/puppet-users?hl=en. > >-- Julian Simpson Software Build and Deployment http://www.build-doctor.com http://twitter.com/builddoctor -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
"Gabriel - IP Guys" <Gabriel@impactteachers.com> writes:> "Gabriel - IP Guys" <Gabriel@impactteachers.com> writes: >> [Mr Gabriel Says ...] >>> +1 - It seems that some work has already been done to make a standard,This would have been so much easier if you used standard quoting rather than the custom "[Mr Gabriel Says]" stuff, or just top-posted. :) Anyway, I fixed the quotation by hand this time, but I would honestly have preferred top-quoting. It would have been less hard work.>>> write scripts, and automate stuff!), but it would be nice to get a little >>> traction in this area. If I have to bug that cr*p out of the module writers, >>> then that''s something I''m prepared to do. >> >> You would probably get better results, generally speaking, by ensuring that >> there are good, standard documents about how to do this visible to community >> members. > > Are you suggesting that I publish a quick document on how to do a readme?Yup. (Among other things that should be in the document. :)> A document, on how to write a document? Well, if that what it takes to get > people working from the same page, then sure I''ll do it.How else do you expect people to know what they should be doing to structure the document? Unless you can tell someone how to do it before they write their documentation (and we ever hear from them), they would have to re-write stuff to conform to the standard otherwise. :)> (Didn''t I do that with the example posting? Maybe a blog post to go with it > would help - Or an open posting to this list? Ideas?I would strongly suggest you look to get it integrated with the other "how to write a module" documentation. See, for example, the existing puppet documentation and all, or the perlmodstyle guide, for how these flow. This post is great, but in two weeks who will ever see it? A blog is the same thing, ephemeral. Sure, great posts get referenced for a while, but they don''t live as long as real documentation.> To be honest with you, I don''t see what is so hard to grasp, it''s just one > more point on the checklist before releasing a module, take 20 seconds to > write a README that explains how to use this module, where it came from, and > who made it.Ah, but you don''t just want that, you want them to follow a reasonable style, to include certain details, and so forth. Also, you wanted to be successful at doing that. ;) [...]> Developing a standard is fine, and I''ll ''vote'' for that anyday of the week, > but this is a request to help those coming into this community.You have no obligation to do anything. I tell you, though, that if you don''t go ahead and put in the work — and no one else does either — I would put money on the fact that this doesn''t happen. Good programing practices, and communities, don''t happen in a vacuum. This is a chance you have to help one happen, but you (naturally) have no obligation. (Also, obviously, this is /my opinion/ about what will help. :) [...]> Look to be honest, we just need a few module writers to begin to adopt using > a basic readme format for their modules.My essential point is that this is a nice idea, but you will get better results doing something a bit more formal. In my experience, obviously.> I''ll put my neck on the line, and say I''ll the write the damn readmes if you > want!Personally, I don''t care that much. It would be nice, and probably help the puppet community, but I haven''t the time to write the standards or push for it right now. Now, if you *do* put in the work then, hey, you get to set the standard.> ...... Actually, I think that''s what this needs - Talk is cheap, action is > priceless*nod* Daniel -- ✣ Daniel Pittman ✉ daniel@rimspace.net ☎ +61 401 155 707 ♽ made with 100 percent post-consumer electrons -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
This is why we need a standard! People have different ways of doing things - Sorry Dan! :) -----Original Message----- From: puppet-users@googlegroups.com [mailto:puppet-users@googlegroups.com] On Behalf Of Daniel Pittman Sent: 02 June 2010 14:08 To: puppet-users@googlegroups.com Subject: Re: [Puppet Users] Puppet Forge Readme standard? "Gabriel - IP Guys" <Gabriel@impactteachers.com> writes:> "Gabriel - IP Guys" <Gabriel@impactteachers.com> writes: >> [Mr Gabriel Says ...] >>> +1 - It seems that some work has already been done to make a standard,This would have been so much easier if you used standard quoting rather than the custom "[Mr Gabriel Says]" stuff, or just top-posted. :) -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.