From ef02cecb9b11d95affc5919d6fe5f99e68ffd3b6 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Tue, 27 Jun 2023 09:41:29 +0100 Subject: [PATCH 01/10] (CONT-1134) Clean up docs --- docs/pdk.ditamap | 2 +- docs/pdk_building_module_packages.md | 2 +- docs/pdk_install.md | 20 +------------------- docs/pdk_troubleshooting.md | 22 ---------------------- 4 files changed, 3 insertions(+), 43 deletions(-) diff --git a/docs/pdk.ditamap b/docs/pdk.ditamap index 692166158..6a5d911b4 100644 --- a/docs/pdk.ditamap +++ b/docs/pdk.ditamap @@ -5,7 +5,7 @@ pdk - + diff --git a/docs/pdk_building_module_packages.md b/docs/pdk_building_module_packages.md index bce9a6c44..4c55ad6fd 100644 --- a/docs/pdk_building_module_packages.md +++ b/docs/pdk_building_module_packages.md @@ -7,7 +7,7 @@ The `pdk build` command performs a series of checks on your module and builds a `tar.gz` package so that you can upload your module to the Forge. To learn more about publishing your module to the Forge, see the documentation about [publishing your -module](https://puppet.com/docs/puppet/4.9/modules_publishing.html#removing-symlinks-from-your-module).  +module](https://www.puppet.com/docs/puppet/latest/modules_publishing.html#modules_publishing_prep-publishing-remove-symlinks).  When you run the `pdk build` command, PDK checks your module metadata, looks for any symlinks, and excludes from the package any files listed in the `.gitignore` diff --git a/docs/pdk_install.md b/docs/pdk_install.md index a9f8e14e2..d014cba0e 100644 --- a/docs/pdk_install.md +++ b/docs/pdk_install.md @@ -10,7 +10,7 @@ By default, PDK installs to the following locations: - On Windows systems: `C:\Program Files\Puppet Labs\DevelopmentKit` -PDK uses Puppet 6 and 7. +PDK uses the latest versions pf Puppet 7 and 8 available at the time of release. Modules created with PDK work with all Puppet and Ruby version combinations currently under maintenance. See [open source Puppet](https://puppet.com/docs/puppet/latest/about_agent.html) and [Puppet Enterprise](https://www.puppet.com/docs/pe/2023.0/getting_support_for_pe.html#getting_support_for_pe) lifecycle pages for details. @@ -255,15 +255,6 @@ instructions. 2. Open a new PowerShell window to re-source your profile and make PDK available to your PATH. - -**Result:** - -On PowerShell 4.0 or later, PDK loads automatically and `pdk` commands are -available to the prompt. - -> **Tip:** If you encounter execution policy restriction errors when you try to -run `pdk` commands, see [troubleshooting](pdk_troubleshooting.md) for help. - #### What to do next: To upgrade PDK to the most recent release, run `choco upgrade pdk` @@ -280,15 +271,6 @@ Download and install the PDK package for Windows systems. 3. Open a new PowerShell window to re-source your profile and make PDK available to your PATH. - -**Result:** - -On PowerShell 4.0 or later, PDK loads automatically and `pdk` commands are -available to the prompt. - -> **Tip:** If you encounter execution policy restriction errors when you try to -run `pdk` commands, see [troubleshooting](pdk_troubleshooting.md) for help. - ## Setting up PDK behind a proxy If you are using PDK behind a proxy, you must set environment variables to diff --git a/docs/pdk_troubleshooting.md b/docs/pdk_troubleshooting.md index 49efecb21..c5af2548a 100644 --- a/docs/pdk_troubleshooting.md +++ b/docs/pdk_troubleshooting.md @@ -2,28 +2,6 @@ If you are encountering trouble with PDK, check for these common issues.  -## Windows: Execution policy restrictions - -In some Windows installations, the default execution policy restrictions -prohibit `pdk` commands. - -To fix this issue, set your script execution policy to at least `RemoteSigned` -by running `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned` - -Alternatively, you can change the `Scope` parameter of the `ExecutionPolicy` to -the current session by running `Set-ExecutionPolicy -ExecutionPolicy -RemoteSigned -Scope CurrentUser` - -For more information about PowerShell execution policies or how to change them, -see Microsoft documentation about -[Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170) and how to -set [execution -policy](https://msdn.microsoft.com/en-us/powershell/reference/5.1/microsoft.powershell.security/set-executionpolicy). - -> **Note:** Windows versions older than Windows 10 might not recognize the `pdk` -command. If you are running an older version of Windows, you might need to -update your PowerShell prior to using PDK. - ## PDK not in ZShell PATH on Mac OS X With ZShell on Mac OS X, PDK is not automatically added to the PATH. To fix From 8d08c7ad596acd3d416e7e9fd76897ca576a1518 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Tue, 27 Jun 2023 09:57:50 +0100 Subject: [PATCH 02/10] (CONT-1134) Update release notes --- docs/pdk_known_issues.md | 145 +------------------ docs/release_notes_pdk.md | 288 ++------------------------------------ 2 files changed, 15 insertions(+), 418 deletions(-) diff --git a/docs/pdk_known_issues.md b/docs/pdk_known_issues.md index 3c971b988..1bd3df053 100644 --- a/docs/pdk_known_issues.md +++ b/docs/pdk_known_issues.md @@ -1,146 +1,5 @@ # PDK known issues -## PDK 2.7.0 - -### `uninitialized constant` error - -When selecting Puppet versions PDK, you may encounter an `uninitialized constant` error if the target version is below 6.29 for Puppet 6 or 7.22 for Puppet 7. - -This is caused by an incompatible version of concurrent-ruby that is downloaded when PDK processes the selected Puppet version. - -To mitigate this issue, we recommend selecting only the latest puppet versions when using `--puppet-version`. - -For example: - -#### Puppet 6 - -``` -pdk validate --puppet-version 6.29 -``` - -#### Puppet 7 - -``` -pdk validate --puppet-version 7.22 -``` -The above issue should no longer be present when using `--pe-version` - -### Install of pdk-2.7.0.0-1.el9.x86_64 conflicts with file from package - -When installing an el9 based package the user may see the following errors: - -``` -file /usr/lib/.build-id/95/26c65fed0e95fbb6b988476cc811ca19d5c9c9 from install of pdk-2.7.0.0-1.el9.x86_64 conflicts with file from package libgcc-11.3.1-2.1.el9.x86_64 -file /usr/lib/.build-id/ab/d5d7149726b0410af7af2e9a59491942605ddd from install of pdk-2.7.0.0-1.el9.x86_64 conflicts with file from package libstdc++-11.3.1-2.1.el9.x86_64 -``` - -This is caused by conflicting build-ids in the package. - -To avoid this issue, please target PDK 2.7.1. - -## PDK 2.6.1 - -### Running autocorrect on puppet-lint top_scope_facts - -Currently there is an issue with a third party plugin that the pdk currently pulls in called puppet-lint-top_scope_facts-check. When using the autocorrect functionality, it introduces issues in the codebase. - -In order to avoid running into this particular issue we recommend adding the following to your `.sync.yaml` file and then run a `pdk update`: - -``` -Rakefile: - extra_disabled_lint_checks: - - top_scope_facts -``` - -### `uninitialized constant` error - -When selecting Puppet versions PDK, you may encounter an `uninitialized constant` error if the target version is below 6.29 for Puppet 6 or 7.22 for Puppet 7. - -This is caused by an incompatible version of concurrent-ruby that is downloaded when PDK processes the selected Puppet version. - -To mitigate this issue, we recommend selecting only the latest puppet versions when using `--puppet-version`. - -For example: - -#### Puppet 6 - -``` -pdk validate --puppet-version 6.29 -``` - -#### Puppet 7 - -``` -pdk validate --puppet-version 7.22 -``` -In scenarios where `--pe-version` is used, it is recommended that `--puppet-version` is used instead, with the correct target as described above. - -## PDK 1.15.0 is incompatible with Bundler 2.1.0 and later - -PDK 1.15.0 is incompatible with Bundler 2.1.0 and later. Use Bundler 2.0.2 -instead. - -## PDK analytics opt-out dialog causing issues with CI systems - -In PDK 1.11.0, when running in a Continuous Integration (CI) environment (such -as Travis CI), PDK may get stuck waiting for a response as to whether or not you -want to opt-out of anonymous analytics data collection. - -PDK is intended to bypass this prompt in "non-interactive" environments such as -a CI environment. However, certain common CI environments are not being -correctly detected as "non-interactive". As an immediate workaround, avoid the -issue by configuring your CI jobs to run PDK with the `PDK_FRONTEND` environment -variable set to the value "noninteractive". For example, if running a -validation: - -``` -$ PDK_FRONTEND=noninteractive pdk validate -``` - -You might also be able to configure the environment variable for the entire job. -See -[https://docs.travis-ci.com/user/environment-variables/](https://docs.travis-ci.com/user/environment-variables/) -for information about configuring this in Travis CI, or check your CI system's -documentation for similar options. -[PDK-1414](https://tickets.puppetlabs.com/browse/PDK-1414), -[PDK-1415](https://tickets.puppetlabs.com/browse/PDK-1415) - -## Using PDK with PowerShell ISE locks the console - -If you run the `pdk new module` command inside a PowerShell ISE window, it -returns an error and locks the console. Do not use PDK with PowerShell ISE. -PDK-1168 - -## PDK not in ZShell PATH on Mac OS X - -With ZShell on Mac OS X, PDK is not automatically added to the PATH. To fix -this, add the PATH by adding the line `eval $(/usr/libexec/path_helper -s)` to -the ZShell resource file (`~/.zshrc`). - -## Output of `pdk test unit --list` lacks information - -Output from `pdk test unit --list` lacks detailed information and tests appear -duplicated. To get the full text descriptions, execute the tests in JUnit format -by running `pdk test unit --format=junit` -[PDK-374](https://tickets.puppetlabs.com/browse/PDK-374) - -## Module validation and testing might fail if dependencies include gems with native extensions - -You might not be able to use PDK with a module if that module's Gemfile requires -Ruby gems with native extensions, particularly when running on Windows. - -When you run `pdk validate` or `pdk test unit` on a module, PDK tries to install -any missing module dependencies before it runs validations or tests. On some -platforms, PDK can install gems with native extensions, if you already have the -required compilation tools and libraries installed. On Windows, however, the -Ruby installations managed by PDK are not configured to support native extension -compilation, even if the necessary tools are present. - -If you encounter this issue on a platform other than Windows, you might be able -to resolve it by researching and installing the required dependencies for the -gem that is failing to install. - -If you encounter this issue on a Windows platform, you must remove or comment -out the Gemfile dependencies that include native extensions or that have -dependencies that include native extensions. +## PDK 3.0.0 +TBA diff --git a/docs/release_notes_pdk.md b/docs/release_notes_pdk.md index 1729f22bd..3e39a7d4d 100644 --- a/docs/release_notes_pdk.md +++ b/docs/release_notes_pdk.md @@ -2,285 +2,23 @@ New features, enhancements, and resolved issues for PDK. -## PDK 2.7.1 +## PDK 3.0.0 -### New features and enhancements - -* PDK Templates have been updated to 2.7.4 - -### Resolved issues - -* Fixes an issue with duplicate build-ids for RedHat 9 packages - -For more more details, please feel free to check out our [project changelog](https://github.com/puppetlabs/pdk/releases/tag/v2.7.1). - -## PDK 2.7.0 - -### New features and enhancements - -* A RedHat 9 compatible package has been added. -* A new Puppet validator for Bolt plans has been added by communit member jay7x. -* PDK Templates have been updated to 2.7.2. -* Puppet 7.23 has been added to the packages. -* Ruby 2.7.7 is now the default runtime used by packaged versions of PDK. -* The minimum ruby requirement has been raised to 2.5.9. - -### Resolved issues - -* Selecting a Puppet Enterprise version with `PDK_PE_VERSION` will resolve the latest puppet gem relative to the PE release. -* The vendored puppet-lint plugins have been updated to their latest compatible versions. This resolves an issue that top scope facts to be formatted incorrectly. -* Deprecation warnings for `bundle show` will no longer be displayed when using the `release` command. - - -### Deprecations - -* PDK no longer ships with OSX 10.15 packages. -* Legacy i18n support has been removed. - -For more more details, please feel free to check out our [project changelog](https://github.com/puppetlabs/pdk/releases/tag/v2.7.0). - -## PDK 2.6.1 - -### New features and enhancements - -* A Ubuntu 22.04 compatible package has been added. -* An OSX 12 compatible package has been added. - -### Resolved issues - -* Versions 6.29 and 7.22 of the Puppet gem have been added to the packages. The two new gem releases resolve an issue where an incompatible version of `concurrent-ruby` may be dowloaded when creating a new module or running `pdk validate`. - -## PDK 2.6.0 +> PDK 3.0 is a backwards incompatible release. ### New features and enhancements -* Ruby 2.7.6 has been updated to 2.7.7 to address [CVE-2021-33621](https://www.ruby-lang.org/en/news/2022/11/22/http-response-splitting-in-cgi-cve-2021-33621/). -* PDK Templates have been updated to 2.7.1. -* Support for Fedora 36 has been added. - -### Resolved issues - -* The vendored puppet-lint plugins have been updated to their latest compatible versions. This resolves an issue where a conflict between puppet-lint and the sytax validator would occur when using the auto fix feature of `pdk validate`. -* The vendored facterdb version has been updated. This brings in more supported facts for testing your Puppet code. -* PDK will no longer attempt to install missing dependencies when creating new modules with the default template. +* Ruby 3.2.2 is now the default version of Ruby. +* Puppet 8 is now the default version of Puppet. +* PDK no longer relies on PowerShell, you are able to use PDK from any terminal that honours your PATH variable. +* As of this release, PDK now only includes the latest Puppet versions available at the time of build. This siginficantly reduces the package size and improves performance. +* The `bundle` command is no longer `experimental`. +* PDK now properly respects the `verbose` option when utilizing format options for unit testing. +* PDK now supports the `operatingsystem_support` parameter from `answers.json`. ### Deprecations -* Package support for Fedora 32 and 34 has been removed. -* Puppet 5 and Ruby 2.4 support has been removed. -* Nokogiri and it's dependencies have been removed from the packages. - -## PDK 2.5.0 - -### New features and enhancements - -Support added for SUSE Enterprise Linux 15 - -## PDK 2.4.0 -### Resolved issues - -Fix inconsistencies between the `pdk validate` and `pdk release prep` commands. The `in_module_root` function now checks to see if `metadata.json` is present instead of relying on folder names [PDK-1758](https://tickets.puppetlabs.com/browse/PDK-1758) - -## PDK 2.3.0 -### Resolved issues - -Fixes a compatibility issue with psych gem dependency [puppetlabs/pdk#1143](https://github.com/puppetlabs/pdk/issues/1143) - -## PDK 2.2.0 - -### New features and enhancements - -The PDK entry point is now Ruby 2.5, up from Ruby 2.4. This change should be transparent to users as the available Ruby versions are unchanged. - -Support added for OSX 11, Debian 11, Fedora 32 & 34 - -A project level setting containing a list of ignored files or patterns for use with `pdk validate` [puppetlabs/pdk#1114](https://github.com/puppetlabs/pdk/pull/1114) - -Bump `json_pure` gem to ~> 2.5.1 on Ruby >= 2.7 [puppetlabs/pdk#1124](https://github.com/puppetlabs/pdk/pull/1124) - -### Resolved issues -Prevent errors when choosing not to set forge token prior to running `pdk release` [puppetlabs/pdk#1121](https://github.com/puppetlabs/pdk/pull/1121) - -Set `skip_branch_with_pr` to true by default in appveyor.yml template [puppetlabs/pdk-templates#442](https://github.com/puppetlabs/pdk-templates/pull/442) - -Run validation steps prior to the matrix build [puppetlabs/pdk-templates#441](https://github.com/puppetlabs/pdk-templates/pull/441) - -## PDK 2.1.1 - -### New features and enhancements - -#### Use latest Facter version in GHActions Spec Test Template - -The Github Actions `spec.yml` workflow now sets the `FACTER_GEM_VERSION` ENV var. See [puppetlabs/pdk-templates#439](https://github.com/puppetlabs/pdk-templates/pull/439). - -#### New parameters added in `.gitlab-ci.yml` template - -See [puppetlabs/pdk-templates#436](https://github.com/puppetlabs/pdk-templates/pull/436), [puppetlabs/pdk-templates#434](https://github.com/puppetlabs/pdk-templates/pull/434). - -#### Backtrace from spec tests cleaned up - -The verbosity of the backtrace from spec test failures has been scaled back to ensure the relevant info is easier to read. [puppetlabs/pdk-templates#431](https://github.com/puppetlabs/pdk-templates/pull/431). - -#### Added EditorConfig template - -See [puppetlabs/pdk-templates#428](https://github.com/puppetlabs/pdk-templates/pull/428). - -### Resolved issues - -#### Resolved issue with ACCESS_DENIED error on Win Github Actions - -Fixes an issue on Windows Server 2016, 2019 instances on Github Actions where child processes were unable to spawn. -See [puppetlabs/pdk#1084](https://github.com/puppetlabs/pdk/pull/1084). - -#### Multiple issues resolved in `pdk release` - -Fix for an issue where the changelog top most version did not match the version in `metadata.json`. - -`pdk release` can now handle the scenario where no Forge token is provided. - -See [puppetlabs/pdk#1088](https://github.com/puppetlabs/pdk/pull/1088). - -## PDK 2.1 - -### New features and enhancements - -#### Add `pdk env` subcommand - -Adds an experimental `pdk env` subcommand. Use `pdk env` to print the environment variables that PDK is currently using (https://github.com/nkanderson). - -### Resolved issues - -#### `--verbose` option broken for `pdk new defined_type` - -Fixes an issue where the `--verbose` option would not work with the `pdk new defined_type` command. See [ddfreyne/cri#103](https://github.com/ddfreyne/cri/issues/103). - -#### PDK output scrollback in VS Code limited - -Resolves a scrollback issue when using PDK in the integrated terminal of VS Code by disabling ANSICON on Windows. - -### Template changes and fixes - -* Relocated the`inventory.yaml` file used by Litmus. This prevents accidental execution of acceptance tests in production systems. (https://github.com/pmcmaw) -* Removed Win32 gems from the Gemfile. These have been included in Puppet since version 5. (https://github.com/da-ar) -* Added Puppet 7 tests to .gitlab-ci.yml (https://github.com/silug) - -## PDK 2.0 - -### Backwards incompatible changes - -#### Removed support for Puppet 4.x and Ruby \< 2.4.0 - -The PDK gem now requires at least Ruby 2.4.0. PDK OS-native packages no longer -include Puppet 4.x or the Ruby 2.1.9 runtime environment. If your workflow -requires you to work with Puppet 4.x code, you can continue to use the latest -PDK 1.x release, however support for the 1.x series might end soon. - -#### New default mocking framework - -The default mocking framework for RSpec tests has been updated to `rspec-mocks`. -Previously `puppetlabs_spec_helper` was loading both `rspec-mocks` and `mocha`. -This leads to confusing inconsistencies in unit tests. We've been recommending -`rspec-mocks` as the preferred library for some time. If your test suite is not -yet ready for this step, remove the default value by setting `mock_with: ~` -(YAML's nil value) in your `.sync.yml` file to get the PDK 1.x behavior. -(https://github.com/DavidS) - -### New features and enhancements - -#### Added ability to generate new facts - -Added the `pdk new fact` command to generate new custom facts in a module. -(https://github.com/logicminds) - -#### Added ability to generate new functions - -Added the `pdk new function` command to generate new functions in a module. -(https://github.com/logicminds) - -#### Added AIX option to new module interview options - -Added AIX to OS compatibility picker during the guided interview for -`pdk new module`. (https://github.com/logicminds) - -#### Set Forge API token via environment variable - -You can now set your Forge API token via the `PDK_FORGE_TOKEN` environment variable. -(https://github.com/logicminds) - -#### Renamed default branches to `main` - -The default branches for PDK and the PDK templates repositories have been renamed -to `main`, and the PDK's template-related code has been updated to reflect this -change. If you have a module that was manually pinned to the `master` branch of the -templates repo you might need to use `pdk convert --default-template` to switch -back to the default branch. - -Similarly, the `--puppet-dev` version selection flag now pulls from the `main` -branch of the official Puppet source code repository. - -#### Better error messages for `pdk release publish` failures - -The `pdk release publish` command now surfaces the underlying Forge error messages -if the module upload step fails. (https://github.com/michaeltlombardi) - -### Resolved issues - -#### Improved Facter compatibility - -The PDK gem can now be activated alongside Facter 4.x. (https://github.com/GabrielNagy) - -#### Removal of harmful/offensive terminology - -Several instances of inappropriate, harmful, or insensitive terminology have been removed -from documentation, code examples, etc. Please open an issue or pull request if you -find additional instances. - -### Template Changes and Fixes - - * To set up code for the default Ruby 2.7 behavior, the Rubocop rule - `Style/BracesAroundHashParameters` is now disabled by default. - (https://github.com/alexjfisher) - - * Improved flexibility of Appveyor configuration by providing a `remove_includes` - option to manipulate the jobs to be run. (https://github.com/sheenaajay) - - * Enabled VSCode's "Remote Containers" plugin to allow running all the backend tooling - in a remote container, instead of requiring a local PDK install. (https://github.com/silug) - - * Fixed setting `strict_variables` to false. (https://github.com/cdenneen) - - * Updated GitLab CI config to new schema. (https://github.com/silug) - - * Updated `pdk build` to automatically exclude `.puppet-lint.rc` and `.sync.yml`. - (https://github.com/silug) - - * Added an empty, commented `.sync.yml` to new modules to help folks jumpstart the - customization process. (https://github.com/silug) - - * Added ability to override GitLab CI global defaults in jobs. (https://github.com/cdenneen) - - * Added Gitpod.io support to modules. (https://github.com/logicminds) - - * Implemented Puppet's public Litmus runners in Github Actions workflows. This provides - immediate feedback on testing through running the full test suite against ephemeral VMs - on each PR update. (https://github.com/DavidS, https://github.com/ekohl) - - * Travis config now allows setting the chosen distributions per Puppet collection for - acceptance tests. (https://github.com/adrianiurca) - - * Updated template-configured Rubocop to current version; updated default cops; updated - target Ruby version to 2.4. (https://github.com/tuxmea, https://github.com/DavidS) - - * Updated default Ruby version for static analysis steps run in Appveyor. - (https://github.com/pmcmaw) - - * Added a Github workflow to run module release prep on-demand or on a schedule. - (https://github.com/carabasdaniel, https://github.com/pmcmaw, https://github.com/ekohl) - - * Added an optional step to run Litmus on Gitlab CI. (https://github.com/cdenneen) - - * Fixed new object templates to pass validation and unit tests after initial generation. - (https://github.com/DavidS, https://github.com/cdenneen) - - * Removed Puppet 5.x from default Travis and Appveyor configs. - (https://github.com/carabasdaniel, https://github.com/cdenneen) +* The `--pe-version` flag has been deprecated. It will continue to work but we advise moving to `--puppet-version` given that this flag will be removed in a future release. +* The deprecated `module` command has now been removed. +* The deprecated `config` command has now been removed. +* The experimental `console` command has been removed from this release. From bed5ab43519ba6b039ddc80d1008ab3193c0bac4 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Tue, 27 Jun 2023 13:34:53 +0100 Subject: [PATCH 03/10] (CONT-1134) Update upgrade docs --- docs/pdk_upgrading.md | 118 ++++++++++++++++++++++++++++++++---------- 1 file changed, 92 insertions(+), 26 deletions(-) diff --git a/docs/pdk_upgrading.md b/docs/pdk_upgrading.md index d9d75ac4c..4c73fa219 100644 --- a/docs/pdk_upgrading.md +++ b/docs/pdk_upgrading.md @@ -7,42 +7,108 @@ Upgrade PDK using the same method you used to originally install it. See the PDK [installation](pdk_install.md) instructions for your platform for details. Then, update your modules to integrate any module template changes. -## Update a module with template changes +## Upgrading to PDK 3.0.0 -Update your module to keep it current with PDK or custom module template -changes.  +### Clear the local PDK cache -> **Before you begin** -> Ensure that the module you are updating is compatible with PDK version 1.3.0 or -later. If the module was created with versions of PDK earlier than 1.3.0, -convert the module to the current template with the pdk convert command. See [converting modules](pdk_converting_modules.md) for more -information. +When PDK encounters a module with non standard dependencies (added by you or the module author), +it will cache gems in your user profile. -The `pdk update` function updates your module based on the template you used -when you created or converted your module. If there have been any changes to -that template, PDK updates your module to incorporate them. +On Linux systems the cache can be found in `~/.pdk/cache` and on Windows systems it can be +found in `$ENV:USERPROFILE\AppData\Local\PDK\cache`. -To check for template changes without making changes, run `update` with the -`--noop` option. This option runs the command in "no operation" mode, which -shows what changes would be made, but doesn't actually make them. +Sometimes gems installed in the cache by older version of PDK can cause conflicts. +For that reason we recommend clearing the cache before you install PDK 3.0.0. -1. From the command line, change into the module's directory with `cd - ` +#### On Linux/MacOS -2. Run the update command: `pdk update` +``` +rm -rf ~/.pdk/cache +``` -3. If any module metadata is missing, respond to PDK prompts to provide - metadata information. +#### On Windows -4. Confirm the change summary PDK displays and either continue or cancel the - update.  +``` +Remove-Item -Path $ENV:USERPROFILE\AppData\Local\PDK\cache -Recurse -Force +``` +#### Remove older versions of PDK (optional) -**Result:** +To be extra sure that you will have a smooth upgrade, you can remove your existing PDK installation. -Whether you confirm or cancel changes, PDK generates a detailed change report, -`update_report.txt`, in the top directory of the module. This report is updated -every time you run the `update` command. +Given that PDK can be installed through a variety of different methods, please consult the documentation +of the package provider for uninstallation steps. -If you confirm changes, PDK applies the reported changes to the module. +### Update your modules + +PDK 3.0.0 removes support for Puppet 6 and Ruby 2.5.9. Before upgrading you should ensure that your modules +are compatible with later Puppet and Ruby releases. + +Here are the versions of Puppet and Ruby that are included versions in PDK 3.0.0: + +* Puppet 8 and Ruby 3.2.2 +* Puppet 7 and Ruby 2.7.8 + +Once you are satisfied that your modules will support the versions listed above, you should ensure that your +modules also have the changes from the latest PDK templates. + +To do this, simply run `pdk update` inside a module and follow the prompts. + +### Troubleshooting issues after upgrading + +#### `racc` errors with Ruby 2.7.8 and PDK 3.0.0 + +You may encounter the following error after upgrading to PDK 3.0.0 + +``` + bolt was resolved to 3.23.1, which depends on + r10k was resolved to 3.15.4, which depends on + gettext-setup was resolved to 1.1.0, which depends on + gettext was resolved to 3.4.4, which depends on + racc +``` + +This happens because newer versions of racc are native gems and therefore require some compilation on installation. + +At this time, PDK cannot support all Gems with native extensions. + +##### Resolution + +To resolve the issue you can either: +* Run `pdk update`. +* Manually add the following requirement to your `.sync.yml` and run `pdk update`. + +``` + optional: + ":development": + - gem: racc + version: '~> 1.4.0'# + condition: if Gem::Requirement.create(['>= 2.7.0', '< 3.0.0']).satisfied_by?(Gem::Version.new(RUBY_VERSION.dup)) +``` + +Note: If you opt for manually adding the version requirement to your gem file, you will need + +#### `github_changelog_enerator` errors with Ruby 2.7.8 and PDK 3.0.0 + +You may encounter the following error after upgrading to PDK 3.0.0 + +``` + github_changelog_generator was resolved to 1.16.4, which depends on + async-http-faraday was resolved to 0.12.0, which depends on + async-http was resolved to 0.60.2, which depends on + async-io was resolved to 1.35.0, which depends on + async was resolved to 2.6.2, which depends on + io-event +``` + +##### Resolution + +To resolve this issue you can either: + +* Remove github_changelog_generator from your `.sync.yml` and use another solution for changelog generation. + +* Set the version requirement to 1.15.2 in your `sync.yml`. + +After completing the step of your choice, you will need to run `pdk update` to ensure that you +Gemfile is updated appropriately. From 6b5d4f0cceeb95c5f5806a284bfcc643ce865088 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Wed, 28 Jun 2023 13:22:17 +0100 Subject: [PATCH 04/10] Update docs/pdk_upgrading.md Co-authored-by: jordanbreen28 <112936862+jordanbreen28@users.noreply.github.com> --- docs/pdk_upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pdk_upgrading.md b/docs/pdk_upgrading.md index 4c73fa219..02e373795 100644 --- a/docs/pdk_upgrading.md +++ b/docs/pdk_upgrading.md @@ -111,4 +111,4 @@ To resolve this issue you can either: * Set the version requirement to 1.15.2 in your `sync.yml`. After completing the step of your choice, you will need to run `pdk update` to ensure that you -Gemfile is updated appropriately. +Gemfile is updated accordingly. From 0bd601a1744943c4cc2b8c7a222b820f9e38d3f7 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Wed, 28 Jun 2023 13:22:24 +0100 Subject: [PATCH 05/10] Update docs/pdk_upgrading.md Co-authored-by: jordanbreen28 <112936862+jordanbreen28@users.noreply.github.com> --- docs/pdk_upgrading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pdk_upgrading.md b/docs/pdk_upgrading.md index 02e373795..dbe315b4d 100644 --- a/docs/pdk_upgrading.md +++ b/docs/pdk_upgrading.md @@ -110,5 +110,5 @@ To resolve this issue you can either: * Set the version requirement to 1.15.2 in your `sync.yml`. -After completing the step of your choice, you will need to run `pdk update` to ensure that you +After completing the step of your choice, you will need to run `pdk update` to ensure that your Gemfile is updated accordingly. From 6ae19362a87b6f2be6c4715962cbd06383a1caf7 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Wed, 28 Jun 2023 13:22:54 +0100 Subject: [PATCH 06/10] Update docs/pdk_install.md Co-authored-by: jordanbreen28 <112936862+jordanbreen28@users.noreply.github.com> --- docs/pdk_install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pdk_install.md b/docs/pdk_install.md index d014cba0e..bf2888bad 100644 --- a/docs/pdk_install.md +++ b/docs/pdk_install.md @@ -10,7 +10,7 @@ By default, PDK installs to the following locations: - On Windows systems: `C:\Program Files\Puppet Labs\DevelopmentKit` -PDK uses the latest versions pf Puppet 7 and 8 available at the time of release. +PDK uses the latest versions of Puppet 7 and 8 available at the time of release. Modules created with PDK work with all Puppet and Ruby version combinations currently under maintenance. See [open source Puppet](https://puppet.com/docs/puppet/latest/about_agent.html) and [Puppet Enterprise](https://www.puppet.com/docs/pe/2023.0/getting_support_for_pe.html#getting_support_for_pe) lifecycle pages for details. From bd43f4fd7622aa7b335c2fdb9ff4015995724397 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Wed, 28 Jun 2023 13:23:03 +0100 Subject: [PATCH 07/10] Update README.md Co-authored-by: jordanbreen28 <112936862+jordanbreen28@users.noreply.github.com> --- docs/pdk_upgrading.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/pdk_upgrading.md b/docs/pdk_upgrading.md index dbe315b4d..e9eefa9f0 100644 --- a/docs/pdk_upgrading.md +++ b/docs/pdk_upgrading.md @@ -32,13 +32,40 @@ rm -rf ~/.pdk/cache Remove-Item -Path $ENV:USERPROFILE\AppData\Local\PDK\cache -Recurse -Force ``` -#### Remove older versions of PDK (optional) +### Remove older versions of PDK (optional) To be extra sure that you will have a smooth upgrade, you can remove your existing PDK installation. Given that PDK can be installed through a variety of different methods, please consult the documentation of the package provider for uninstallation steps. +### Remove the legacy PowerShell module (Windows only) + +Versions of PDK prior to 3.0.0 used a PowerShell module to execute the application. This has now been removed as we +have transitioned to using a batch file as the entry point. + +To avoid conflicts when running PDK you should ensure that the PowerShell module has been removed. +Additionally, if you will need to close and restart any open PowerShell sessions. + +If it hasn't, it can easily be removed with a few simple steps: + +#### Check if your new install still references the module + +From a new PowerShell session, run the following command: + +``` +Get-Command -name PDK +``` + +#### Check that the module has been removed from the $MODULEPATH + +From a new PowerShell session run the following command: + +``` +Get-ChildItem -Path 'C:\Program Files\WindowsPowerShell\Modules\' +``` + +If the `PuppetDevelopmentKit` module is listed in the output, it can safely be removed. ### Update your modules @@ -83,12 +110,10 @@ To resolve the issue you can either: optional: ":development": - gem: racc - version: '~> 1.4.0'# + version: '~> 1.4.0' condition: if Gem::Requirement.create(['>= 2.7.0', '< 3.0.0']).satisfied_by?(Gem::Version.new(RUBY_VERSION.dup)) ``` -Note: If you opt for manually adding the version requirement to your gem file, you will need - #### `github_changelog_enerator` errors with Ruby 2.7.8 and PDK 3.0.0 You may encounter the following error after upgrading to PDK 3.0.0 From 24308009762e90a24564e0d624229df57f815e60 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Fri, 30 Jun 2023 09:36:44 +0100 Subject: [PATCH 08/10] (CONT-1134) Update version to latest --- docs/pdk.ditamap | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pdk.ditamap b/docs/pdk.ditamap index 6a5d911b4..b256f357a 100644 --- a/docs/pdk.ditamap +++ b/docs/pdk.ditamap @@ -5,7 +5,7 @@ pdk - + From 740869ab71ef8eb8c21d348530533c8068d212e2 Mon Sep 17 00:00:00 2001 From: Craig Gumbley Date: Mon, 3 Jul 2023 14:26:41 +0100 Subject: [PATCH 09/10] (CONT-1134) Link to pdk_upgrading.md --- docs/pdk_known_issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pdk_known_issues.md b/docs/pdk_known_issues.md index 1bd3df053..af0e50271 100644 --- a/docs/pdk_known_issues.md +++ b/docs/pdk_known_issues.md @@ -2,4 +2,4 @@ ## PDK 3.0.0 -TBA +For more information about upgrading your PDK installation, see [Upgrading PDK](pdk_upgrading.md). From 63e1a87885c736da7becdbfddc41f78242fc623d Mon Sep 17 00:00:00 2001 From: Ramesh Sencha Date: Tue, 4 Jul 2023 09:17:52 +0530 Subject: [PATCH 10/10] Mute rubocop warning for console.rb --- .rubocop_todo.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml index 1e3b3726b..65aa424d3 100644 --- a/.rubocop_todo.yml +++ b/.rubocop_todo.yml @@ -37,6 +37,8 @@ Metrics/AbcSize: # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode. # AllowedMethods: refine Metrics/BlockLength: + Exclude: + - lib/pdk/cli/console.rb Max: 105 # Offense count: 16