Skip to content

Latest commit

 

History

History
87 lines (57 loc) · 4.44 KB

CONTRIBUTING.md

File metadata and controls

87 lines (57 loc) · 4.44 KB
Raw

Contributing

Reporting Bugs

We welcome error reports and patches to the PDK repository. If you have discovered an issue, you can raise it here or reach out to us directly on the Puppet Community Slack.

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 or post a question to [email protected].

Finally if you have a fix for an issue you can open a PR to resolve it here.

Raising Feature Requests

Feature requests are also welcome. To raise a request, please start a 'Feature Request' Discussion. 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. 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

# 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 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

Release Process

  1. Bump the version in lib/pdk/version.rb.
  2. In a clean checkout of main, run bundle exec rake changelog.
  3. Edit PR titles and tags, until bundle exec rake changelog output makes sense.
  4. Commit and PR the changes.
  5. When the PR is merged, get a clean checkout of the merged commit, and run bundle exec rake release[upstream] (where "upstream" is your local name of the puppetlabs remote)
  6. Profit!
  7. Update lib/pdk/version.rb with x.y.z.pre version bump, commit, and PR to prepare for next release.