diff options
author | Tim Smith <tsmith@chef.io> | 2019-04-11 23:25:15 -0700 |
---|---|---|
committer | Tim Smith <tsmith@chef.io> | 2019-04-23 16:53:22 -0700 |
commit | 0d108f49e5837fbbaec4570e816fdba00b828b66 (patch) | |
tree | 604eac9f4ce2755d1d256d98f9da3cfe1ab58461 /docs | |
parent | 380f521cd91010b04b7038ed03264dfe2d337ed6 (diff) | |
download | chef-0d108f49e5837fbbaec4570e816fdba00b828b66.tar.gz |
Remove a few RFC references
Signed-off-by: Tim Smith <tsmith@chef.io>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/dev/design_documents/client_release_cadence.md | 6 | ||||
-rwxr-xr-x | docs/dev/design_documents/resource_guard_interpreters.md | 39 |
2 files changed, 22 insertions, 23 deletions
diff --git a/docs/dev/design_documents/client_release_cadence.md b/docs/dev/design_documents/client_release_cadence.md index 2954d5d21d..2f77980ae7 100644 --- a/docs/dev/design_documents/client_release_cadence.md +++ b/docs/dev/design_documents/client_release_cadence.md @@ -3,8 +3,8 @@ 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). +backwards-compatible to the best of our ability. Patch releases will contain bug +and security fixes only 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 @@ -30,4 +30,4 @@ 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 +vacations, ChefConf, and Chef Summits. diff --git a/docs/dev/design_documents/resource_guard_interpreters.md b/docs/dev/design_documents/resource_guard_interpreters.md index 4367cc8a34..d7cf9f244a 100755 --- a/docs/dev/design_documents/resource_guard_interpreters.md +++ b/docs/dev/design_documents/resource_guard_interpreters.md @@ -73,10 +73,10 @@ These definitions are used throughout the discussion: context and is expressed within a block guard's block. The guard interpreter resource is simply used to assess a true or false value (e.g. whether a script that tests system state in a relevant way returns a success or - failure process status) inside of a block guard. + failure process status) inside of a block guard. ## Overview -Guard expressions for all resources have been extended to include an attribute +Guard expressions for all resources have been extended to include an attribute named `guard_interpreter` that takes the short name symbol of a Chef resource to be used to evaluate script guards. This is useful for testing conditions to ensure idempotence for non-idempotent resources such as script resources. The goals in doing this are: @@ -130,7 +130,7 @@ Concepts such as inheritance are introduced in the examples which are explained # the bash interpreter; if we had passed the same string # directly to the only_if, this would have failed the # Chef run since that string is not valid for /bin/sh -bash "Use bash for only_if" do +bash "Use bash for only_if" do guard_interpreter :bash code "echo I am $SHELL" only_if '[[ 1 == 1 ]]' # won't work outside of bash @@ -190,7 +190,7 @@ end # What if guards evaluated powershell script code that powershell # evaluates as a boolean type as the actual boolean value of the guard # itself? You can avoid extra script code to translate the boolean into -# a process exit code that results in the right true / false behavior +# a process exit code that results in the right true / false behavior # for the guard. Guards already work this way on Linux systems... powershell_script "set execution policy" do guard_interpreter :powershell_script @@ -199,7 +199,7 @@ powershell_script "set execution policy" do end ``` -#### `powershell_script` architecture inheritance +#### `powershell_script` architecture inheritance ```ruby do @@ -235,7 +235,7 @@ action or to skip it: or `false`. 3. If the aforementioned string or block expression was supplied to an `only_if` attribute, the action of the resource containing the attribute will be skipped if the expression evaluated to `false` and executed if it evaluated to `true`. 4. If the expression was supplied to a `not_if` attribute, the behavior of the resource is the inverse of that for `only_if`; the resource action is executed if the expression evaluated to `false` and skipped if it evaluated to `true`. - + This specification of guard behavior is accurate without the inclusion of `guard_interpreter` features described in this document. The `guard_interpreter` attribute allows for the interpreter to be something other @@ -250,7 +250,7 @@ was introduced, which provides the following behavior: 2. If the resource action updates the resource, the value is `true`. Resources can only be updated if the interpreter used by the resource specified in the `guard_interpreter` attribute returns a success code, `0` by default, though this can be overridden in attributes specified to the resource as guard arguments. Anything other than a success code results in the guard evaluating as `false`. ### script resource conditional semantics -To enable the usage as guard resources of resources derived from `Chef::Resource::Script`, known colloquially as script resources, all such resources when executed as guard resources will handle the exception `Mixlib::Shellout::ShellCommandFailed`. +To enable the usage as guard resources of resources derived from `Chef::Resource::Script`, known colloquially as script resources, all such resources when executed as guard resources will handle the exception `Mixlib::Shellout::ShellCommandFailed`. By doing this, usage of script resources has the same conditional and exception behavior as the case described earlier when a string is passed to a `not_if` or `only_if` guard attribute since this exception is raised precisely in the case where a string passed as a guard would have been evaluated by /bin/sh or cmd.exe as exiting with a failure status code. @@ -282,7 +282,7 @@ end ``` ### Guard attribute inheritance -A new change is that a resource used within the context of a guard may inherit some attributes from the resource that contains the guard. +A new change is that a resource used within the context of a guard may inherit some attributes from the resource that contains the guard. Inheritance follows these rules: @@ -332,7 +332,7 @@ end * For the `powershell_script` resource, an additional attribute is inherited when this resource is used as a guard resource: - + `:architecture` * When a guard attribute of `powershell_script` is given a string rather than a @@ -411,13 +411,13 @@ modification: executed as the definition of a PowerShell function with a return type of `bool`, a PowerShell type analogous to a typical Boolean data type **AND** if the `convert_boolean_return` attribute of the resource executing the - script is set to `true`. + script is set to `true`. * In this case, if the function return value is the PowerShell value `$true`, the exit code is 0 (overloaded with 'success'), otherwise the function return value is `$false` and the exit code is 1. * In cases where the hypothetical PowerShell function raises an exception or returns a type other than PowerShell's `bool` type, preexisting exit code rules hold. - + This behavior for `powershell_script` when `convert_boolean_return` is set to `true` is functionally equivalent to the behavior of the bash shell when it evaluates quasi-boolean commands such as the `test` command and @@ -440,7 +440,7 @@ how to use legacy `cmd.exe` to accomplish tasks. Most likely, users of `powershe would choose to run powershell.exe in the `not_if` and `only_if` blocks. Since that was the common case for `powersell_script` users, the guards should have had some way to allow that, or to -provide guard execution via PowerShell in a more natural fashion. +provide guard execution via PowerShell in a more natural fashion. Even for Unix users, however, there was still room to be delightful since `/bin/sh`, while not the antediluvian relic that is `cmd.exe` on Windows, is @@ -455,12 +455,11 @@ well use the generic script or execute resources if knowledge of the best way to a given interpreter cannot be contained in the resource. So the addition of the `guard_interpreter` attribute as adopted via this -RFC lets users choose to adopt a -more natural way of expressing idempotence that lets you embed shell-specific -expressions in the clean Chef DSL without all of the awkwardness and corner -cases described earlier. The result is an uncluttered description of -infrastructure that doesn't sacrifice on the shell or underlying platform's -native descriptive and functional capabilities. +design document lets users choose to adopt a more natural way of expressing +idempotence that lets you embed shell-specific expressions in the clean Chef +DSL without all of the awkwardness and corner cases described earlier. The +result is an uncluttered description of infrastructure that doesn't sacrifice +on the shell or underlying platform's native descriptive and functional capabilities. ### Boolean result code interpolation details Consider the Chef DSL fragment below where a string passed to an `only_if` guard performs a @@ -517,7 +516,7 @@ This enables cases where a test that can be expressed very cleanly with the PowerShell language can be used directly within a guard expression with no need to try to generate a process exit code that Chef will interpret as a true or false value. For example, the true or false value of a PowerShell -expression like +expression like ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()). IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator") @@ -531,4 +530,4 @@ without specifying any additional PowerShell code. This interpolation of Boolean return values also happens when a string of code is passed to a guard in a `powershell_script` resource, a scenario that builds on top of the previously described switch to the PowerShell language as the script interpreter of -strings passed to guards in the `powershell_script` resource.
\ No newline at end of file +strings passed to guards in the `powershell_script` resource. |