What does it mean to be Puppet Approved?

Table of Contents

1. Terminology
2. Format
3. Style
4. Documentation
5. Maintenance and Lifecycle
6. License
7. Originality
8. Metadata
9. SemVer
10. Testing
11. 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.

Version 1.0.0.

1. Terminology

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.

2. Format

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.

3. Style

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.

Requirements

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.

Resources

• Puppet Style Guide
• Puppet Development Kit (PDK)

Validation

Use PDK to run pdk validate. This validates a module's metadata, Puppet and Ruby code, syntax, and style.

4. Documentation

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.

Requirements

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.

Resources

• Standard README template.
• Puppet Strings — used to generate the REFERENCE.md file for your module.

Validation

The Puppet team will review all documentation.

5. Maintenance and Lifecycle

Ideal Puppet Approved modules are regularly maintained by a diverse group of people.

Requirements

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.

Resources

• 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:
  • puppet blacksmith CLI publisher
  • puppet forge deployment — this helps you build a travis.ci publishing workflow

Validation

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.

6. License

Requirements

Puppet Approved modules must be licensed and should be licensed under Apache, MIT, or BSD licenses.

Resources

• choosealicense.com can help you pick between software licenses for your project.

Validation

The team at Puppet examines any available license files in the root of your module. They also query the Forge API for the modules license metadata.

7. Originality

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.

Requirements

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.

Resources

• Check the Puppet Forge for existing modules to contribute to.

Validation

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.

8. Metadata

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.

Requirements

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.

Resources

• jsonlint.com, syntastic.vim and jacinto.vim help you validate and write JSON.
• Module metadata linter to lint module metadata.
• Module publishing documentation.

Validation

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, curl 'https://forgeapi.puppet.com/v3/modules/puppetlabs-ntp'

9. SemVer

Versioning your module according to SemVer rules lets users know what to expect when they upgrade the module. This keeps it predictable and consistent.

Requirements

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.

Resources

• SemVer v1 website.
• https://keepachangelog.com/en/1.0.0/ website - for suggestions on CHANGELOG design.

Validation

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.

10. Testing

Modules being used in production will often go through stringent testing to prove their reliability and fitness for deployment.

Requirements

Puppet Approved modules must prove their reliability with rspec-puppet unit tests and/or Beaker or Litmus acceptance tests. They should have at least one test for each class, define, task, type, provider, fact, and example use-case.

Resources

• PDK — helps generate and execute unit tests.
• Litmus - modern acceptance test framework for Puppet modules
• 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.

Validation

We will manually run your tests or inspect your public CI results.

11. 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.

Requirements

Puppet Approved modules must not rely on experimental Puppet features and must be compatible with the latest major-release series of puppet-agent.

Resources

• pdk validate - pdk v1.5 allows you to validate modules against different versions of Puppet.
• puppet config print parser will return current or future.