README

  I. About

    This project helps you to create high quality Puppet modules in a fast and
    comfortable way. Main targets are to boost your efficiency and Puppet code
    quality. Use it if you want to get Puppet module skeletons with:

    - tidy and easily extendable structure
    - good documentation
    - source code which follows the official style guide [1]
    - parameterized classes [2]

    Just call the "new module wizard", answer the questions and start editing.
    If you want to get an impression of what to expect, you may have a look at
    the "puppet-boilerplate-modules-example-content" [3] repository.

    [1] <http://docs.puppetlabs.com/guides/style_guide.html>
    [2] <http://docs.puppetlabs.com/guides/parameterized_classes.html>
    [3] <http://j.mp/X3GnY9>



  II. Usage

    1. Clone the repository:
       $ git clone git://github.com/syn-systems/puppet-boilerplate-modules.git

    2. Call the wizard to create the module skeleton for a new module:
       $ ./puppet-boilerplate-modules/newmodule.sh
       You can provide the answers by using parameters. Use "newmodule.sh -h" to
       get a listing.

    3. ???

    4. Profit!!!

    The "puppet-boilerplate-modules-example-content" [1] repository is your
    friend if you need more help. It provides example modules including detailed
    creation transcripts.

    [1] <http://j.mp/X3GnY9>



  III. How to add a new boilerplate

    The existing boilerplates may not fit your needs. Therefore it might make
    sense to add your own boilerplate. The newmodule.sh will list every
    directory as boilerplate if it can find a "/manifests/init.pp" file in it.
    So all you have to do is:

    1. Create a directory for the new boilerplate (name: [a-zA-Z0-9-_] only).

    2. Optional but recommended: put a DESCRIPTION file into the boilerplate's
       root dir. The newmodule.sh will show the file content when listing the
       available boilerplates as description then.

    3. Add everything your boilerplate needs. Please note that all files have
       to be UTF-8 encoded so take care your editor can handle UTF-8.

    4. The newmodule.sh executes different actions when creating a new skeleton.
       It copies the chosen boilerplate to the specified target dir, renames
       files/dirs and does some string replacements to create a useful module
       skeleton. You can use placeholders for your new boilerplate and
       newmodule.sh inserts the real data it asked the user for.

       - The following case sensitive string replacements will be done in every
         file of your boilerplate:
           John Doe               gets replaced with   the author name
           john.doe@example.com   gets replaced with   the author email address
           YYYY                   gets replaced with   the current year
           boilerplate            gets replaced with   the module name

       - "boilerplate" gets replaced with the module name in every file name and
          dir name. Example: If the user told newmodule.sh that the name for the
          new module is "test", the file "/manifests/fooboilerplatebar.pp" would
          be renamed into "/manifests/footestbar.pp".



  IV. How to remove a boilerplate

    The newmodule.sh will list every directory as boilerplate if it can find a
    "/manifests/init.pp" file in it. So you may just delete the boilerplate's
    directory to remove it or e.g. rename the boilerplate's "/manifests/init.pp"
    to prevent its listing.



  V. Contact

    If you think you have found a bug or have a useful idea (a.k.a. "feature
    request"), create an issue [1] on GitHub (preferred), or contact us by
    mail [2].

    Feel free to submit patches as GitHub pull requests (preferred) or by mail
    as well. However, please try to respect the official style guide [3] as this
    project follows its rules.

    [1] <https://github.com/syn-systems/puppet-boilerplate-modules/issues>
    [2] SYN Systems <puppet@dev.syn-systems.com>
    [3] <http://docs.puppetlabs.com/guides/style_guide.html>



  VI. Other notes

    If you like this free project, you might buy us a coffee [1], or get some
    cool QR Code merchandise [2]. Thank you! :-)

    Do not hesitate to contact SYN Systems [3] if you need professional support
    or if you think we are the ones to get your project done.

    [1] <http://syn-systems.com/donate/puppet-modules/>
    [2] <http://goqr.me/>
    [3] <http://syn-systems.com/>