diff --git a/language/module.md b/language/module.md new file mode 100644 index 0000000..222178f --- /dev/null +++ b/language/module.md @@ -0,0 +1,69 @@ +# Puppet Module Schema + +This document describes allowed (optional) and required files and directories in +a Puppet Module Release. + +## What is a Puppet Module + +A module in the sense of this document is a compressed tar archive. It is +usually distributed via [forge.puppet.com](https://forge.puppet.com/). A module +is usually developed in a git repository. Some files in the git repository are +only used for development and testing. They should not be released. + +Common files often seen in a vcs repository that are used for development but +shall not be released: + +`/spec`, `/Rakefile`, `/Gemfile`, `/.gitignore`, `/.github/`, `/.devcontainer`, `/Dockerfile` + +Note that above are just examples and not a complete list. The goal of this +document is to provide an allowlist (*for a module release, not a VCS repo*), +not a denylist. + +The official +[Puppet documentation](https://www.puppet.com/docs/puppet/latest/modules_fundamentals.html) +already explains what a module is and what it can contain. + +| Directories and Files | Purpose | +|-----------------------|---------| +| `/manifests/` | contains Puppet code | +| `hiera.yaml` | Can define a Hiera configuration for Hiera data within this module | +| `/data/` | If the module has a `hiera.yaml`, the related data has to be within `/data/` | +| `/templates/` | Stores [epp](https://www.puppet.com/docs/puppet/latest/lang_template_epp.html) (preferred) or [erb](https://www.puppet.com/docs/puppet/latest/lang_template_erb.html) templates | +| `/files/` | Static files that Puppet code within the module will distribute | +| `/examples/` | Example Puppet snippets that explain how to use the module. They can be used within acceptance tests | +| `/facts.d/` | [External facts](https://www.puppet.com/docs/puppet/latest/external_facts.html) that are synced via [pluginsync](https://www.puppet.com/docs/puppet/latest/plugins_in_modules.html) | +| `/lib/facter/` | Contains custom facts | +| `/lib/puppet/type/` | Custom types | +| `/lib/puppet/provider/` | Custom provider for one or multiple types | +| `/lib/puppet/functions/` | Modern functions in Ruby for the new API | +| `/lib/puppet/parser/functions/` | Legacy functions in Ruby | +| `/lib/puppet_x/` | Custom Ruby modules to extend types, providers, functions or facts | +| `/lib/augeas/lenses/` | Custom [Augeas](https://augeas.net/) lenses | +| `/functions/` | Can contain [functions written in Puppet DSL](https://www.puppet.com/docs/puppet/latest/lang_write_functions_in_puppet.html) | +| `/metadata.json` | Metadata file that describes the module based on [a schema](https://www.puppet.com/docs/puppet/latest/modules_metadata.html) | +| `/README` | A README that describes what the module does. It's best practice to add a file extension like `.md`, `.rst` when a markup language is used | +| `/LICENSE` | `/metadata.json` specifies a license. The license text needs to be distributed in a LICENSE file. It can have a suffix if a markup language is used | +| `/CHANGELOG` | A Changelog that's updated for every release. A new release should not alter existing changelog entries. It can have a suffix if a markup language is used | +| `/docs/` | Directory for additional documentation | +| `/REFERENCE.md` | [puppet-strings](https://www.puppet.com/docs/puppet/latest/puppet_strings.html) based documentation in markdown, updated on each release | +| `/locales/` | Used for i18n support, can contain translated strings | +| `/scripts/` | Distribute a script for bolt?? | +| `/tasks/` | Contains [Tasks for Bolt](https://www.puppet.com/docs/bolt/latest/tasks.html) | +| `/plans/` | Contains [Plans for Bolt](https://www.puppet.com/docs/bolt/latest/plans) | +| `/types/` | Contains [type aliases](https://www.puppet.com/docs/puppet/latest/lang_type_aliases.html) | +| `/bolt_plugin.json` | The file can contain metadata about [a Bolt plugin](https://www.puppet.com/docs/bolt/latest/writing_plugins.html#module-structure) | + +Mandatory are: +* `/metadata.json` +* `/README` +* `/LICENSE` +* `/CHANGELOG` + +In the past, modules sometines contained a `/Modulefile`. It contained metadata +about the module. The `/metadata.json` is the successor. A module can now only +have a `/metadata.json`. It must not have a `/Modulefile`. + +The `/REFERENCE.md` file is optional. It's generated by puppet-strings. Some +modules might use a different tool for documentation (and then cannot generate +a `REFERENCE.md`). If a `/REFERENCE.md` is present in the release, it has to be +up to date.