# Contributing

## Reporting Bugs

We welcome error reports and patches to the PDK repository.
If you have discovered an issue, you can raise it [here](https://github.com/puppetlabs/pdk/issues) or reach out to us directly on the [Puppet Community Slack](https://slack.puppet.com/).

In addition if there is something that you do not understand, or a point that you wish to clarify you can start a Discussion [here](https://github.com/puppetlabs/pdk/discussions) or post a question to [puppet-users@groups.google.com](https://groups.google.com/forum/#!forum/puppet-users).

Finally if you have a fix for an issue you can open a PR to resolve it [here](https://github.com/puppetlabs/pdk/pulls).

## Raising Feature Requests

Feature requests are also welcome.
To raise a request, please start a ['Feature Request' Discussion](https://github.com/puppetlabs/pdk/discussions/categories/feature-request).
Once there is consensus on how to proceed, we can then create a ticket for our backlog and plan for bringing it in to a future sprint.

# Running from source

If you need to run `pdk` in a working directory outside the cloned repository, either set `BUNDLE_GEMFILE` to the pdk's Gemfile location, or install and use the [binstubs of bundler](http://bundler.io/bundle_binstubs.html). These binstubs are small proxy binaries that set up the environment for running the tool.

```
# assuming ~/bin is already on your path:
$ bundle binstubs pdk --path ~/bin
```

## binstubs and Windows

The binstubs generated by bundler depend on the hashbang (`#!`) to invoke ruby, however this of course doesn't work on Windows. To invoke the binstubs you must call ruby and then specify the path to the binstub. For example, let's say we have the PDK source called `pdk` and a test module called `testmodule`

``` powershell
# Starting from the PDK Source directory

# 1. Create bin directory
PS> mkdir ..\testmodule\bin

# 2. Create the binstub in the test module
PS> bundle binstubs pdk --path ..\testmodule\bin

# 3. Change directory to the test module
PS> cd ..\testmodule

# 4. Run the pdk binstub
PS> ruby.exe bin\pdk --version
1.10.0.pre (heads/main-g3e22a80)
```

# Running tests

pdk has the following testing Rake tasks.

## spec

Runs unit tests.

## rubocop

Runs Ruby style checks. Use `rake rubocop:auto_correct` to fix the easy ones.

## acceptance:local

Runs acceptance tests on the current pdk code. These tests are executed on commits and pull requests to this repo using appveyor.

# Testing packages

The package-testing/ folder contains files for testing built packages of pdk. This is for Puppet's packaging CI, so contributors outside of Puppet, Inc. don't need to worry about executing it. It uses [beaker](https://github.com/puppetlabs/beaker) to provision a VM, fetch and install a pdk installation package, and then run the acceptance tests on that VM.

This folder has its own Gemfile and Rakefile providing an _acceptance_ rake task. It requires some environment variables to be set in order to specify what beaker will set up:

Environment Variable | Usage
---------------------|------
**SHA** | The SHA or tag of a package build i.e. the folder name on the build server that packages will be found in.
*--or--* |
**LOCAL_PKG** | Full path to a locally built package that you want to test.
**TEST_TARGET** | A beaker-hostgenerator string for the OS of the VM you want to test on e.g. _redhat7-64workstation._ or _windows2012r2-64workstation._ (The period character after workstation is required by beaker-hostgenerator).
**BUILD_SERVER** | (Defaults to 'builds.delivery.puppetlabs.net' if not set) (Only required if testing a SHA on a Windows VM). The hostname of the build server that hosts packages.
**SUITE_VERSION** | (If not set, will be automatically determined if possible) The build tag/version string used when installing packages on certain platforms - e.g. if the package you built is `pdk-0.5.0.0.21.gb84d40e-1.osx10.12.dmg` then **SUITE_VERSION** would be `0.5.0.0.21.gb84d40e`