Merge pull request #7074 from chef/release_notes_v1

Add Chef 13.8 and 14.0 release notes

9 files changed, 463 insertions, 92 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index d1e082ffbe..71c2cf014e 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -2,11 +2,401 @@ _This file holds "in progress" release notes for the current release under devel
 
 # Unreleased
 
-# Chef Client Release Notes 14.TBC:
+# Chef Client Release Notes 14.0:
 
-## New Windows PowerShell mixin `powershell_exec`
+## New Resources
 
-Since our supported Windows platforms can all run .NET Framework 4.0 and PowerShell 4.0 we have taken time to add a new interop that will allow faster and safer interactions with the system PowerShell.  You will be able to use the `powershell_exec` mixin in most places where you would have previously used `powershell_out`.  For comparison, a basic benchmark test to return the `$PSVersionTable` 100 times completed 7.3X faster compared to the `powershell_out` method.  The majority of the time difference is because of less time spent in invocation.  So we believe it has big future potential where multiple calls to PowerShell are required inside (for example) a custom resource.
+Chef 14 includes a large number of resources ported from community cookbooks. These resources have been tested, improved, and had their functionality expanded. With these new resources in the Chef Client itself, the need for external cookbook dependencies and dependency management has been greatly reduced.
+
+### build_essential
+
+Use the build_essential resource to install packages required for compiling C software from source. This resource was ported from the `build-essential` community cookbook.
+
+`Note`: This resource no longer configures msys2 on Windows systems.
+
+### chef_handler
+
+Use the chef_handler resource to install or uninstall Chef reporting/exception handlers. This resource was ported from the `chef_handler` community cookbook.
+
+### dmg_package
+
+Use the dmg_package resource to install a dmg 'package'. The resource will retrieve the dmg file from a remote URL, mount it using hdiutil, copy the application (.app directory) to the specified destination (/Applications), and detach the image using hdiutil. The dmg file will be stored in the Chef::Config[:file_cache_path]. This resource was ported from the `dmg` community cookbook.
+
+### homebrew_cask
+
+Use the homebrew_cask resource to install binaries distributed via the Homebrew package manager. This resource was ported from the `homebrew` community cookbook.
+
+### homebrew_tap
+
+Use the homebrew_tap resource to add additional formula repositories to the Homebrew package manager. This resource was ported from the `homebrew` community cookbook.
+
+### hostname
+
+Use the hostname resource to set the system's hostname, configure hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks. This resource was ported from the `chef_hostname` community cookbook.
+
+### macos_userdefaults
+
+Use the macos_userdefaults resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works. This resource was ported from the `mac_os_x` community cookbook.
+
+### ohai_hint
+
+Use the ohai_hint resource to pass hint data to Ohai to aid in configuration detection. This resource was ported from the `ohai` community cookbook.
+
+### openssl_dhparam
+
+Use the openssl_dhparam resource to generate dhparam.pem files. If a valid dhparam.pem file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam file, it will be overwritten. This resource was ported from the `openssl` community cookbook.
+
+### openssl_rsa_private_key
+
+Use the openssl_rsa_private_key resource to generate RSA private key files. If a valid RSA key file can be opened at the specified location, no new file will be created. If the RSA key file cannot be opened, either because it does not exist or because the password to the RSA key file does not match the password in the recipe, it will be overwritten. This resource was ported from the `openssl` community cookbook.
+
+### openssl_rsa_public_key
+
+Use the openssl_rsa_public_key resource to generate RSA public key files given a RSA private key. This resource was ported from the `openssl` community cookbook.
+
+### rhsm_errata
+
+Use the rhsm_errata resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts. This resource was ported from the `redhat_subscription_manager` community cookbook.
+
+### rhsm_errata_level
+
+Use the rhsm_errata_level resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed. This resource was ported from the `redhat_subscription_manager` community cookbook.
+
+### rhsm_register
+
+Use the rhsm_register resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server. This resource was ported from the `redhat_subscription_manager` community cookbook.
+
+### rhsm_repo
+
+Use the rhsm_repo resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions. This resource was ported from the `redhat_subscription_manager` community cookbook.
+
+### rhsm_subscription
+
+Use the rhsm_subscription resource to add or remove Red Hat Subscription Manager subscriptions for your host. This can be used when a host's activation_key does not attach all necessary subscriptions to your host. This resource was ported from the `redhat_subscription_manager` community cookbook.
+
+### sudo
+
+Use the sudo resource to add or remove individual sudo entries using `sudoers.d` files. Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the `#includedir` directive introduced in version 1.7.2\. This resource does not enforce installation of the required sudo version. Supported releases of Ubuntu, Debian, SuSE, and RHEL (6+) all support this feature. This resource was ported from the `sudo` community cookbook.
+
+### swap_file
+
+Use the swap_file resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host. This resource was ported from the `swap` community cookbook.
+
+### sysctl
+
+Use the sysctl resource to set kernel parameters using the sysctl command line tool and configuration files in the system's `sysctl.d` directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If an existing value was already set for the value it will be backed up to the node and restored if the :remove action is used later. This resource was ported from the `sysctl` community cookbook.
+
+`Note`: This resource no longer backs up existing key values to the node when changing values as we have done in the sysctl cookbook previously. The resource has also been renamed from `sysctl_param` to `systctl` with backwards compatibility for the previous name.
+
+### windows_ad_join
+
+Use the windows_ad_join resource to join a Windows Active Directory domain and reboot the node. This resource is based on the `win_ad_client` resource in the `win_ad` community cookbook, but is not backwards compatible with that resource.
+
+### windows_auto_run
+
+Use the windows_auto_run resource to set applications to run at logon. This resource was ported from the `windows` community cookbook.
+
+### windows_feature
+
+Use the windows_feature resource to add, remove or delete Windows features and roles. This resource calls the `windows_feature_dism` or `windows_feature_powershell` resources depending on the specified installation method and defaults to dism, which is available on both Workstation and Server editions of Windows. This resource was ported from the `windows` community cookbook.
+
+### windows_font
+
+Use the windows_font resource to install or remove font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well. This resource was ported from the `windows` community cookbook.
+
+### windows_printer
+
+Use the windows_printer resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system. This resource was ported from the `windows` community cookbook.
+
+### windows_printer_port
+
+Use the windows_printer_port resource to create and delete TCP/IPv4 printer ports on Windows. This resource was ported from the `windows` community cookbook.
+
+### windows_shortcut
+
+Use the windows_shortcut resource to create shortcut files on Windows. This resource was ported from the `windows` community cookbook.
+
+## Custom Resource Improvements
+
+We've expanded the DSL for custom resources with new functionality to better document your resources and help users with errors and upgrades. Many resources in Chef itself are now using this new functionality, and you'll see more updated to take advantage of this it in the future.
+
+### Deprecations in Cookbook Resources
+
+Chef 14 provides new primitives that allow you to deprecate resources or properties with the same functionality used for deprecations in Chef Client resources. This allows you make breaking changes to enterprise or community cookbooks with friendly notifications to downstream cookbook consumers directly in the Chef run.
+
+Deprecate the foo_bar resource in a cookbook:
+
+```ruby
+deprecated "The foo_bar resource has been deprecated and will be removed in the next major release of this cookbook scheduled for 12/25/2018!"
+
+property :thing, String, name_property: true
+
+action :create do
+ # you'd probably have some actual chef code here
+end
+```
+
+Deprecate the thing2 property in a resource
+
+```ruby
+property :thing2, String, deprecated: 'The thing2 property has been deprecated and will be removed in the next major release of this cookbook scheduled for 12/25/2018!'
+```
+
+Rename a property with a deprecation warning for users of the old property name
+
+```ruby
+deprecated_property_alias 'thing2', 'the_second_thing', 'The thing2 property was renamed the_second_thing in the 2.0 release of this cookbook. Please update your cookbooks to use the new property name.'
+```
+
+### validation_message
+
+Validation messages allow you give the user a friendly error message when any validation on a property fails.
+
+Provide a friendly message when a regex fails:
+
+```ruby
+property :repo_name, String, regex: [/^[^\/]+$/], validation_message: "The repo_name property cannot contain a forward slash '/'",
+```
+
+### Resource Documentation
+
+You can now include documentation that describes how a resource is to be used. Expect this data to be consumed by Chef and other tooling in future releases.
+
+A resource which includes description and introduced values in the resource, actions, and properties:
+
+```ruby
+description 'The apparmor_policy resource is used to add or remove policy files from a cookbook file'
+introduced '14.1'
+
+property :source_cookbook, String,
+         description: 'The cookbook to source the policy file from'
+property :source_filename, String,
+         description: 'The name of the source file if it differs from the apparmor.d file being created'
+
+action :add do
+  description 'Adds an apparmor policy'
+
+  # you'd probably have some actual chef code here
+end
+```
+
+## Improved Resources
+
+Many existing resources now include new actions and properties that expand their functionality.
+
+### apt_package
+
+`apt_package` includes a new `overwrite_config_files` property. Setting this new property to true is equivalent to passing `-o Dpkg::Options::="--force-confnew"` to apt, and allows you to install packages that prompt the user to overwrite config files. Thanks @ccope for this new property.
+
+### env
+
+The `env` resource has been renamed to `windows_env` as it only supports the Windows platform. Existing cookbooks using `env` will continue to function, but should be updated to use the new name.
+
+### ifconfig
+
+`ifconfig` includes a new `family` property for setting the network family on Debian systems. Thanks @martinisoft for this new property.
+
+### registry_key
+
+The `sensitive` property can now be used in `registry_key` to suppress the output of the key's data from logs and error messages. Thanks @shoekstra for implementing this.
+
+### powershell_package
+
+`powershell_package` includes a new `source` property to allow specifying the source of the package. Thanks @Happycoil for this new property.
+
+### systemd_unit
+
+`systemd_unit` includes the following new actions:
+
+- `preset` - Restore the preset enable/disable configuration for a unit
+- `revert` - Revert to a vendor's version of a unit file
+- `reenable` - Reenable a unit file
+
+Thanks @nathwill for these new actions.
+
+### windows_service
+
+`windows_service` now includes actions for fully managing services on Windows, in addition to the previous actions for starting/stopping/enabling services.
+
+- `create` - Create a new service
+- `delete` - Delete an existing service
+- `configure` - Reconfigure an existing service
+
+Thanks @jasonwbarnett for these new actions
+
+### route
+
+`route` includes a new `comment` property.
+
+Thanks Thomas Doherty for adding this new property.
+
+## Expanded Configuration Detection
+
+Ohai has been expanded to collect more information than ever. This should make writing cross-platform and cross cloud cookbooks simpler.
+
+### Windows Kernel information
+
+The kernel plugin now reports the following information on Windows:
+
+- `node['kernel']['product_type']` - Workstation vs. Server editions of Windows
+- `node['kernel']['system_type']` - What kind of hardware are we installed on (Desktop, Mobile, Workstation, Enterprise Server, etc.)
+- `node['kernel']['server_core']` - Are we on Windows Server Core edition?
+
+### Cloud Detection
+
+Ohai now detects the Scaleway cloud and provides additional configuration information for systems running on Azure.
+
+### Virtualization / Container Detection
+
+In addition to detecting if a system is a Docker host, we now provide a large amount of Docker configuration information available at `node['docker']`. This includes the release of Docker, installed plugins, network config, and the number of running containers.
+
+Ohai also now properly detects LXD containers and macOS guests running on VirtualBox / VMware. This data is available in `node['virtualization']['systems']`.
+
+### Optional Ohai Plugins
+
+Ohai now includes the ability to mark plugins as optional, which skips those plugins by default. This allows us to ship additional plugins, which some users may find useful, but not all users want that data collected in the node object on a Chef server. The change introduces two new configuration options; `run_all_plugins` which runs everything including optional plugins, and `optional_plugins` which allows you to run plugins marked as optional.
+
+By default we will now be marking the `lspci`, `sessions` `shard` and `passwd` plugins as optional. Passwd has been particularly problematic for nodes attached to LDAP or AD where it attempts to write the entire directory's contents to the node. If you previously disabled this plugin via Ohai config, you no longer need to. Hurray!
+
+## Other Changes
+
+### Ruby 2.5
+
+Ruby has been updated to version 2.5 bringing a 10% performance improvement and improved functionality.
+
+### InSpec 2.0
+
+InSpec has been updated to the 2.0 release. InSpec 2.0 brings compliance automation to the cloud, with new resource types specifically built for AWS and Azure clouds. Along with these changes are major speed improvements and quality of life updates. Please visit <https://www.inspec.io/> for more information.
+
+### Policyfile Hoisting
+
+Many users of Policyfiles rely on "hoisting" to provide group specific attributes. This approach was formalized in the poise-hoist extension, and is now included in Chef 14.
+
+To hoist an attribute, the user provides a default attribute structure in their Policyfile similar to:
+
+```ruby
+default['staging']['myapp']['title'] = "My Staging App" default['production']['myapp']['title'] = "My App"
+```
+
+and then accesses the node attribute in their cookbook as:
+
+```ruby
+node['myapp']['title']
+```
+
+The correct attribute is then provided based on the policy_group of the node, so with a policy_group of staging the attribute would contain "My Staging App".
+
+### yum_package rewrite
+
+yum_package received a ground up rewrite that greatly improves both the performance and functionality while also resolving a dozen existing issues. It introduces a new caching method that runs for the duration of the chef-client process. This caching method speeds up each package install and takes 1/2 the memory of the previous `yum-dump.py` process.
+
+yum_package should now take any argument that `yum install` does and operate the same way, including version constraints "foo < 1.2.3" and globs "foo-1.2*" along with arches "foo.i386" and in combinations
+
+Package with a version constraint:
+
+```ruby
+yum_package "foo < 1.2.3"
+```
+
+Installing a package via what it provides:
+
+```ruby
+yum_package "perl(Git)"
+```
+
+### powershell_exec Mixin
+
+Since our supported Windows platforms can all run .NET Framework 4.0 and PowerShell 4.0 we have taken time to add a new helper that will allow for faster and safer interactions with the system PowerShell. You will be able to use the powershell_exec mixin in most places where you would have previously used powershell_out. For comparison, a basic benchmark test to return the $PSVersionTable 100 times completed 7.3X faster compared to the powershell_out method. The majority of the time difference is because of less time spent in invocation. So we believe it has big future potential where multiple calls to PowerShell are required inside (for example) a custom resource. Many core Chef resources will be updated to use this new mixin in future releases.
+
+### Logging Improvements
+
+Chef now includes a new log level of `:trace` in addition to the existing `:info`, `:warn`, and `:debug` levels. With the introduction of `trace` level logging we've moved a large amount of logging that is more useful for Chef developers from `debug` to `trace`. This makes it easier for Chef Cookbook developers to use `debug` level to get useful information.
+
+## Breaking Changes
+
+This release completes the deprecation process for many of the deprecations that were warnings throughout the Chef 12 and Chef 13 releases.
+
+### erl_call Resource
+
+The erl_call resource was deprecated in Chef 13.7 and has been removed.
+
+### deploy Resource
+
+The deploy resource was deprecated in Chef 13.6 and been removed. If you still require this resource, it is available in the new `deploy_resource` cookbook at <https://supermarket.chef.io/cookbooks/deploy_resource>
+
+### Windows 2003 Support
+
+Support for Windows 2003 has been removed from both Chef and Ohai, improving the performance of Chef on Windows hosts.
+
+### knife bootstrap options --distro and --template_file
+
+The `--distro` and `--template_file` knife bootstrap flags were deprecated in Chef 12.0 and have now been removed.
+
+### knife help
+
+The knife help functionality that read legacy Chef manpages has been removed. These manpages had not been updated in many years and were often quite wrong. Running knife help will now simply show the help menu.
+
+### chocolatey_package :uninstall Action
+
+The chocolatey_package resource in the chocolatey cookbook supported an `:uninstall` action. When this resource was moved into the Chef Client we allowed this action with a deprecation warning. This action is now removed.
+
+### Property names not using new_resource.NAME
+
+Previously if a user wrote a custom resource with a property named `foo` they could reference it throughout the resource using the name `foo`. This caused multiple edge cases where the property name could conflict with resources or methods in Chef. Properties now must be referenced as `new_resource.foo`. This was already the case when writing LWRPs.
+
+### epic_fail
+
+The original name for the `ignore_failure` property in resource was `epic_fail`. The legacy name has been removed.
+
+### Legacy Mixins
+
+Several legacy mixins mostly used in older HWRPs have been removed. Usage of these mixins has resulted in deprecation warnings for several years and they are rarely used in cookbooks available on the Supermarket.
+
+- Chef::Mixin::LanguageIncludeAttribute
+- Chef::Mixin::RecipeDefinitionDSLCore
+- Chef::Mixin::LanguageIncludeRecipe
+- Chef::Mixin::Language
+- Chef::DSL::Recipe::FullDSL
+
+### cloud_v2 and filesystem2 Ohai Plugins
+
+In Chef 13 the `cloud_v2` plugin replaced data at `node['cloud']` and `filesystem2` replaced data at `node['filesystem']`. For compatibility with cookbooks that were previously using the "v2" data we continued to write data to both locations (ie: both node['filesystem'] and node['filesystem2']). We now no longer write data to the "v2" locations which greatly reduces the amount of data we need to store on the Chef server.
+
+### Ipscopes Ohai Plugin Removed
+
+The ipscopes plugin has been removed as it duplicated data already present in the network plugins and required the user to install an additional gem into the Chef installation.
+
+### Ohai libvirt attributes moved
+
+The libvirt Ohai plugin now writes data to `node['libvirt']` instead of writing to various locations in `node['virtualization']`. This plugin required installing an additional gem into the Chef installation and thus was infrequently used.
+
+### Ohai Plugin V6 Support Removed
+
+In 2014 we introduced Ohai v7 with a greatly improved plugin format. With Chef 14 we no longer support loading of the legacy "v6" plugin format.
+
+### Newly-disabled Ohai Plugins
+
+As mentioned above we now support an `optional` flag for Ohai plugins and have marked the `sessions`, `lspci`, and `passwd` plugins as optional, which disables them by default. If you need one of these plugins you can include them using `optional_plugins`.
+
+optional_plugins in the client.rb file:
+
+```ruby
+optional_plugins [ "lspci", "passwd" ]
+```
+
+# Chef Client Release Notes 13.8:
+
+## Revert attributes changes from 13.7
+
+Per <https://discourse.chef.io/t/regression-in-chef-client-13-7-16/12518/1> , there was a regression in how arrays and hashes were handled in 13.7\. In 13.8, we've reverted to the same code as 13.6.
+
+## Continuing work on `windows_task`
+
+13.8 has better validation for the `idle_time` property, when using the `on_idle` frequency.
+
+## Security Updates
+
+- Updated libxml2 to 2.9.7; fixes: CVE-2017-15412
 
 # Chef Client Release Notes 13.7:
 
@@ -75,7 +465,7 @@ The mdadm plugin has been updated to properly handle arrays with more than 10 di
 
 ## Bugfixes
 
-  - Resolved a regression in 13.6.0 that prevented upgrading packages on Debian/Ubuntu when the package name contained a tilde. 
+- Resolved a regression in 13.6.0 that prevented upgrading packages on Debian/Ubuntu when the package name contained a tilde.
 
 ## Security Updates
 
@@ -86,31 +476,21 @@ The mdadm plugin has been updated to properly handle arrays with more than 10 di
 
 ## `deploy` Resource Is Deprecated
 
-The `deploy` resource (and its alter ego `deploy_revision`) have been deprecated,
-to be removed in Chef 14. This is being done because this resource is considered
-overcomplicated and error-prone in the modern Chef ecosystem. A compatibility
-cookbook will be available to help users migrate during the Chef 14 release
-cycle. See [the deprecation documentation](https://docs.chef.io/deprecations_deploy_resource.html)
-for more information.
+The `deploy` resource (and its alter ego `deploy_revision`) have been deprecated, to be removed in Chef 14\. This is being done because this resource is considered overcomplicated and error-prone in the modern Chef ecosystem. A compatibility cookbook will be available to help users migrate during the Chef 14 release cycle. See [the deprecation documentation](https://docs.chef.io/deprecations_deploy_resource.html) for more information.
 
-## zypper\_package supports package downgrades
+## zypper_package supports package downgrades
 
-`zypper_package` now supports downgrading installed packages with the
-`allow_downgrade` property.
+`zypper_package` now supports downgrading installed packages with the `allow_downgrade` property.
 
 ## InSpec updated to 1.42.3
 
 ## Reserve certain Data Bag names
 
-It's no longer possible to create data bags named `node`, `role`,
-`client`, or `environment`. Existing data bags will continue to work as
-before.
+It's no longer possible to create data bags named `node`, `role`, `client`, or `environment`. Existing data bags will continue to work as before.
 
 ## Properly use yum on RHEL 7
 
-If both dnf and yum were installed, in some circumstances the yum
-provider might choose to run dnf, which is not what we intended it to
-do. It now properly runs yum, all the time.
+If both dnf and yum were installed, in some circumstances the yum provider might choose to run dnf, which is not what we intended it to do. It now properly runs yum, all the time.
 
 ## Ohai 13.6 Release Notes:
 
@@ -136,7 +516,7 @@ The Packages plugin now supports gathering packages data on Amazon Linux
 
 ### Deprecation updates
 
-In Ohai 13 we replaced the filesystem and cloud plugins with the filesystem2 and cloud_v2 plugins. To maintain compatibility with users of the previous V2 plugins we write data to both locations. We had originally planned to continue writing data to both locations until Chef 15. Instead due to the large amount of duplicate node data this introduces we are updating OHAI-11 and OHAI-12 deprecations to remove node['cloud_v2'] and node['filesystem2'] with the release of Chef 14 in April 2018.
+In Ohai 13 we replaced the filesystem and cloud plugins with the filesystem2 and cloud_v2 plugins. To maintain compatibility with users of the previous V2 plugins we write data to both locations. We had originally planned to continue writing data to both locations until Chef 15\. Instead due to the large amount of duplicate node data this introduces we are updating OHAI-11 and OHAI-12 deprecations to remove node['cloud_v2'] and node['filesystem2'] with the release of Chef 14 in April 2018.
 
 # Chef Client Release Notes 13.5:
 
@@ -146,10 +526,7 @@ This means that passwords passed to mount won't show up in logs.
 
 ## The `windows_task` resource now correctly handles `start_day`
 
-Previously, the resource would accept any date that was formatted
-correctly in the local locale, unlike the Windows cookbook and Windows
-itself. We now only support the `MM/DD/YYYY` format, in common with the
-Windows cookbook.
+Previously, the resource would accept any date that was formatted correctly in the local locale, unlike the Windows cookbook and Windows itself. We now only support the `MM/DD/YYYY` format, in common with the Windows cookbook.
 
 ## InSpec updated to 1.39.1
 
@@ -157,90 +534,79 @@ Windows cookbook.
 
 ### Correctly detect IPv6 routes ending in ::
 
-Previously we would ignore routes that ended `::`, and now we properly
-detect them.
+Previously we would ignore routes that ended `::`, and now we properly detect them.
 
 ### Plugin run time is now measured
 
-Debug logs will show the length of time each plugin takes to run, making
-debugging of long ohai runs easier.
+Debug logs will show the length of time each plugin takes to run, making debugging of long ohai runs easier.
 
 # Chef Client Release Notes 13.4:
 
 ## Security release of Ruby
 
 Chef Client 13.4 includes Ruby 2.4.2 to fix the following CVEs:
-  * CVE-2017-0898
-  * CVE-2017-10784
-  * CVE-2017-14033
-  * CVE-2017-14064
+
+- CVE-2017-0898
+- CVE-2017-10784
+- CVE-2017-14033
+- CVE-2017-14064
 
 ## Security release of RubyGems
 
 Chef Client 13.4 includes RubyGems 2.6.13 to fix the following CVEs:
-  * CVE-2017-0899
-  * CVE-2017-0900
-  * CVE-2017-0901
-  * CVE-2017-0902
+
+- CVE-2017-0899
+- CVE-2017-0900
+- CVE-2017-0901
+- CVE-2017-0902
 
 ## Ifconfig provider on Red Hat now supports additional properties
 
-It is now possible to set `ETHTOOL_OPTS`, `BONDING_OPTS`, `MASTER` and
-`SLAVE` properties on interfaces on Red Hat compatible systems. See https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s1-networkscripts-interfaces.html for further information
+It is now possible to set `ETHTOOL_OPTS`, `BONDING_OPTS`, `MASTER` and `SLAVE` properties on interfaces on Red Hat compatible systems. See <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s1-networkscripts-interfaces.html> for further information
 
 ### Properties
 
-*   `ethtool\_opts`<br/>
-    **Ruby types:** String</br>
-    **Platforms:** Fedora, RHEL, Amazon Linux
-    A string containing arguments to ethtool. The string will be wrapped
-    in double quotes, so ensure that any needed quotes in the property
-    are surrounded by single quotes
-
-*   `bonding\_opts`<br/>
-    **Ruby types:** String</br>
-    **Platforms:** Fedora, RHEL, Amazon Linux
-    A string containing configuration parameters for the bonding device.
-
-*   `master`<br/>
-    **Ruby types:** String</br>
-    **Platforms:** Fedora, RHEL, Amazon Linux
-    The channel bonding interface that this interface is linked to.
-
-*   `slave`<br/>
-    **Ruby types:** String</br>
-    **Platforms:** Fedora, RHEL, Amazon Linux
-    Whether the interface is controlled by the channel bonding interface
-    defined by `master`, above.
+- `ethtool_opts`<br>
+  **Ruby types:** String<br>
+  **Platforms:** Fedora, RHEL, Amazon Linux A string containing arguments to ethtool. The string will be wrapped in double quotes, so ensure that any needed quotes in the property are surrounded by single quotes
+
+- `bonding_opts`<br>
+  **Ruby types:** String<br>
+  **Platforms:** Fedora, RHEL, Amazon Linux A string containing configuration parameters for the bonding device.
+
+- `master`<br>
+  **Ruby types:** String<br>
+  **Platforms:** Fedora, RHEL, Amazon Linux The channel bonding interface that this interface is linked to.
+
+- `slave`<br>
+  **Ruby types:** String<br>
+  **Platforms:** Fedora, RHEL, Amazon Linux Whether the interface is controlled by the channel bonding interface defined by `master`, above.
 
 ## Chef Vault is now included
 
-Chef Client 13.4 now includes the `chef-vault` gem, making it easier for
-users of chef-vault to use their encrypted items.
+Chef Client 13.4 now includes the `chef-vault` gem, making it easier for users of chef-vault to use their encrypted items.
 
 ## Windows `remote_file` resource with alternate credentials
 
-The `remote_file` resource now supports the use of credentials on Windows when accessing a remote UNC path on Windows such as `\\myserver\myshare\mydirectory\myfile.txt`. This
-allows access to the file at that path location even if the Chef client process identity does not have permission to access the file. The new properties `remote_user`, `remote_domain`, and `remote_password` may be used to specify credentials with access to the remote file so that it may be read.
+The `remote_file` resource now supports the use of credentials on Windows when accessing a remote UNC path on Windows such as `\\myserver\myshare\mydirectory\myfile.txt`. This allows access to the file at that path location even if the Chef client process identity does not have permission to access the file. The new properties `remote_user`, `remote_domain`, and `remote_password` may be used to specify credentials with access to the remote file so that it may be read.
 
-**Note**: This feature is mainly used for accessing files between two nodes in different domains and having different user accounts.
-In case the two nodes are in same domain, `remote_file` resource does not need `remote_user` and `remote_password` specified because the user has the same access on both systems through the domain.
+**Note**: This feature is mainly used for accessing files between two nodes in different domains and having different user accounts. In case the two nodes are in same domain, `remote_file` resource does not need `remote_user` and `remote_password` specified because the user has the same access on both systems through the domain.
 
 ### Properties
 
 The following properties are new for the `remote_file` resource:
 
-*   `remote_user`</br>
-    **Ruby types:** String</br>
-    *Windows only:* The user name of a user with access to the remote file specified by the `source` property. Default value: `nil`. The user name may optionally be specifed with a domain, i.e. `domain\user` or `user@my.dns.domain.com` via Universal Principal Name (UPN) format. It can also be specified without a domain simply as `user` if the domain is instead specified using the `remote_domain` attribute. Note that this property is ignored if `source` is not a UNC path. If this property is specified, the `remote_password` property **must** be specified.
+- `remote_user`<br>
+  **Ruby types:** String<br>
+  _Windows only:_ The user name of a user with access to the remote file specified by the `source` property. Default value: `nil`. The user name may optionally be specifed with a domain, i.e. `domain\user` or `user@my.dns.domain.com` via Universal Principal Name (UPN) format. It can also be specified without a domain simply as `user` if the domain is instead specified using the `remote_domain` attribute. Note that this property is ignored if `source` is not a UNC path. If this property is specified, the `remote_password` property **must** be specified.
 
-*   `remote_password`</br>
-    **Ruby types** String</br>
-    *Windows only:* The password of the user specified by the `remote_user` property. Default value: `nil`. This property is mandatory if `remote_user` is specified and may only be specified if `remote_user` is specified. The `sensitive` property for this resource will automatically be set to `true` if `remote_password` is specified.
+- `remote_password`<br>
+  **Ruby types** String<br>
+  _Windows only:_ The password of the user specified by the `remote_user` property. Default value: `nil`. This property is mandatory if `remote_user` is specified and may only be specified if `remote_user` is specified. The `sensitive` property for this resource will automatically be set to `true` if `remote_password` is specified.
 
-*   `remote_domain`</br>
-    **Ruby types** String</br>
-    *Windows only:* The domain of the user user specified by the `remote_user` property. Default value: `nil`. If not specified, the user and password properties specified by the `remote_user` and `remote_password` properties will be used to authenticate that user against the domain in which the system hosting the UNC path specified via `source` is joined, or if that system is not joined to a domain it will authenticate the user as a local account on that system. An alternative way to specify the domain is to leave this property unspecified and specify the domain as part of the `remote_user` property.
+- `remote_domain`<br>
+  **Ruby types** String<br>
+  _Windows only:_ The domain of the user user specified by the `remote_user` property. Default value: `nil`. If not specified, the user and password properties specified by the `remote_user` and `remote_password` properties will be used to authenticate that user against the domain in which the system hosting the UNC path specified via `source` is joined, or if that system is not joined to a domain it will authenticate the user as a local account on that system. An alternative way to specify the domain is to leave this property unspecified and specify the domain as part of the `remote_user` property.
 
 ### Examples
 
@@ -254,7 +620,9 @@ remote_file "E://domain_test.txt"  do
   remote_password "password"
 end
 ```
+
 OR
+
 ```ruby
 remote_file "E://domain_test.txt"  do
   source  "\\\\myserver\\myshare\\mydirectory\\myfile.txt"
@@ -273,7 +641,9 @@ remote_file "E://domain_test.txt"  do
   remote_password "password"
 end
 ```
+
 OR
+
 ```ruby
 remote_file "E://domain_test.txt"  do
   source  "\\\\myserver\\myshare\\mydirectory\\myfile.txt"
@@ -386,7 +756,6 @@ Sample data now available under azure:
 
 The Package plugin has been updated to include package information on Arch Linux systems.
 
-
 # Chef Client Release Notes 13.3:
 
 ## Unprivileged Symlink Creation on Windows
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 9825372070..f825db804e 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -22,8 +22,8 @@ class Chef
     class DmgPackage < Chef::Resource
       resource_name :dmg_package
 
-      description "Use the dmg_package resourceto install a DMG 'Package'. The resource will retrieve the"\
-                  " DMG file from a remote URL, mount it using hdid, copy the application (.app directory)"\
+      description "Use the dmg_package resource to install a dmg 'package'. The resource will retrieve the"\
+                  " dmg file from a remote URL, mount it using OS X's hdidutil, copy the application (.app directory)"\
                   " to the specified destination (/Applications), and detach the image using hdiutil. The dmg file"\
                   " will be stored in the Chef::Config[:file_cache_path]."
       introduced "14.0"
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index a863b14f1d..f785d1b620 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -6,7 +6,8 @@ class Chef
       resource_name :hostname
       provides :hostname
 
-      description "Sets the systems hostname, ensures that reboot will preserve the hostname, and re-runs the ohai plugin so the hostname will be available in subsequent cookbooks."
+      description "Use the hostname resource to set the system's hostname, configure hostname and hosts config"\
+                  " file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks."
       introduced "14.0"
 
       property :hostname, String,
diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index 45be356d1b..abdf08c1d4 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -25,10 +25,9 @@ class Chef
       provides :mac_os_x_userdefaults
       provides :macos_userdefaults
 
-      description "Use the macos_userdefaults resource to manage the macOS user defaults"\
-                  " system. The properties to the resource are passed to the defaults command"\
-                  " and the parameters follow convention of the macOS command. See the defaults(1)"\
-                  " man page for details on how the tool works."
+      description "Use the macos_userdefaults resource to manage the macOS user defaults system. The properties"\
+                  " of this resource are passed to the defaults command, and the parameters follow the convention"\
+                  " of that command. See the defaults(1) man page for details on how the tool works."
       introduced "14.0"
 
       property :domain, String,
diff --git a/lib/chef/resource/rhsm_subscription.rb b/lib/chef/resource/rhsm_subscription.rb
index 60ea7a7dd8..4fad8fa650 100644
--- a/lib/chef/resource/rhsm_subscription.rb
+++ b/lib/chef/resource/rhsm_subscription.rb
@@ -22,8 +22,8 @@ class Chef
     class RhsmSubscription < Chef::Resource
       resource_name :rhsm_subscription
 
-      description "Use tthe rhsm_subscription resource to add additional Redhat Subscription Manager subscriptions"\
-                  " to your host. This can be used when a host's activation_key"\
+      description "Use the rhsm_subscription resource to add or remove Red Hat Subscription Manager"\
+                  " subscriptions from your host. This can be used when a host's activation_key"\
                   " does not attach all necessary subscriptions to your host."
       introduced "14.0"
 
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index f288d82f39..0eb3c562fd 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -28,10 +28,10 @@ class Chef
       provides "sudo"
 
       description "Use the sudo resource to add or remove individual sudo entries using sudoers.d files."\
-                  " Sudo version 1.7.2 or newer is required to use the sudo resource as it relies on the"\
-                  " '#includedir' directive introduced in version 1.7.2. The resource does not enforce"\
-                  " installing the version. Supported releases of Ubuntu, Debian and RHEL (6+) all support"\
-                  " this feature."
+                  " Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the"\
+                  " '#includedir' directive introduced in version 1.7.2. This resource does not enforce"\
+                  " installation of the required sudo version. Supported releases of Ubuntu, SuSE, Debian,"\
+                  " and RHEL (6+) all support this feature."
       introduced "14.0"
 
       # acording to the sudo man pages sudo will ignore files in an include dir that have a `.` or `~`
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index 6beb20c976..6bb29515ae 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -23,7 +23,7 @@ class Chef
       resource_name :swap_file
       provides :swap_file
 
-      description "Use the swap_file resource to create or delete swap files on Linux systems."
+      description "Use the swap_file resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
       introduced "14.0"
 
       property :path, String,
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index 84778e2bcb..d7bb1180c4 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -24,7 +24,9 @@ class Chef
       resource_name :windows_feature
       provides :windows_feature
 
-      description "Using the windows_feature resource to add, remove or delete Windows features and roles"
+      description "Use the windows_feature resource to add, remove or delete Windows features and roles. This resource calls"\
+                  " the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation"\
+                  " method and defaults to dism, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/lib/chef/resource/windows_font.rb b/lib/chef/resource/windows_font.rb
index 7ff098cc88..6f82e3cd8f 100644
--- a/lib/chef/resource/windows_font.rb
+++ b/lib/chef/resource/windows_font.rb
@@ -26,7 +26,7 @@ class Chef
       provides :windows_font
 
       description "Use the windows_font resource to install or remove font files on Windows."\
-                  " Sources the font by default from the cookbook using the resource, but a URI"\
+                  " By default, the font is sourced from the cookbook using the resource, but a URI"\
                   " source can be specified as well."
       introduced "14.0"