Add Module layout specification

This document describes all files/directories that are allowed or
mandatory within a module. The forge can use it as an allowlist and
filter other files out. r10k/code-manager can use it as an allowlist as
well when modules are pulled from version controll systems like github
(similar to the `--exclude-spec` option in r10k).

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.