Add more design docs from the RFCs

Signed-off-by: Tim Smith <tsmith@chef.io>

9 files changed, 429 insertions, 3 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 9078cbe8a6..0ffbd51e51 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -11,9 +11,15 @@ This directory contains a collection of useful how-to guides for both new and se
 
 ## Design Documents
 
+- [Client Release Cadence](./design_documents/client_release_cadence.mdÂ)
 - [Data Collection](./design_documents/data_collector.md)
 - [Action Collection](./design_documents/action_collection.md)
-- [Deprecations Within Resources](./design_documents/deprecations-in-resources.md)
+- [Deprecations Within Resources](./design_documents/deprecations_in_resources.md)
 - [Resource Guard Interpreters](./design_documents/resource_guard_interpreters.md)
-- [Resource Property Validation Messaging](./design_documents/resource-property-validation-messaging.md)
-- [Self Documenting Resources](./design_documents/self-documenting-resources.md)
\ No newline at end of file
+- [Resource Property Validation Messaging](./design_documents/resource_property_validation_messaging.md)
+- [Self Documenting Resources](./design_documents/self_documenting_resources.md)
+- [Resource Before Notifications](./design_documents/resource_before_notifications.md)
+- [Resource File Content Verification](resource_file_content_verification.md)
+- [Ohai Cookbook Segment](./design_documents/ohai_cookbook_segment.md)
+- [Client Exit Codes](./design_documents/client_exit_codes.md)
+- [Server Enforced Recipes](./design_documents/server_enforced_recipes.md)
diff --git a/docs/dev/design_documents/client_exit_codes.md b/docs/dev/design_documents/client_exit_codes.md
new file mode 100644
index 0000000000..1fdbea2952
--- /dev/null
+++ b/docs/dev/design_documents/client_exit_codes.md
@@ -0,0 +1,63 @@
+# Chef-Client Exit Codes
+
+Signal outside tools of specific Chef-Client run status. Ability to determine results of a Chef-Client run.
+
+## Motivation
+
+    As a Chef user,
+    I want to be able to determine when a chef-client run is rebooting the node,
+    so that Test-Kitchen/Vagrant/any outside tool can wait for node to reboot, and continue converging.
+
+## Specification
+
+* Chef applications (e.g. chef-client) that interpret recipes should use the specified exit codes
+* Chef tools (e.g. knife) should behave appropriately for the exit code, or pass it to the user
+
+### Exit codes Reserved by Operating System
+
+* Windows- [Link](https://msdn.microsoft.com/en-us/library/windows/desktop/ms681381(v=vs.85).aspx)
+* Linux - [Sysexits](http://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD+4.3-RELEASE&format=html), [Bash Scripting](http://tldp.org/LDP/abs/html/exitcodes.html)
+
+### Remaining Available Exit Codes
+
+All exit codes defined should be usable on all supported Chef Platforms.  Also the exit codes used should be identical across platforms.  That limits the total range from 1-255.  Exit codes not explicitly used by Linux/Windows are listed below.  There are 59 exit codes that are available on both platforms.
+ * Any numbers below that have a strike-through are used below in the **Exit Codes in Use** section
+ * Exit Codes Available for Chef use :
+     * ~~35,37,40,41,42~~,43,44,45,46,47,48,49,79,81,90,91,92,93,94,95,96,97
+     * 98,99,115,116,168,169,172,175,176,177,178,179,181,184,185,204,211
+     * ~~213~~,219,227,228,235,236,237,238,239,241,242,243,244,245
+
+### Precedence
+
+* Reboot exit codes should take precedence over Chef Execution State
+* Precedence within a table should be evaluated from the top down.
+    *  Example - Audit Mode Failure would only apply on a successful execution.  But if the chef-run failed for any other reason, no reason to exit with audit mode.
+
+## Exit Codes in Use
+
+#### Reboot Requirement
+
+Exit Code        | Reason            | Details
+-------------    | -------------     |-----
+35               | Reboot Scheduled  | Reboot has been scheduled in the run state
+37               | Reboot Needed     | Reboot needs to be completed
+41               | Reboot Failed     | Initiated Reboot failed - due to permissions or any other reason
+
+
+#### Chef Run State
+
+Exit Code        | Reason             | Details
+-------------    | -------------      |-----
+-1               | Failed execution*   | Generic error during Chef execution.  On Linux this will show up as 255, on Windows as -1
+0                | Successful run     | Any successful execution of a Chef utility should return this exit code
+1                | Failed execution   | Generic error during Chef execution.
+2                | SIGINT received    | Received an interrupt signal
+3                | SIGTERM received   | Received an terminate signal
+42               | Audit Mode Failure | Audit mode failed, but chef converged successfully.
+213              | Chef upgrade       | Chef has exited during a client upgrade
+
+* \*Next release should deprecate any use of this exit code.
+
+## Extend
+
+If there is a need for additional exit codes pleae open a Design Proposal PR to discuss the change and then a PR to update this document.
\ No newline at end of file
diff --git a/docs/dev/design_documents/client_release_cadence.md b/docs/dev/design_documents/client_release_cadence.md
new file mode 100644
index 0000000000..40892ddf33
--- /dev/null
+++ b/docs/dev/design_documents/client_release_cadence.md
@@ -0,0 +1,33 @@
+# Chef Release Cadence
+
+Chef follows [Semantic Versioning](https://semver.org/) for releases. Major
+versions (eg. 11.x -> 12.x) will include backwards-incompatible changes, minor
+versions (eg 12.1 -> 12.2) will include new features and bug fixes but will be
+backwards-compatible to the best of our ability. Patch versions are governed
+by [RFC 47](rfc047-release-process.md).
+
+Chef feature releases are promoted to the stable channel once per month. It is
+expected that this occur during the second week of the month unless
+circumstances intervene. Additional patch releases for a given feature release
+may be promoted if critical issues are found.
+
+ChefDK is released once per month. It is expected that this occur during the
+fourth week of the month unless circumstances intervene.
+
+Both Chef and ChefDK will prepare a release candidate before the target release
+date, usually in the week before but at least three business days before release.
+
+The Chef release in April of each year is a major version release, which will
+contain backwards-incompatible changes. A reminder notice will be sent via
+Discourse and Slack in March that will summarize the changes slated for the release.
+
+## Rationale
+
+Monthly releases help ensure we get new features and minor bug fixes out to Chef
+users in a timely fashion while not overloading the maintainer teams.
+Similarly, offsetting the Chef and ChefDK releases allows the full attention of
+the Chef development team on each of those releases and leaves time for any
+potential hot fixes or follow-up.
+
+Major releases in April avoids releasing during winter holidays, summer
+vacations, ChefConf and Chef Summits.
\ No newline at end of file
diff --git a/docs/dev/design_documents/deprecations-in-resources.md b/docs/dev/design_documents/deprecations_in_resources.md
index 0ae145712f..0ae145712f 100644
--- a/docs/dev/design_documents/deprecations-in-resources.md
+++ b/docs/dev/design_documents/deprecations_in_resources.md
diff --git a/docs/dev/design_documents/ohai_cookbook_segment.md b/docs/dev/design_documents/ohai_cookbook_segment.md
new file mode 100644
index 0000000000..09c2dcbf69
--- /dev/null
+++ b/docs/dev/design_documents/ohai_cookbook_segment.md
@@ -0,0 +1,36 @@
+# Add Ohai cookbook segment
+
+Support Ohai plugins under an `ohai` top level directory in cookbooks.  Load all
+Ohai plugins in all synchronized cookbooks after cookbook synchronization.
+
+## Motivation
+
+    As a Chef User,
+    I want to have my custom Ohai plugins loaded on first bootstrap,
+    So I don't have to run chef twice.
+
+    As a Chef User,
+    I want my Ohai plugins loaded before attributes and compile/converge mode,
+    So I can use them without worrying about cookbook execution ordering.
+
+    As a Chef User,
+    I want my Ohai plugins synchronized with my cookbooks,
+    So that I don't incure more unavoidable round-trips to the Chef Server.
+
+    As a Chef Developer,
+    I want Ohai plugins as a first-class object,
+    So that I don't have to compile recipes to discover templates that drop plugins.
+
+## Specification
+
+The "segments" of a cookbook will be extended to include an "ohai" segment.  In this segment there will be plugins which are intended to be copied to the Ohai `plugin_path`.  All files in this segment will be copied, recursively, maintaining directory structure.
+
+In the `Chef::RunContext::CookbookCompiler#compile` method a phase will be added after `compile_libraries` and before `compile_attributes` which will copy the Ohai plugins from the cookbook segment and will load all of the discovered plugins.
+
+The plugins will be copied from `<cookbookname>/ohai` into `/etc/chef/ohai/cookbook-plugins/<cookbookname>` as their top level directory (recursively).  The state of the entire
+subdirectory tree under `/etc/chef/ohai/cookbook-plugins` will be managed fully by chef-client so that any files which are not synchronized by chef-client will be removed, so
+that removal of a plugin from a cookbook or removal of the cookbook from `run_list` will result in the plugin being removed on the target host.
+
+The plugins directory will work similarly to libraries and other directions in that there will be no control over the inclusion of plugins below the level of the inclusion of the cookbook itself in the `run_list`.
+
+When plugins override other plugins on loading, and in particular when cookbook plugins override core plugins, they should WARN the user.  This will address the case where a user has included a custom plugin and Ohai is later extended with similar functionality in the same namespace.  The custom plugin should take precedence for backwards compatibility.  There should be a way to silence the warning with a DSL method added to the custom plugin.
\ No newline at end of file
diff --git a/docs/dev/design_documents/resource_before_notifications.md b/docs/dev/design_documents/resource_before_notifications.md
new file mode 100644
index 0000000000..35828036b6
--- /dev/null
+++ b/docs/dev/design_documents/resource_before_notifications.md
@@ -0,0 +1,77 @@
+# Before Notifications
+
+Let users trigger another resource prior to an action happening.
+
+## Motivation
+
+    As a Chef user,
+    I want to make one resource action a precondition for another,
+    So that when two resources depend on each other, I can make an update succeed.
+
+    As a Chef user,
+    I want this action only to happen if the other resource *does* update,
+    So that I don't unnecessarily run my preconditions on every single Chef run.
+
+    As a Chef user,
+    I want Chef to run me an action if a resource updates,
+    So that I don't have to implement the resource test logic in my recipe.
+
+## Specification
+
+We add a new :before timing which causes a notification to happen
+*before* the resource actually updates. If the resource will not actually update,
+this event does not fire.
+
+The events you can specify would become:
+
+- :before - before the resource updates, but *only* if an update will occur.
+- :immediately - after the resource updates, but *only* if an update occurred.
+- :delayed - after the resource updates, at the end of the run.
+
+```ruby
+package "foo" do
+  action :upgrade
+  # The package upgrade will fail if we try to upgrade while it runs!!!
+  notifies :stop, "service[blah]", :before
+end
+
+service "blah" do
+end
+```
+
+This will work for both subscribes and notifies.
+
+### Backwards Compatibility
+
+This will only affect resources which have :before on them, and will
+not modify any existing resources or recipes.
+
+### Implementation
+
+There is a tricky implementation detail here, because both the test ("is my
+package version lower than the latest?") and the set ("call rpm and update the
+package") part of a resource are both part of the action. Chef only runs one
+action to run at a time, and it seems ill-advised to change that without a lot
+of extra thinking.
+
+To get around this without breaking the model, we propose that resources with an
+`:before` action run a why-run test of the action and trigger off of
+that, before running the action for real. The flow of this resource:
+
+```ruby
+package "foo" do
+  action :upgrade
+  notifies :stop, "service[blah]", :before
+end
+```
+
+The execution of the package upgrade looks like this:
+
+1. If :before events are on the resource:
+   a. raise an error if the resource does not support why-run.
+   b. Turn on why-run temporarily.
+   c. Run the action.
+   d. Send the notification if updated_by_last_action? is true.
+   e. Turn off why-run.
+2. Run the action (for real!).
+3. Send :immediate or :delayed notifications if updated_by_last_action? is true.
diff --git a/docs/dev/design_documents/resource_file_content_verification.md b/docs/dev/design_documents/resource_file_content_verification.md
new file mode 100644
index 0000000000..a67c8a5786
--- /dev/null
+++ b/docs/dev/design_documents/resource_file_content_verification.md
@@ -0,0 +1,110 @@
+# File Content Verification
+
+File-based resources should be able to verify a file's content via
+user-supplied instructions before deploying the new content.
+
+## Specification
+
+The `verify` attribute of the `file`, `template`, `cookbook_file`, and
+`remote_file` resources will take a user-provided block or string. At
+converge time, a block will be passed the path to a temporary file
+holding the proposed content for the file. If the block returns `true`
+the provider will continue to update the file on disk as
+appropriate. If the block returns false, the provider will raise an
+error.
+
+If a string argument to verify is passed, it will then be executed as
+a system command. If the command's return code indicates success (0 on
+unix-like system) the provider will continue to update the file on
+disk as appropriate.  If the command's return code indicates failure,
+the provider will raise an error.
+
+The path to the temporary file with the proposed content will be
+available by using Ruby's sprinf formatting:
+
+   "%{path}"
+
+other variables may be made available to commands in the future.
+
+If no verification block or string is supplied by the user, the
+provider assumes the content is valid.
+
+Multiple verify blocks may be provided by the user.  All given verify
+block must pass before the content is deployed.
+
+As an example:
+
+```ruby
+# This should succeed
+template "/tmp/foo" do
+  verify do |path|
+    true
+  end
+end
+
+# This should succeed on most systems
+template "/tmp/wombat" do
+  verify "/usr/bin/true"
+end
+
+# This should raise an error
+template "/tmp/bar" do
+  verify do |path|
+    false
+  end
+end
+
+# This should raise an error on most systems
+template "/tmp/turtle" do
+  verify "/usr/bin/false"
+end
+
+# This should pass
+template "/tmp/baz" do
+  verify { true }
+  verify { 1 == 1 }
+end
+
+# This should raise an error
+template "/tmp/bat" do
+   verify { true }
+   verify { 1 == 0 }
+end
+```
+
+Users could use this feature to shell out to tools which check the
+configuration:
+
+```ruby
+template "/etc/nginx.conf" do
+  verify "nginx -t -c %{path}"
+end
+```
+
+Chef may ship built-in verifiers for common checks such as
+content-type verification. Built-in verifiers can be used by passing
+well-known symbols to the verify attribute:
+
+```ruby
+template "/etc/config.json" do
+  verify :json
+end
+```
+
+## Motivation
+
+Typos and bugs in a template can lead Chef to render invalid
+configuration files on a node. In some cases, this will cause the
+related service to fail a notified restart, bringing down the user's
+application. One hopes to catch such errors in testing, but that is
+not always possible.
+
+Many applications provide a means to verify a configuration file, but
+it is currently difficult to use these tools to verify a template
+without an elaborate series of resources chained together with
+notifications.
+
+## Related BUGS
+
+https://tickets.opscode.com/browse/CHEF-4416
+https://tickets.opscode.com/browse/CHEF-3634
diff --git a/docs/dev/design_documents/self-documenting-resources.md b/docs/dev/design_documents/self_documenting_resources.md
index d1aa2282f6..d1aa2282f6 100644
--- a/docs/dev/design_documents/self-documenting-resources.md
+++ b/docs/dev/design_documents/self_documenting_resources.md
diff --git a/docs/dev/design_documents/server_enforced_recipes.md b/docs/dev/design_documents/server_enforced_recipes.md
new file mode 100644
index 0000000000..be81f4a9b5
--- /dev/null
+++ b/docs/dev/design_documents/server_enforced_recipes.md
@@ -0,0 +1,101 @@
+# Server Enforced Recipe
+
+## Description
+
+Chef Server will provide an endpoint that MAY serve a Chef recipe file. Chef
+Client will attempt to fetch the recipe during run context setup. If
+no user action is taken to configure the feature, the endpoint returns 404
+and Client behavior will be unaffected. When the feature is enabled, the
+endpoint returns the configured recipe file. Chef Client will evaluate and
+converge the recipe.
+
+## Rationale
+
+The motivation for this feature is to allow the operator of the Chef Server to
+enforce limited desired client-side configuration using Chef. Intended use
+cases include:
+
+* Allow cloud-based vendors to install an agent necessary for correct operation
+  of the service
+* Allow Chef Customer Development Partners to efficiently install experimental
+  client-side software during feature development
+* Allow organizations that operate as internal service providers to enforce
+  standard configurations
+
+This feature is targeted at expert level practitioners who are delivering
+isolated configuration changes to the target systems, such as self-contained
+agent software. Users who wish to deliver more comprehensive configuration
+changes should not use this mechanism to deliver those changes directly, but
+could configure an additional Chef Client identity (i.e., node name, client
+key, organization/server url) to deliver those changes via this feature.
+
+As this feature is intended to be used in a manner that is as unobtrusive as
+possible, and in cases where the Chef Server is administrated by a vendor on
+behalf of the user, existing approaches to enforcing client-side configuration
+are not sufficient.
+
+The enforced policy is limited to a single recipe instead of a full cookbook or
+secondary run list for several reasons:
+
+* Cookbooks are Chef Server objects that are organization-scoped and subject to
+  authorization restrictions. Allowing some cookbooks to be global requires
+  additional complexity which is not needed for the intended uses.
+* Cookbooks have versions and dependencies, which have to be solved. There are
+  several ways this could be addressed, but all options introduce unneeded
+  complexity into the solution.
+* Attributes are not usable for the intended use case, since the author(s) of
+  the enforced recipe code may have no control over the node data, roles, JSON
+  files, or policyfiles used by the nodes being managed.
+* Other cookbook features, such as libraries and the various flavors of
+  resources and providers set ruby constants which could interfere with the
+  correct operation of the end user's cookbooks.
+* Templates and cookbook files would be useful, but expert practitioners will
+  be able to be effective without them.
+
+## Motivation
+
+    As a Chef Server Service Provider,
+    I want to enforce a recipe to run on client systems,
+    so that I can ensure client systems are correctly configured.
+
+## Specification
+
+### Enforced Recipe Endpoint
+
+Chef Server shall expose an organization-scoped endpoint for the enforced
+recipe. If the feature has not been configured by the Chef Server
+administrator, the endpoint shall return a 404 response. If the feature is
+enabled by the Chef Server administrator, the endpoint shall return a 200
+response with the recipe content as the response body.
+
+The endpoint shall authenticate the request via Chef Server's usual
+authentication mechanism.
+
+No authorization mechanism is provided. Any user or client with API access to
+any organization on the Chef Server will have read-only access to the enforced
+recipe.
+
+The URL path of the endpoint relative to the organization base path will be
+determined at a future time.
+
+### Chef Server Configuration
+
+The interface for configuring the feature is to be determined.
+
+Though the initial implementation will likely only support a standalone Chef
+Server deployment, the configuration interface will be written such that it can
+be extended to support tiered and HA configurations.
+
+### Chef Run
+
+During the setup phase of the Chef Client run, Chef Client shall make a HTTP
+GET request to the enforced recipe endpoint. If the Chef Server returns a 404
+response, Chef Client will continue the Chef Client run normally. If the Chef
+Server returns a 200 response, Chef Client will store the recipe file in its
+cache directory. Chef Client will then evaluate and converge the recipe using a
+mechanism to be decided.
+
+One possible implementation is to add the recipe to the list of
+`specific_recipes` which is currently populated only via CLI arguments to
+`chef-client --local-mode`. In this case, enforced recipes would be evaluated
+and converged after the primary run list.
\ No newline at end of file