CONTRIBUTING.md

Contributing

This module has grown over time based on a range of contributions from people using it. If you follow these contributing guidelines, your patch will likely make it into a release a little quicker.

1. Fork and clone the repository.

2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate.

3. Create a new feature branch.

4. Add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, please add a test.

5. Make the test pass.

6. Commit your changes, push the feature branch to your fork, and submit a pull request.

Development environment

This project is managed with PDK and based on the PDK template.

Many files in this repository are generated by PDK, based on the configuration in the .sync.yml file. Changes to files generated by PDK should only go through changes to the .sync.yml and then be updated via pdk update.

For your convenience, the pdk is also installed by the Gemfile in this repository and Bundler. Once the Bundler project is properly configured and installed, it can be called via bundler exec pdk.

Bundler manages the development tools and library Ruby dependencies via the Gemfile, which is generated by the PDK in this project.

Setting up Ruby dependencies with Bundler

PDK provides a couple of environment variables to modify the versions of Puppet, Facter, and Hiera, which can be set before fetching all dependencies.

For example:

export PUPPET_GEM_VERSION="~> 7.17.0"
export FACTER_GEM_VERSION="~> 2.5.7"
export HIERA_GEM_VERSION="~> 3.9.0"

You might want to specify a project local directory to fetch all dependencies into before installing all of them:

bundle config set --local path vendor/bundle

Installing the Ruby dependencies is done by:

bundle install

Afterward, you have access to the PDK:

bundle exec pdk

Bundler also installs other tools like rake, a Make-like program implemented in Ruby, which gives convenient access to common development tasks:

bundle exec rake --tasks

Checks and tests

Syntax and style checks

After setting up the development environment, you have access to static code and style checks. For instance, checking the Puppet and Ruby code can be done like this:

bundle exec rake validate lint check rubocop

Additionally check the Markdown files with markdownlint:

bundle exec rake markdownlint

Unit test

The unit tests are implemented in spec/unit/ and can be run as follows:

bundle exec rake spec

To execute the unit tests in parallel, run:

bundle exec rake parallel_spec

Acceptance tests

The unit tests just check if the code runs and contains the required resource definitions. In those tests, the code is not used to provision real systems. For this litmus is used.

Litmus fires up fresh containers or virtual machines, applies this Puppet module and then checks if it behaved as expected by running a series of tests on it. Those tests are implemented in spec/acceptance/.

Litmus is normally run in a GitHub action on each pull request. But it is also possible to run it on a local machine. The following examples use the Docker provisioner to provision a Debian 11 system with Puppet 7. For other options see the litmus documentation and the list of available images.

First, a machine has to be provisioned. To use the Docker provisioner, you need to have Docker installed and properly configured. If you have some issues doing that, you can also use the GitHub action runners with a draft pull request.

bundle exec rake 'litmus:provision[docker,litmusimage/debian:11]'

Afterward, the Puppet agent has to be installed:

bundle exec rake 'litmus:install_agent[puppet7-nightly]'

Then the module is installed on the provisioned system:

bundle exec rake 'litmus:install_module'

Then the acceptance test can be executed:

bundle exec rake 'litmus:acceptance:parallel'

And finally, the provisioned system can be removed:

bundle exec rake 'litmus:tear_down'