What does it mean to be Puppet Approved?
Table of Contents
- Maintenance and lifecycle
- Puppet versions and features
Puppet Approved modules must adhere to the following criteria. These modules meet our standards for being well-written, reliable, and actively maintained.
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.
Each section is broken down into three parts: Requirements - describes what a Puppet Approved module must and should comply to. Resources - provides documentation and tools to help you improve your module. Validation - specifies how Puppet validates Puppet Approved modules.
Modules that are developed with a consistent style are more approachable for users and contributors. They are easier to refactor and often more future-proof.
Puppet Approved modules must not produce errors or warnings when
pdk validate is run. Puppet Approved modules must be well-written by following common coding practices and presenting user-friendly interfaces. The Puppet team will also manually review some or all of your module code.
Use PDK to run
pdk validate. This validates a module's metadata, Puppet and Ruby code, syntax, and style.
Almost more important 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 limits usage.
Puppet Approved modules must have a README and should conform to our documentation standards (following the README template for example).
Example usage and realistic use-cases accompanied by example code must be documented in the README. All classes, defined types, parameters, and resources used in module should be well documented. You can use Puppet Strings to generate these directly from your code.
The module must contain an examples directory — with real-world example manifests that help users incorporate the module into their environment.
As Puppet Approved matures, we will routinely raise the standards for module documentation.
The Puppet team will review all documentation.
3. Maintenance and lifecycle
Ideal Puppet Approved modules are regularly maintained by a diverse group of people.
Puppet Approved modules must be regularly maintained and have received updates in the last 6 months, where applicable. Modules should not have more than one month gap between the Puppet Forge and VCS. They should be contributed to by more than one person from more than one organization. They should be present on the Forge for at least 3 months.
- Include a contributing guide with your module for future contributors. See puppetlabs-ntp for an example.
- Publish to the Forge quickly and easily with the following tools:
We will look at the development history of the project — as a well as a list of contributors — by following the project URL link on the 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.
We want Puppet Approved modules to make it simple for users 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.
Puppet Approved modules should not conflict with widely-used module names or Ruby code namespaces and modules must not overlap existing puppet approved module functionality too closely.
- Check the Puppet Forge for existing modules to contribute to.
The Puppet team attempts to limit duplicate modules for a given technology. Multiple modules are acceptable as long as they solve the problem in a different way, or offer functionality beyond existing Puppet Approved modules. Modules are regularly compared to others on the Forge.
Thorough and accurate module metadata helps users find your module on the Forge, and ensures that it takes advantage of all the features the 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 — including compatibility metadata for Puppet and OS versions that the module is compatible with, issues_url metadata, and project_page metadata — and should provide accurate information for all other fields. You must state known dependencies.
- Geppetto has a built-in module metadata editor.
- jsonlint.com, syntastic.vim and jacinto.vim help you validate and write JSON.
- Module metadata linter to lint module metadata.
- Module publishing documentation.
The Forge's API service is authoritative for any modules metadata. We query the REST endpoint for a module and examine its metadata. For example,
Versioning your module according to SemVer rules lets users know what to expect when they upgrade the module. This keeps it predictable and consistent.
Puppet Approved modules must be versioned according to SemVer v1 rules. Candidate releases must be >= 1.0.0. Puppet Approved modules must contain a CHANGELOG.md detailing the changes for each release.
- SemVer v1 website.
- https://keepachangelog.com/en/1.0.0/ website - for suggestions on changelog design.
We evaluate a module's version against SemVer v1 rules and require a version greater or equal to 1.0.0 to qualify for Puppet Approved. We review the changelog for accurate release version increments due to bugfixes, features, and breaking changes.
Modules being used in production will often go through stringent testing to prove their reliability and fitness for deployment.
Puppet Approved modules must prove their reliability with rspec-puppet unit tests and/or beaker acceptance tests. They should have at least one test for each class, define, task, type, provider, fact, and example use-case.
- PDK — helps generate and execute unit tests.
- beaker - an acceptance framework for Puppet modules, capable of testing against both Puppet Enterprise and the open-source Puppet projects.
- rspec-puppet - a good framework for unit testing Puppet modules.
We will manually run your tests or inspect your public CI results.
9. Puppet versions and features
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 and must be compatible with the latest major-release series of puppet-agent.
pdk validate- pdk v1.5 allows you to validate modules against different versions of Puppet.
puppet config print parserwill return