Update documentation / release notes

Cherry-pick of 73d7480

3 files changed, 235 insertions, 300 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1062f383e8..1e5272df37 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Chef Client Changelog
 
+
+## Unreleased: 11.16.0
+
+* Add `dsc_script` resource to Chef for PowerShell DSC support on Windows
+
 ## Last Release: 11.14.6:
 
 * Modify action for env raises Chef::Exceptions::Env exception on Windows (Chef Issues 1754)
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 0660e9a38d..e509e38ce8 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -6,96 +6,249 @@ Example Doc Change:
 Description of the required change.
 -->
 
-### New knife command: knife serve
-You can now run a persistent chef-zero against your local repository:
+### New dsc\_script resource
 
-```
-knife serve
-```
+The `dsc_script` resource for Windows systems that allows cookbook authors to embed [PowerShell Desired
+State Configuration](http://technet.microsoft.com/en-us/library/dn249912.aspx)
+(DSC) script code or re-use existing DSC script
+artifacts in a cookbook. It is similar to other Chef `script` resources like
+`powershell_script` in that it allows another language to be used from within
+the Chef Domain Specific Language (DSL). 
 
-knife serve takes --chef-zero-host=HOST, --chef-zero-port=PORT and --chef-repo-path=PATH variables. By default, it will do exactly the same thing as the local mode argument to knife and chef-client (-z), locating your chef-repo-path automatically and binding to port 8900.  It will print the URL it is bound to so that you can add it to your knife.rb files.
+#### DSC Prerequisites
 
-### --run-lock-timeout for chef-client and chef-solo
-You can now add a timeout for the maximum time a client run waits on another client run to finish.
-The default is to wait indefinitely.
-Setting the run lock timeout to 0 causes the second client run to exit immediately.
+Use of the `dsc_script` resource requires the following components on a
+Windows system:
 
-This can be configured in your config file:
-```
-run_lock_timeout SECONDS
-```
+* **PowerShell version 4.0**, which can be configured on the target system through Chef using the
+[PowerShell cookbook](https://supermarket.getchef.com/cookbooks/powershell)
+available at [Chef Supermarket](http://supermarket.getchef.com).
+* **WinRM** service enabled: The **WinRM** service can be enabled on the
+    system by executing the command
 
-Or via the command line:
-```
-chef-client --run-lock-timeout SECONDS
-```
+    `winrm quickconfig`
+    
+
+#### What is DSC?
+
+DSC is described in detail at the [PowerShell DSC site](http://technet.microsoft.com/en-us/library/dn249912.aspx). In summary, DSC is a tool similar to Chef for describing the configuration of a system and enacting the configuration. DSC uses a DSL based on the concept of *resources*, which are conceptually the same as resources in the Chef DSL. Like Chef, DSC is idempotent. Because of these similarities, it natural and useful to be able to use DSC from Chef.
+
+Unlike Chef, DSC's DSL is embedded in the PowerShell language environment; Chef's is embedded in Ruby. DSC is exposed in PowerShell through the `Configuration` language element, which takes a PowerShell script block and other parameters similar to a PowerShell function. Within the script block are instances of resources, very much the way resources in Chef are given within a recipe.
+
+The `dsc_script` resource allows this PowerShell DSC code to be embedded within a Chef recipe.
+
+Many DSC resources are exact analogs of Chef resources (e.g. DSC's
+`File` resource); therefore, `dsc_script` is most useful in the context of Chef when it is utilized to manage
+resources that are *not* supported directly in Chef, such as DSC's `Archive`
+resource which decompresses **.zip** files. Another use case for `dsc_script`
+is the use in Chef of already-existing PowerShell DSC scripts that perform
+important tasks.
+
+#### `dsc_script` actions
 
-#### New knife command: knife node environment set
-You can now easily set the environment for an existing node without editing the node object:
+In addition to the standard `:nothing` action, this resource has the following action:
 
+|Action|Description|
+|------|-----------|
+|`:run`|This is the default action. This action triggers PowerShell DSC components of Windows to configure the system according to the configuration specified in `dsc_script`. |
+
+Note that since all DSC code is idempotent, use of guard expressions is not
+required with the `dsc_script` resource to implement idempotence. 
+
+#### `dsc_script` attributes
+
+`dsc_script` honors common Chef resource attributes in addition to the following:
+
+|Attribute|Description|
+|---------|-----------|
+|`code`|This attribute is a `String` that contains PowerShell DSC code for a configuration. If `code` is non-`nil`, it must be set to the value of a PowerShell script block (without enclosing braces) that be passed to a `Configuration` element of the PowerShell DSC DSL. This attribute **MUST NOT** be set to `nil` value if the `command` attribute is to anything other than `nil`. The default value is `nil`.|
+|`command`|Path to a .ps1 file containing PowerShell DSC script code with which to configure the node. This file must be capable of being executed as a script outside of Chef to generate a valid DSC configuration according to DSC documentation. This attribute **MUST NOT** be set `nil` if the `code` attribute is set non-`nil`. The default value is `nil`.|
+|`configuration_name`|This attribute is a `String` used to specify the name given to a `Configuration` element in the script code specified by `command` that identifies the configuration to apply. It **MUST NOT** be specified if `code` is non-`nil`. If `command` is specified and `configuration_name` is `nil`, then the configuration to be applied is specified by the `name` attribute.|
+|`configuration_data`|Used to specify [PowerShell DSC configuration data](https://supermarket.getchef.com/cookbooks/powershell). The attribute is a `String` that conforms to the [.psd1 format](http://msdn.microsoft.com/en-us/library/dd878337(v=vs.85).aspx). It **MUST** specify a node with a name of `localhost` to be used with the `dsc_script` resource|
+|`configuration_data_script`| This attribute is a `string` that is a path to a `.psd1` file that **MUST** contain a node named `localhost` to be used with `dsc_script`.|
+|`flags`|This attribute is a `Hash` that contains keys of type `:symbol`. This can be used to pass parameters to the script specified by the `command` attributes for DSC code with a `Configuration` element that takes parameters. The value of each key in the hash is the parameter value to pass. This value defaults to `nil` and should not be set if `code` is set -- it is only valid if `command` is non-`nil`.|
+|`cwd`|This attribute sets the current working directory of the process that executes the DSC code, which is useful for scripts that rely on the **cwd**. |
+|`environment`| This attribute is similar to the `environment` attribute for `script` resources -- it takes keys of type `string` that represent the names of environment variables to set when executing the specified DSC script code. The value of each key is the desired value of each environment variable.|
+
+#### `dsc_script` examples
+
+Here is a recipe fragment with a simple usage of DSC embedded in the Chef
+`dsc_script` resource:
+
+```ruby
+dsc_script 'emacs' do
+  code <<-EOH
+  Environment 'texteditor'
+  {
+    Name = 'EDITOR'
+    Value = 'c:\\emacs\\bin\\emacs.exe'
+  }
+EOH
+end
 ```
-knife node environment set NODE ENVIRONMENT
+
+The same DSC content could be supplied by specifying a file that contains it
+within a PowerShell `Configuration` language element using the `command`
+attribute to specify a path to the DSC script file. When using `command`, you
+mest either set the `configuration_name` attribute to the value of the argument supplied to `Configuration` in the DSC script, or just set the `dsc_script` resource's `name` attribute to that value, like this:
+
+```ruby
+dsc_script `DefaultEditor` do
+  command 'c:\dsc_scripts\emacs.ps1'
+end
 ```
-### New configurable knife bootstrap options for chef-full template
-You can now modify the chef-full template with the following options in `knife bootstrap`:
 
-* `--bootstrap-install-sh URL` fetches and executes an installation bash script from the provided URL.
-* `--bootstrap-wget-options OPTIONS` and `--bootstrap-curl-options OPTIONS` allow arbitrary options to be added to wget and curl.
-* `--bootstrap-install-command COMMAND` can be used to execute a custom chef-client installation command sequence. Take note that this cannot be used in conjunction with the above options.
+which assumes that `c:\dsc_scripts\emacs.ps1` contains a configuration called **DefaultEditor** as in the PowerShell DSC script below:
 
-### Parallelize cookbook synchronization
+```powershell
+Configuration 'DefaultEditor'  
+{
+    Environment 'texteditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\emacs\bin\emacs.exe'
+    }
+}
+```
+
+##### Using the `configuration_name` attribute
 
-You can now synchronize your cookbooks faster by parallelizing the process. You can specify the number of helper threads in your config file with `cookbook_sync_threads NUM_THREADS`. The default is 10. Increasing `NUM_THREADS` can result in gateway errors from the chef server (namely 503 and 504). If you are experiencing these often, consider decreasing `NUM_THREADS` to fewer than default.
+The `configuration_name` attribute may be used to allow the `name` attribute to be set to something other than the configuration in a DSC script. In this example, `configuration_name` is used to select one of the configurations in the DSC script:
 
-### New chef config options: Whitelisting for the attributes saved by the node
+```ruby
+dsc_script `EDITOR` do
+  configuration_name 'vi'
+  command 'c:\dsc_scripts\editors.ps1'
+end
+```
 
-You can now whitelist attributes that will be saved by the node by providing a hash with the keys you want to include. Whitelist filters are described for each attribute level: `automatic_attribute_whitelist`, `default_attribute_whitelist`, `normal_attribute_whitelist`, and `override_attribute_whitelist`.
+The content of `c:\dsc_scripts\editors.ps1` in this case was:
 
-If your automatic attribute data looks like
-````
+```powershell
+Configuration 'emacs'  
 {
-  "filesystem" => {
-    "/dev/disk0s2" => {
-      "size" => "10mb"
-    },
-    "map - autohome" => {
-      "size" => "10mb"
-    }
-  },
-  "network" => {
-    "interfaces" => {
-      "eth0" => {...},
-      "eth1" => {...},
+    Environment 'TextEditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\emacs\bin\emacs.exe'
     }
-  }
 }
-````
-and your config file looks like
-````
-automatic_attribute_whitelist = ["network/interfaces/eth0"]
-````
-then the entire `filesystem` and `eth1` subtrees will not be saved by the node. To save the `/dev/disk0s2` subtree, you must write `automatic_attribute_whitelist = [ ["filesystem", "/dev/disk0s2"] ]`.
 
-If your config file looks like `automatic_attribute_whitelist = []`, then none of your automatic attribute data will be saved by the node.
+Configuration 'vi'  
+{
+    Environment 'TextEditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\vim\bin\vim.exe'
+    }
+}
+```
 
-The default behavior is for the node to save all the attribute data. This can be ensured by setting your whitelist filter to `nil`.
+##### Passing parameters to DSC configurations
 
-We recommend only using `automatic_attribute_whitelist` to reduce the size of the system data being stored for nodes, and discourage the use of the other attribute whitelists except by advanced users.
+If a DSC script specified with the `command` attribute has a configuration that takes parameters, those may be passed using the `flags` attribute:
 
-### Set proxy environment variables if present in your config file.
+```ruby
+dsc_script `DefaultEditor` do
+  flags { :EditorChoice => 'emacs', :EditorFlags => '--maximized' }
+  command 'c:\dsc_scripts\editors.ps1'
+end
+```
 
-If `:http_proxy`, `:https_proxy`, `:ftp_proxy`, or `:no_proxy` is found in your config file, we will configure your environment variables according to the variable form and configuration info given. If your config file looks like
+This could be used with the following PowerShell DSC script content for `c:\dsc_scripts\editors.ps1`
 
-````
-http_proxy "http://proxy.example.org:8080"
-http_proxy_user "myself"
-http_proxy_pass "Password1"
-````
+```powershell
+$choices = @{'emacs' = 'c:\emacs\bin\emacs';'vi' = 'c:\vim\vim.exe';'powershell' = 'powershell_ise.exe'}
+Configuration 'DefaultEditor' 
+{
+    [CmdletBinding()]
+    param
+    (
+        $EditorChoice,
+        $EditorFlags = ''
+    )
+    Environment 'TextEditor'
+    {
+        Name = 'EDITOR'
+        Value =  "$($choices[$EditorChoice]) $EditorFlags"
+    }
+}
+```
 
-then Chef will set `ENV['http_proxy'] = "http://myself:Password1@proxy.example.org:8080"`
+##### Using configuration data
+
+DSC's [configuration data](http://technet.microsoft.com/en-us/library/dn249925.aspx)
+feature allows further customization of DSC scripts. In some cases, such as
+setting behavior for Powershell credential data types, its use in a DSC
+configuration is required. The configuration data supplied **MUST** contain an
+entry for a node name of `localhost` to be applied by `dsc_script`. 
+
+Configuration data may be supplied directly through the `configuration_data` attribute
+of `dsc_script` or the `configuration_data_script` or by specifying the path
+to a **.psd1** with the same contents that could be supplied to `configuration_data`.
+
+The following example demonstrates DSC's `User` resource using DSC configuration
+data to create a user using a plaintext specification of a password:
+
+```ruby
+dsc_script 'BackupUser' do
+  configuration_data <<-EOH
+@{
+AllNodes = @(
+             @{
+             NodeName = "localhost";
+             PSDscAllowPlainTextPassword = $true
+             })
+}
+EOH
+  code <<-EOH
+$user = 'backup'
+$password = ConvertTo-SecureString -String "YourPass$(random)" -AsPlainText -Force
+$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user, $password
 
-### -E is not respected by knife ssh [search]
-knife now includes a warning in the -E/--environment option that this setting is ignored by knife searches.
+User $user
+{
+    UserName = $user
+    Password = $cred
+    Description = 'Backup operator'
+    Ensure = "Present"
+    Disabled = $false
+    PasswordNeverExpires = $true
+    PasswordChangeRequired = $false
+}
+EOH
+
+configuration_data <<-EOH
+@{
+AllNodes = @(
+             @{
+             NodeName = "localhost";
+             PSDscAllowPlainTextPassword = $true
+             })
+}
+EOH
+end
+```
 
-### New configurable option :yum-lock-timeout
-You can now set the timeout for receiving the yum lock in `config.rb` by adding `yum-lock-timeout SECONDS` (default is 30 seconds).
+##### Using `dsc_script` with other Chef resources
+Like any other resource in Chef, `dsc_script` can be used in concert with
+other Chef resources -- here's an example that downloads a file using Chef's
+`remote_file` resource and uncompresses it using DSC's `Archive` resource via
+`dsc_script` into a target directory:
+
+```ruby
+remote_file "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip" do
+  source 'http://gallery.technet.microsoft.com/DSC-Resource-Kit-All-c449312d/file/124481/1/DSC%20Resource%20Kit%20Wave%206%2008282014.zip'
+end
+  
+dsc_script 'get-dsc-resource-kit' do
+  code <<-EOH
+Archive reskit
+{
+    ensure = 'Present'
+    path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
+    destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
+}
+EOH
+end
+```
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 960dbf89e4..bffd1f0b7d 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,57 +1,4 @@
-# Chef Client Release Notes 11.14.4:
-
-## DSCL user provider now supports Mac OS X 10.7 and above.
-
-DSCL user provider in Chef has supported setting passwords only on Mac OS X 10.6. In this release, Mac OS X versions 10.7 and above are now supported. Support for Mac OS X 10.6 is dropped from the dscl provider since this version is EOLed by Apple.
-
-In order to support configuring passwords for the users using shadow hashes two new attributes `salt` & `iterations` are added to the user resource. These attributes are required to make the new [SALTED-SHA512-PBKDF2](http://en.wikipedia.org/wiki/PBKDF2) style shadow hashes used in Mac OS X versions 10.8 and above.
-
-User resource on Mac supports setting password both using plain-text password or using the shadow hash. You can simply set the `password` attribute to the plain text password to configure the password for the user. However this is not ideal since including plain text passwords in cookbooks (even if they are private) is not a good idea. In order to set passwords using shadow hash you can follow the instructions below based on your Mac OS X version.
-
-### Mac OS X 10.7
-
-10.7 calculates the password hash using **SALTED-SHA512**. Stored shadow hash length is 68 bytes; first 4 bytes being salt and the next 64 bytes being the shadow hash itself. You can use below code in order to calculate password hashes to be used in `password` attribute on Mac OS X 10.7:
-
-```
-password = "my_awesome_password"
-salt = OpenSSL::Random.random_bytes(4)
-encoded_password = OpenSSL::Digest::SHA512.hexdigest(salt + password)
-shadow_hash = salt.unpack('H*').first + encoded_password
-
-# You can use this value in your recipes as below:
-
-user "my_awesome_user" do
-  password "c9b3bd....d843"  # Length: 136
-end
-```
-### Mac OS X 10.8 and above
-
-10.7 calculates the password hash using **SALTED-SHA512-PBKDF2**. Stored shadow hash length is 128 bytes. In addition to the shadow hash value, `salt` (32 bytes) and `iterations` (integer) is stored on the system. You can use below code in order to calculate password hashes on Mac OS X 10.8 and above:
-
-```
-password = "my_awesome_password"
-salt = OpenSSL::Random.random_bytes(32)
-iterations = 25000 # Any value above 20k should be fine.
-
-shadow_hash = OpenSSL::PKCS5::pbkdf2_hmac(
-  password,
-  salt,
-  iterations,
-  128,
-  OpenSSL::Digest::SHA512.new
-).unpack('H*').first
-salt_value = salt.unpack('H*').first
-
-# You can use this value in your recipes as below:
-
-user "my_awesome_user" do
-  password "cbd1a....fc843"  # Length: 256
-  salt "bd1a....fc83"        # Length: 64
-  iterations 25000
-end
-```
-
-# 11.14.2
+# Chef Client Release Notes 11.16.0:
 
 ## Known Issues
 
@@ -78,185 +25,15 @@ Original bug: [JIRA CHEF-5276](https://tickets.opscode.com/browse/CHEF-5276)
 
 ## Bug Fixes and New Features
 
-### New JSON gem:  ffi-yajl
-
-The dependencies on yajl-ruby and json have been dropped in favor of using the ffi-yajl gem.  This is a dual-mode
-(ffi and c-extension) gem which uses the yajl 2.x c-library for JSON parsing.  It fixes several bugs related to
-truncated JSON or JSON with trailing garbage being parsed successfully (e.g. CHEF-4565 and CHEF-4899).  It also should
-remove the conflicts based on collisions over JSON gem versions.
-
-Gem installs of Chef may not require both libffi headers (libffi-dev/devel packages) and "build-essential" tools
-(c-compiler, make, etc) to install the ffi library on Unix-ish systems.  The compilers were already previously required
-for native gem installation and yajl-ruby -- the libffi header file dependency is new.  Omnibus chef installers will
-ship with the libffi that we already build and ship with omnibus chef.
-
-### CHEF-5223 OS X Service provider regression.
-
-This commit: https://github.com/opscode/chef/commit/024b1e3e4de523d3c1ebbb42883a2bef3f9f415c
-introduced a requirement that a service have a plist file for any
-action, but a service that is being created will not have a plist file
-yet. Chef now only requires that a service have a plist for the enable
-and disable actions.
-
-### Signal Regression Fix
-
-CHEF-1761 introduced a regression for signal handling when not in daemon mode
-(see CHEF-5172). Chef will now, once again, exit immediately on SIGTERM if it
-is not in daemon mode, otherwise it will complete it's current run before
-existing.
-
-### New knife command: knife serve
-You can now run a persistent chef-zero against your local repository:
-
-```
-knife serve
-```
-
-knife serve takes --chef-zero-host=HOST, --chef-zero-port=PORT and --chef-repo-path=PATH variables. By default, it will do exactly the same thing as the local mode argument to knife and chef-client (-z), locating your chef-repo-path automatically and binding to port 8900.  It will print the URL it is bound to so that you can add it to your knife.rb files.
-
-### --run-lock-timeout for chef-client and chef-solo
-You can now add a timeout for the maximum time a client run waits on another client run to finish.
-The default is to wait indefinitely.
-Setting the run lock timeout to 0 causes the second client run to exit immediately.
-
-This can be configured in your config file:
-```
-run_lock_timeout SECONDS
-```
-
-Or via the command line:
-```
-chef-client --run-lock-timeout SECONDS
-```
-
-### New knife command: knife node environment set
-You can now easily set the environment for an existing node without editing the node object:
-
-```
-knife node environment set NODE ENVIRONMENT
-```
-### New configurable knife bootstrap options for chef-full template
-You can now modify the chef-full template with the following options in `knife bootstrap`:
-
-* `--bootstrap-install-sh URL` fetches and executes an installation bash script from the provided URL.
-* `--bootstrap-wget-options OPTIONS` and `--bootstrap-curl-options OPTIONS` allow arbitrary options to be added to wget and curl.
-* `--bootstrap-install-command COMMAND` can be used to execute a custom chef-client installation command sequence. Take note that this cannot be used in conjunction with the above options.
-
-### Parallelize cookbook synchronization
-
-You can now synchronize your cookbooks faster by parallelizing the process. You can specify the number of helper threads in your config file with `cookbook_sync_threads NUM_THREADS`. The default is 10. Increasing `NUM_THREADS` can result in gateway errors from the chef server (namely 503 and 504). If you are experiencing these often, consider decreasing `NUM_THREADS` to fewer than default.
-
-### New chef config options: Whitelisting for the attributes saved by the node
-
-You can now whitelist attributes that will be saved by the node by providing a hash with the keys you want to include. Whitelist filters are described for each attribute level: `automatic_attribute_whitelist`, `default_attribute_whitelist`, `normal_attribute_whitelist`, and `override_attribute_whitelist`.
-
-If your automatic attribute data looks like
-````
-{
-  "filesystem" => {
-    "/dev/disk0s2" => {
-      "size" => "10mb"
-    },
-    "map - autohome" => {
-      "size" => "10mb"
-    }
-  },
-  "network" => {
-    "interfaces" => {
-      "eth0" => {...},
-      "eth1" => {...},
-    }
-  }
-}
-````
-and your config file looks like
-````
-automatic_attribute_whitelist = ["network/interfaces/eth0"]
-````
-then the entire `filesystem` and `eth1` subtrees will not be saved by the node. To save the `/dev/disk0s2` subtree, you must write `automatic_attribute_whitelist = [ ["filesystem", "/dev/disk0s2"] ]`.
-
-If your config file looks like `automatic_attribute_whitelist = []`, then none of your automatic attribute data will be saved by the node.
-
-The default behavior is for the node to save all the attribute data. This can be ensured by setting your whitelist filter to `nil`.
-
-We recommend only using `automatic_attribute_whitelist` to reduce the size of the system data being stored for nodes, and discourage the use of the other attribute whitelists except by advanced users.
-
-### Set proxy environment variables if present in your config file.
-
-If `:http_proxy`, `:https_proxy`, `:ftp_proxy`, or `:no_proxy` is found in your config file, we will configure your environment variables according to the variable form and configuration info given. If your config file looks like
-
-````
-http_proxy "http://proxy.example.org:8080"
-http_proxy_user "myself"
-http_proxy_pass "Password1"
-````
-
-then Chef will set `ENV['http_proxy'] = "http://myself:Password1@proxy.example.org:8080"`
-
-### -E is not respected by knife ssh [search]
-knife now includes a warning in the -E/--environment option that this setting is ignored by knife searches.
-
-### New configurable option :yum-lock-timeout
-You can now set the timeout for receiving the yum lock in `config.rb` by adding `yum-lock-timeout SECONDS` (default is 30 seconds).
-
-### New `timeout` attribute for `package` resource
-`package` resource now exposes a new attribute called `timeout` which is used during the execution of specified actions. This attribute currently is only supported by `Chef::Provider::Package::Apt` provider on `ubuntu`, `gcel`, `linaro`, `raspbian`, `linuxmint` and `debian` operating systems.
-
-### Ohai 7.2.0
-In this release of Chef included ohai version is bumped to 7.2.0 which contains [these](https://github.com/opscode/ohai/blob/7-stable/CHANGELOG.md) changes.
-
-### Declare `lazy` values in LWRPs
-In prior releases of Chef, it was impossible to declare "composite" attribute values due to scoping context:
-
-```ruby
-attribute :username, kind_of: String
-
-# This will fail because `username` is not defined at this scope
-attribute :home, default: "/home/#{username}"
-```
-
-In this release of Chef, you can use the `lazy` key to define an attribute that will yield the `new_resource` instance when called:
-
-```ruby
-attribute :username, kind_of: String
-attribute :home, default: lazy { |new_resource| "/home/#{new_resource.username}" }
-```
-
-You can also pass a more complex, multi-line block to your `lazy`:
-
-```ruby
-attribute :home, default: lazy do |new_resource|
-  case platform_family
-  when 'windows'
-    "C:/Users/#{new_resource.username}"
-  when 'osx'
-    "/Users/#{new_resource.username}"
-  else
-    "/home/#{new_resource.username}"
-  end
-end
-```
-
-These changes do not impact any cookbook code, but may impact tools that
-use the code base as a library. Authors of tools that rely on Chef
-internals should review these changes carefully and update their
-applications.
-
-## Changes to CookbookUpload
-
-`Chef::CookbookUpload.new` previously took a path as the second
-argument, but due to internal changes, this parameter was not used, and
-it has been removed. See: https://github.com/opscode/chef/commit/12c9bed3a5a7ab86ff78cb660d96f8b77ad6395d
-
-## Changes to FileVendor
-
-`Chef::Cookbook::FileVendor` was previously configured by passing a
-block to the `on_create` method; it is now configured by calling either
-`fetch_from_remote` or `fetch_from_disk`. See: https://github.com/opscode/chef/commit/3b2b4de8e7f0d55524f2a0ccaf3e1aa9f2d371eb
+### New dsc\_script resource for PowerShell DSC on Windows
+The `dsc_script` resource is new in Chef with this release. `dsc_script`
+allows the invocation of
+[PowerShell Desired State Configuration]((http://technet.microsoft.com/en-us/library/dn249912.aspx) (DSC) scripts
+from Chef recipes. The `dsc_script` resource is only available for systems
+running the Windows operating systtem with **PowerShell version 4.0 or later** installed. Windows systems may be
+updated to PowerShell version 4.0 or later using the [PowerShell cookbook](https://supermarket.getchef.com/cookbooks/powershell)
+available at [Chef Supermarket](http://supermarket.getchef.com). 
 
-## 'group' provider on OSX properly uses 'dscl' to determine existing groups
+The **WinRM** service required by PowerShell DSC must be enabled on the system as well in order to use
+the `dsc_script` resource -- this can be accomplished using the Windows OS `winrm quickconfig` command.
 
-On OSX, the 'group' provider would use 'etc' to determine existing groups,
-but 'dscl' to add groups, causing broken idempotency if something existed
-in /etc/group. The provider now uses 'dscl' for both idempotenty checks and
-modifications.