Modules

Develop your module using consistent code and module structures to make it easier to update and maintain.

Versioning

Your module must be versioned, and have metadata defined in the metadata.json file.

We recommend semantic versioning.

Semantic versioning, or SemVer, means that in a version number given as x.y.z:

  • An increase in 'x' indicates major changes: backwards incompatible changes or a complete rewrite.

  • An increase in 'y' indicates minor changes: the non-breaking addition of new features.

  • An increase in 'z' indicates a patch: non-breaking bug fixes.

Module metadata

Every module must have metadata defined in the metadata.json file.

Your metadata should follow the following format:

{
  "name": "examplecorp-mymodule",
  "version": "0.1.0",
  "author": "Pat",
  "license": "Apache-2.0",
  "summary": "A module for a thing",
  "source": "https://github.com/examplecorp/examplecorp-mymodule",
  "project_page": "https://github.com/examplecorp/examplecorp-mymodule",
  "issues_url": "https://github.com/examplecorp/examplecorp-mymodules/issues",
  "tags": ["things", "stuff"],
  "operatingsystem_support": [
    {
      "operatingsystem":"RedHat",
      "operatingsystemrelease": [
        "5.0",
        "6.0"
      ]
    },
    {
      "operatingsystem": "Ubuntu",
      "operatingsystemrelease": [ 
        "12.04",
        "10.04"
     ]
    }
  ],
  "dependencies": [
    { "name": "puppetlabs/stdlib", "version_requirement": ">= 3.2.0 <5.0.0" },
    { "name": "puppetlabs/firewall", "version_requirement": ">= 0.4.0 <5.0.0" },
  ]
}
For additional information regarding the metadata.json format, see Adding module metadata in metadata.json.

Dependencies

Hard dependencies must be declared explicitly in your module’s metadata.json file.

Soft dependencies should be called out in the README.md, and must not be enforced as a hard requirement in your metadata.json. A soft dependency is a dependency that is only required in a specific set of use cases. For an example, see the rabbitmq module.

Your hard dependency declarations should not be unbounded.

README

Your module should have a README in .md (or .markdown) format. READMEs help users of your module get the full benefit of your work.

The Puppet README template offers a basic format you can use. If you create modules with Puppet Development Kit or the puppet module generate command, the generated README includes the template. Using the .md/.markdown format allows your README to be parsed and displayed by Puppet Strings, GitHub, and the Puppet Forge.

You can find thorough, detailed information on writing a great README in Documenting modules, but in general your README should:

  • Summarize what your module does.

  • Note any setup requirements or limitations, such as "This module requires the puppetlabs-apache module and only works on Ubuntu."

  • Note any part of a user’s system the module might impact (for example, “This module overwrites everything in animportantfile.conf.”).

  • Describe how to customize and configure the module.

  • Include usage examples and code samples for the common use cases for your module.

Documenting Puppet code

Use Puppet Strings code comments to document your Puppet classes, defined types, functions, and resource types and providers. Strings processes the README and comments from your code into HTML or JSON format documentation. This allows you and your users to generate detailed documentation for your module.

Include comments for each element (classes, functions, defined types, parameters, and so on) in your module. If used, comments must precede the code for that element. Comments should contain the following information, arranged in this order:

  • A description giving an overview of what the element does.

  • Any additional information about valid values that is not clear from the data type. For example, if the data type is [String], but the value must specifically be a path.

  • The default value, if any, for that element,

Multiline descriptions must be uniformly indented by at least one space:

# @param config_epp Specifies a file to act as a EPP template for the config file.
#  Valid options: a path (absolute, or relative to the module path). Example value: 
#  'ntp/ntp.conf.epp'. A validation error is thrown if you supply both this param **and**
#  the `config_template` param.

If you use Strings to document your module, include information about Strings in the Reference section of your README so that your users know how to generate the documentation. See Puppet Strings documentation for details on usage, installation, and correctly writing documentation comments.

If you do not include Strings code comments, you should include a Reference section in your README with a complete list of all classes, types, providers, defined types, and parameters that the user can configure. Include a brief description, the valid options, and the default values (if any).

For example, this is a parameter for the ntp module’s ntp class: package_ensure: 

Data type: String.

Whether to install the NTP package, and what version to install. Values: 'present', 'latest', or a specific version number.

Default value: 'present'.
For more details and examples, see the module documentation guide.

CHANGELOG

Your module should include a change log file called CHANGELOG.md or .markdown. Your change log should:

  • Have entries for each release.

  • List bugfixes and features included in the release.

  • Specifically call out backwards-incompatible changes.

Examples

In the /examples directory, include example manifests that demonstrate major use cases for your module. 

modulepath/apache/examples/{usecase}.pp
The example manifest should provide a clear example of how to declare the class or defined resource type. It should also declare any classes required by the corresponding class to ensure puppet apply works in a limited, standalone manner.

Testing

You can use these community tools to test your code and style: