The following criteria describe characteristics that any Puppet Approved module must adhere to. It's expected that your module operates as documented within the constraints described below.
Puppet Approved criteria are still under development and aren't yet considered stable.
Version 0.1.0.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Failure to meet requirements that specify "MUST", "MUST NOT", or "REQUIRED" will not be accepted into Puppet Approved. Failure to meet requirements that specify "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are acceptable but should be considered suggestions for improvement.
The following documents the criteria used by Puppet Labs when reviewing modules for Puppet Approved. Each section is broken into three parts.
Requirements describes what a Puppet Approved module must and/or should comply to.
Resources provides documentation and tools to help you improve your module.
Validation provides specifics on how Puppet Labs validates Puppet Approved modules, if available.
Modules that are developed with a consistent style are much more approachable for users and contributors. They're easier to refactor and are often more future-proof.
Puppet Approved modules must not produce warnings (exceptions noted in validation section).
- Puppet Labs Style Guide
- puppet-lint cli tool
- puppet-lint guide on resolving each check
- community puppet linter service
Puppet Labs will run the puppet-lint cli tool on your modules manifests, using the following configuration.
- PuppetLint.configuration.fail_on_warnings
- PuppetLint.configuration.send('relative')
- PuppetLint.configuration.send('disable_80chars')
- PuppetLint.configuration.send('disable_class_inherits_from_params_class')
- PuppetLint.configuration.send('disable_class_parameter_defaults')
- PuppetLint.configuration.send('disable_documentation')
- PuppetLint.configuration.send('disable_single_quote_string_with_variables')
- PuppetLint.configuration.ignore_paths = ["spec//*.pp", "pkg//*.pp"]
Almost more critical than the module itself, thorough and readable documentation is the best way to ensure your module is used successfully and contributed to by others. Cutting corners here will limit usage.
Puppet Approved modules must have a README and should conform to our documentation standards (following this README template for example).
Example usage must be documented in the README and classes, defines, parameters, and resources used in the example usage should be completely documented in the README.
As Puppet Approved matures, we will be routinely raising the bar for module documentation.
- Standard README template on the Puppet Labs docs site.
- preview of the puppet strings cli tool.
Validation is based on a human review by the team at Puppet Labs.
Ideal Puppet Approved modules are regularly maintained, by a diverse group of people and don't lag between development and released artifacts.
Puppet Approved modules should be regularly maintained and have received updates in the last 6 months, where applicable. Modules should not have more than 1 month gap between Forge and VCS. They should be contributed to by more than one person or organization.
Include a contributing guide with your module to provide would-be contributors with some guidelines. See puppetlabs-ntp for an example.
Publish to Forge quickly and easily with these tools.
- puppet blacksmith cli publisher
- ghpublisher can help you build a travis.ci publishing workflow
We'll take a look at the development history of the project as a well as a list of contributors by following the Project URL link on Forge.
Puppet Approved modules must be licensed and should be licensed under Apache, MIT, or BSD licenses.
choosealicense.com can help you pick between software licenses for your project.
The team at Puppet Labs will examine any available license file in the root of your module. They will also query the Forge API for the modules license metadata.
Puppet Approved modules are intended to make it simple to find a great module to solve a given automation task. Limiting the number of available choices for a given technology helps simplify the process.
The Puppet Labs team will attempt to limit duplicate modules for a given technology. Multiple modules are acceptable so long as they solve the problem in a sufficiently different way or offer functionality above and beyond existing Puppet Approved modules. The collection of modules will be regularly evaluated against other Forge modules.
Thorough and accurate module metadata helps users find your module on the Puppet Forge and ensures that it takes advantage of all the features Forge offers. The metadata is used throughout; in search filters, module pages and the API service.
Puppet Approved modules must:
- Accurately express every required metadata field.
- Express compatibility metadata for Puppet/PE and OS versions module is compatible with.
- Accurately express issues_url and project_page metadata.
Approved modules should provide accurate information for every metadata field.
- Geppetto has a built-in module metadata editor.
- jsonlint.com, syntastic.vim and jacinto.vim help you validate and write JSON.
- Lint module metadata with this module metadata linter.
- See our module publishing documentation for more.
The Puppet Forge's API service is considered authoritative for any modules metadata. We query the REST endpoint for a module and examine its metadata.
Example: curl 'https://forgeapi.puppetlabs.com/v3/modules/puppetlabs-ntp'
Versioning your module according to SemVer rules sets expectations for users upgrading their version of your module, keeping things predictable and consistent.
Puppet Approved modules must be versioned according to SemVer v1 rules. Candidate releases must be >=1.x.
You can learn more about SemVer v1 at its website.
We evaluate a modules version against SemVer v1 rules and expect a version greater or equal to 1.0.0 to review for Puppet Approved.
As with any module, it’s a universally accepted best practice to test and validate a module prior to deploying in production. In that spirit, Puppet Approved modules:
- Should have rspec-puppet tests for manifests.
- Should have acceptance tests, preferably written with the beaker framework.
- Types, providers, facts, and functions should have at least 1 unit test each.
- rspec-puppet is a really good framework for unit testing Puppet modules.
- beaker is an acceptance framework for Puppet modules, capable of testing against Puppet Enterprise and the open-source Puppet projects.
We'll manually run your tests or inspect your public CI results.
Though we like to move quickly with new Puppet features, Puppet Approved modules must be stable, reliable and ready for production use.
Puppet Approved modules:
- Must not rely on experimental Puppet features (like the future parser or in-module hiera data)
- Must be compatible with the Puppet 3 and Puppet Enterprise 3 series.
- Should not directly call out to an ENC like the hiera() function for example.
-
puppet --version
should return something in the 3.x series. -
puppet config print parser
will returncurrent
orfuture
.