Add Module layout specification

[bastelfreak]

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

[ekohl]

In general I'm in favor of a specific list of what's allowed. I'd suggest the make sure puppet-modulebuilder has this list built in. It may be a breaking change to switch to it, so perhaps at first it should be opt-in.

Short term I think this may work for .pmtignore, if it follows gitignore:

# Ignore everything
*

# except
!manifest/**/*.pp
!metadata.json
!README*
!CHANGELOG*
!LICENSE*
...

[david22swan]

Aside from that one comment this LGTM.
Would probably need a few more eyes on it before merging though, considering the importance.

[donoghuc]

This is a good start. i would like to see bolt_plugin.json added as well https://www.puppet.com/docs/bolt/latest/writing_plugins.html but having this as a point of reference will be helpful.

[bastelfreak]

@donoghuc thanks for the hint, I added it.

[ekohl]

I wonder if it's useful to show a tree form.

$ mkdir -p docs examples facts.d files functions lib/facter lib/puppet/{type,provider,functions,parser/functions,puppet_x,augeas/lenses} locales plans scripts tasks templates types
$ touch CHANGELOG LICENSE README REFERENCE.md bolt_plugin.json hiera.yaml metadata.json
$ tree
.
├── bolt_plugin.json
├── CHANGELOG
├── docs
├── examples
├── facts.d
├── files
├── functions
├── hiera.yaml
├── lib
│   ├── facter
│   └── puppet
│       ├── augeas
│       │   └── lenses
│       ├── functions
│       ├── parser
│       │   └── functions
│       ├── provider
│       ├── puppet_x
│       └── type
├── LICENSE
├── locales
├── manifests
├── metadata.json
├── plans
├── README
├── REFERENCE.md
├── scripts
├── tasks
├── templates
└── types

24 directories, 7 files

On the console it helpfully shows directories as blue and files as white so it's even easier to understand.

I'd even consider a separate chapter for each file/directory describing it. Some descriptions are already quite long, but many of them could be further enhanced with references to official documentation. For example, files can explain the puppet:// mechanism, but also the file() function. And that the Puppetserver will serve the files as a fileserver. Similarly, for lib which things are synced to agents.

[Ramesh7]

Just a thought : as we have consider bolt scenario here so should we consider below 2 files also to be part of specification ?

• Puppetfile
• bolt-project.yaml

[donoghuc]

@Ramesh7 no those are for bolt projects. A bolt project is not a module. This spec is for modules.

[jstraw]

I know it says at the end .md/,rst, would it make sense to do README.md by default, given that is the community standard.

[jstraw]

should we semver this? so 0.1.0?

[bastelfreak]

at other places Puppet only used major versions for schema. For example for the report format. I'm fine with everything here.