bolt-project.yaml documentation for moudles is incomplete

[Sharpie]

Describe the Change You Would Like

The modules list in bolt-project.yaml is incompletely documented:

https://puppet.com/docs/bolt/latest/bolt_project_reference.html#modules

Each entry in the list must conform to the specification of either a Forge module or a git module:

https://github.com/puppetlabs/bolt/blob/3.8.0/lib/bolt/module_installer/specs.rb#L51-L52

In order to conform to a specification, there are keys the entry must provide and keys the entry may provide:

• https://github.com/puppetlabs/bolt/blob/main/lib/3.8.0/module_installer/specs/forge_spec.rb#L15-L16
• https://github.com/puppetlabs/bolt/blob/3.8.0/lib/bolt/module_installer/specs/git_spec.rb#L15-L16

The documentation should cover each of these keys and describe what effect they have along with which are required. For example, it is not obvious from the existing documetation that the ref key for a git module must be provided and that ref may be set to a branch name.

Additionally, the error message printed when a module does not conform to either specification links to https://pup.pt/bolt-modules as a source of more information:

$ bolt module install
Installing project modules

Invalid module specification:
name: tfc
git: https://github.com/Sharpie/puppet-tfc

To read more about specifying modules, see https://pup.pt/bolt-modules

This documentation page only contains a minimal example of specifying a Forge module, which does not cover module specification in depth. Git modules are not covered at all.

[beechtom]

@Sharpie This information is documented on the Installing modules page. The short link was made when that information was on this page, but we missed updating it when we made the new page. I've updated it to point to the doc with more detail.

I'll get a PR up to update the bolt-project.yaml ref page to point to this doc as well.