README.md in pdk-0.5.0 vs README.md in pdk-0.6.0
- old
+ new
@@ -1,16 +1,54 @@
-# pdk [](https://travis-ci.org/puppetlabs/pdk) [](https://ci.appveyor.com/project/puppetlabs/pdk)
+# pdk [](https://travis-ci.org/puppetlabs/pdk) [](https://ci.appveyor.com/project/puppetlabs/pdk) [](https://coveralls.io/github/puppetlabs/pdk?branch=master)
-A CLI to facilitate easy, unified development workflows for Puppet modules. pdk is a key part of the Puppet Development Kit, the shortest path to better modules.
+A CLI to facilitate easy, unified development workflows for Puppet modules. `pdk` is a key part of the Puppet Development Kit, the shortest path to better modules.
## Installation
-Download and install the newest package matching your platform from [here](https://drive.google.com/drive/folders/0Bz0tCHSb1u41alR4MmZfRHBTV1k?usp=sharing).
+Download and install the newest package matching your platform from [here](https://drive.google.com/drive/folders/0Bz0tCHSb1u41alR4MmZfRHBTV1k?usp=sharing). If you are using Windows, please remember to close any open PowerShell windows.
-On Windows you need to set your script execution policy to [RemoteSigned](https://technet.microsoft.com/en-us/library/ee176961.aspx), to allow the (required) PowerShell integration to work.
+### Windows
+On Windows you should run PDK from PowerShell and `pdk` will be available in your PowerShell prompt after installation.
+
+If the `pdk` command does not appear, check that the `PuppetDevelopmentKit` PowerShell module is loaded in your PowerShell prompt:
+
+```
+Get-Module -Name PuppetDevelopmentKit
+```
+
+If no output is returned, load the `PuppetDevelopmentKit` module by running the following command:
+
+```
+Import-Module -Name PuppetDevelopmentKit
+```
+
+> Note: On PowerShell version 3 and above, PowerShell modules are loaded automatically so this step shouldn't be necessary.
+
+You should set your script execution policy to at least [RemoteSigned](https://msdn.microsoft.com/en-us/powershell/reference/5.1/microsoft.powershell.security/set-executionpolicy), if it's not already, to allow the PowerShell integration to work.
+
+You can check your ExecutionPolicy by running the following command from a PowerShell prompt:
+
+```
+Get-ExecutionPolicy
+```
+
+To set the `ExecutionPolicy`, run the following command:
+
+```
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
+```
+
+If you can't change the system `ExecutionPolicy`, you can change the `ExecutionPolicy` for just the current session by using the `Scope` paramter:
+
+```
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+For more information about PowerShell `ExecutionPolicies` or how to change them, see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170).
+
## Usage
### Generate a new module
To get started, generate a new module from the default template.
@@ -96,11 +134,11 @@
Generates a new module.
Usage:
```
-pdk new module [--template-url=git_url] [--license=spdx_identifier] [--vcs=vcs_provider] module_name [target_dir]
+pdk new module [--template-url=git_url] [--license=spdx_identifier] module_name [target_dir]
```
The `pdk new module` command accepts the following arguments and options. Arguments are optional unless otherwise specified.
#### `--template-url=git_url`
@@ -109,14 +147,10 @@
#### `--license=spdx_identifier`
Specifies the license this module is written under. See https://spdx.org/licenses/ for a list of open source licenses, or use `proprietary`. Defaults to `Apache-2.0`.
-#### `--vcs=vcs_provider`
-
-Specifies the version control driver. Valid values: `git`, `none`. Default: `git`.
-
#### `--skip-interview`
Suppress interactive queries for initial values. All questions will use the default values.
#### `module_name`
@@ -164,34 +198,10 @@
If the class should take parameters, they can be specified on the command line
to be added to the generated class. Optionally, the data type of the parameter
can be specified along with the parameter name, separated by a colon. Any
number of parameters can be provided on the command line.
-### `pdk add provider` command
-
-Adds a new resource provider to an existing module.
-
-Usage:
-
-```
-pdk add provider [--template-url=git_url] provider_name [data_type:attribute_name]*
-```
-
-The `pdk add provider` command accepts the following arguments. Arguments are optional unless specified.
-
-#### `--template-url=git_url`
-
-Overrides the template to use for this module. If possible please contribute your improvements back to the default template at [puppetlabs/pdk](https://github.com/puppetlabs/pdk).
-
-#### `provider_name`
-
-**Required**. Specifies the name of the resource provider being created.
-
-#### `data_type:attribute_name`
-
-Specifies a list of attributes with their expected data types, such as `'Enum[absent, present]:ensure'`. If not specified, the data type will have no attributes.
-
### `pdk validate` command
Runs all static validations. Any errors are reported to the console in the format requested. The exit code is non-zero when errors occur.
Usage:
@@ -291,50 +301,23 @@
rake beaker:ssh[set,node] # Try to use vagrant to login to the Beaker node
rake build # Build puppet module package
[...]
```
-## Contributing
+## Module Compatibility
-In cases where `pdk` needs to run 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/v1.15/bundle_binstubs.html), which are small proxy binaries, that set up the environment for running the tool.
+**PDK Version Compatibility:** modules created with a specific PDK version should validate against and run on all Puppet andRuby version combinations currently under maintenance (see https://docs.puppet.com/puppet/latest/about_agent.html and https://puppet.com/misc/puppet-enterprise-lifecycle)
-```
-# assuming ~/bin is already on your path:
-$ bundle binstubs pdk --path ~/bin
-```
+**Module Template Compatibility:** Modules created with a specific version of the PDK will remain compatible to newer versions of the PDK with the following exceptions:
+* access to new PDK functionality might require an update of the module to the current Template version
+* access to a new major PDK version might require an update of the module to the current Template version, after a one year deprecation cycle
+* validation against new Puppet versions might require new PDK functionality, a new major PDK version, and changes to the module itself.
-Bug reports and pull requests are welcome on GitHub at https://github.com/puppetlabs/pdk/issues.
+## Upgrading
+* In the common case, Puppet and the PDK will be forward-compatible so that minor Puppet updates will not require a new version of the PDK.
+* Some new Puppet versions will require changes to the PDK. In that case, upgrading the PDK for validation prior to roll-out of Puppet is strongly recommended.
-### Running tests
-pdk has three testing rake tasks
-#### spec
+## Contributing
-Run unit tests.
-
-#### acceptance:local
-
-Run acceptance tests on the current pdk code. These tests are executed on commits and pull requests to this repo using both travis and appveyor.
-
-#### acceptance:package
-
-Run acceptance tests against a package install. This task is for Puppet's packaging CI, and 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.
-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.
-**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** | (Only required if the tests will run on a Windows VM). The hostname of the build server that hosts packages. A Puppet JIRA ticket ([BKR-1109](https://tickets.puppetlabs.com/browse/BKR-1109)) has been filed to update beaker so this would never be required.
-
-On completion of this testing task, the results from the VM will be available in a folder named _archive_.
-
-### Release Process
-
-1. Bump the version in `lib/pdk/version.rb`.
-1. In a clean checkout of master, run `bundle exec rake changelog`.
-1. Edit PR titles and tags, until `bundle exec rake changelog` output makes sense.
-1. Commit and PR the changes.
-1. 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)
-1. Profit!
-1. Update `lib/pdk/version.rb` with `x.y.z.pre` version bump, commit, and PR to prepare for next release.
+See the [CONTRIBUTING.md](CONTRIBUTING.md) file for development notes.