The PDK Templates is the default templates repository for use with the Puppet Development Kit, within which we have defined all the templates for the creation and configuration of a module. Look into these directories to find the templates:

• moduleroot templates get deployed on new module, convert and update; use them to enforce a common boilerplate for central files.
• moduleroot_init templates get only deployed when the target module does not yet exist; use them to provide skeletons for files the developer needs to modify heavily.
• object_templates templates are used by the various new ... commands for classes, defined types, etc.

PDK builds the configuration of the module by reading a set of default configuration from config_defaults.yml and merging it with the contents of .sync.yml from module's root directory, if exists. Top-level keys of the resulting hash correspond to target files or represent a global configuration. Global configuration will be merged with the configuration hash for a particular target file. This allows a module developer to override/amend the configuration by putting new values into .sync.yml. A knockout prefix may be applied to elements within .sync.yml to remove elements from the default set. Target files are created by rendering a corresponding template which is referring its configuration via the @configs hash. The data for a target file may include delete: true or unmanaged: true in order to have the particular file removed from the module or left unmanaged, respectively.

• Basic usage
• Values of config_defaults
• Making local changes to the Template
• Further Notes

Templates like this one can be used in conjunction with the PDK. As default the PDK itself uses the templates within this repository to render files for use within a module. Templates can be passed to the PDK as a flag for several of the commands.

pdk convert --template-url https://github.com/puppetlabs/pdk-templates

Please note that the template only needs to be passed in once if you wish to change it, every command run on the PDK will use the last specified template. For more on basic usage and more detailed description of the PDK in action please refer to the PDK documentation.

The following is a description and explaination of each of the keys within config_defaults. This will help clarify the default settings we choose to apply to pdk modules.

A namespace for settings that affect multiple templates

A .gitattributes file in your repo allows you to ensure consistent git settings.

A .gitignore file in your repo allows you to specify intentionally untracked files to ignore.

Gitlab CI is a continuous integration platform that is free for all open source projects hosted on Github and Gitlab.com, it also has a self-hosted option that is free as well. We can trigger automated pipelines with ever change to our code base in the master branch, other branches, tags, or additional triggers. Gitlab CI uses a .gitlab-ci.yml file in the root of your repository tell Gitlab CI what jobs to run when in the pipeline.

ruby_versions:
  2.4.9:
    except:
      unit:
      - tags
      - master

ruby_versions:
  2.4.9:
    except:
      unit:
        refs:
        - tags
        - master
        variables:
        - $CI_COMMIT_MESSAGE =~ /[skip[ _-]tests?]/i

A .pdkignore file in your repo allows you to specify files to ignore when building a module package with pdk build.

Travis CI is a hosted continuous integration platform that is free for all open source projects hosted on Github. We can trigger automated builds with every change to our code base in the master branch, other branches or even a pull request. Travis uses a .travis.yml file in the root of your repository to learn about your project and how you want your builds to be executed.

YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.

AppVeyor is a hosted, distributed continuous integration service used to build and test projects hosted on GitHub by spinning up a Microsoft Windows virtual machine. AppVeyor is configured by adding a file named appveyor.yml, which is a YAML format text file, to the root directory of the code repository.

Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax within the Rakefile, present in the root directory of the code repository. Within modules context Rake tasks are used quite frequently, from ensuring the integrity of a module, running validation and tests, to tasks for releasing modules.

Key	Description
requires	A list of hashes with the library to 'require', and an optional 'conditional'.
changelog_user	Sets the github user for the change_log_generator rake task. Optional, if not set it will read the author from the metadata.json file.
changelog_project	Sets the github project name for the change_log_generator rake task. Optional, if not set it will parse the source from the metadata.json file
changelog_since_tag	Sets the github since_tag for the change_log_generator rake task. Required for the changlog rake task.
changelog_version_tag_pattern	Template how the version tag is to be generated. Defaults to 'v%s' which eventually align with tag_pattern property of puppet-blacksmith, thus changelog is referring to the correct version tags and compare URLs.
github_site	Override built-in default for public GitHub. Useful for GitHub Enterprise and other. (Example: github_site = https://git.domain.tld)
github_endpoint	Override built-in default for public GitHub. Useful for GitHub Enterprise and other. (Example: github_endpoint = https://git.domain.tld/api/v4)
gitlab	Allows to work with GitLab (Pending ). (Example: gitlab = true # Boolean default is false)
default_disabled_lint_checks	Defines any checks that are to be disabled by default when running lint checks. As default we disable the --relative lint check, which compares the module layout relative to the module root. Does affect .puppet-lint.rc.
extra_disabled_lint_checks	Defines any checks that are to be disabled as extras when running lint checks. No defaults are defined for this configuration. Does affect .puppet-lint.rc.
extras	An array of extra lines to add into your Rakefile. As an alternative you can add a directory named rakelib to your module and files in that directory that end in .rake would be loaded by the Rakefile.
linter_options	An array of options to be passed into linter config. Does affect .puppet-lint.rc.
linter_fail_on_warnings	A boolean indicating if the linter should exit non-zero on warnings as well as failures. Does affect .puppet-lint.rc.

RuboCop is a Ruby static code analyzer. We use Rubocop to enforce a level of quility and consistancy within Ruby code. Rubocop can be configured within .rubocop.yml which is located in the root directory of the code repository. Rubocop works by defining a sanitized list of cops that'll cleanup a code base without much effort, all of which support autocorrect and that are fairly uncontroversial across wide segments of the Community.

A Gemfile is a file we create which is used for describing gem dependencies for Ruby programs. All modules should have an associated Gemfile for installing the relevant gems. As development and testing is somewhat consistant between modules we have used the template to define a set of gems relevant to these processes.

Within each Gem group defined using the options above one or more gem item definitions may be listed in an array. Each item in that array must be a gem item hash.

The spec/default_facts.yml file contains a list of facts to be used by default when running rspec tests

The spec/spec_helper.rb file contains setup for rspec tests

While we provide a basic template it is likely that it will not match what you need exactly, as such we allow it to be altered or added to through the use of the .sync.yml file.

Values can be added to the data passed to the templates by adding them to your local .sync.yml file, thus allowing you to make changes such as testing against additional operating systems or adding new rubocop rules.

To add a value to an array simply place it into the .sync.yml file as shown below, here I am adding an additional unit test run against Puppet 4:

.travis.yml:
  includes:
    - env: PUPPET_GEM_VERSION="~> 4.0" CHECK=parallel_spec
      rvm: 2.1.9

Values can be removed from the data passed to the templates using the knockout prefix --- in .sync.yml.

To remove a value from an array, prefix the value ---. For example, to remove 2.5.1 from the ruby_versions array in .travis.yml:

.travis.yml:
  ruby_versions:
    - '---2.5.1'

To remove a key from a hash, set the value to ---. For example, to remove the ipaddress fact from spec/default_facts.yml:

spec/default_facts.yml:
  ipaddress: '---'

To add a custom internal puppet-lint plugin served from an internal Rubygems source, add an entry similar to the following in .sync.yml file and run pdk update.

Gemfile:
  optional:
    ':development':
      - gem: 'puppet-lint-my_awesome_custom_module'
        version: '>= 2.0'
        source: 'https://myrubygems.example.com/'

To enable the ability to run Beaker system tests on your module, add the following entry to your .sync.yml and run pdk update.

Gemfile:
  required:
    ':system_tests':
      - gem: 'puppet-module-posix-system-r#{minor_version}'
        platforms: ruby
      - gem: 'puppet-module-win-system-r#{minor_version}'
        platforms:
          - mswin
          - mingw
          - x64_mingw
.gitlab-ci.yml:
  bundler_args: --with system_tests --path vendor/bundle --jobs $(nproc)
  beaker: true
appveyor.yml:
  appveyor_bundle_install: "bundle install --jobs 4 --retry 2 --with system_tests"

Please note that the early version of this template contained only a 'moduleroot' directory, and did not have a 'moduleroot_init'. The PDK 'pdk new module' command will still work with templates that only have 'moduleroot', however the 'pdk convert' command will fail if the template does not have a 'moduleroot_init' directory present. To remedy this please use the up to date version of the template.