Merge pull request #3554 from nickanderson/body-file-control-evaluation-order/master

Added documentation for evaluation_order in file control body

Author: nickanderson

content/examples/tutorials/policy-writing/policy-style.markdown

@@ -87,8 +87,8 @@ significantly easier for a novice to understand the desired state.
 Historically, it was important to remember that Normal ordering still applied and
 that the promises would not be actuated in the order they are written. However,
 as of CFEngine 3.27.0, you can use `evaluation_order => "top_down";` in
-`body common control` or `body agent control` to make the execution order match
-the written order.
+`body common control`, `body agent control`, or `body file control` to make the
+execution order match the written order.
 
 ```cf3
 body common control

content/reference/components/_index.markdown

@@ -245,7 +245,7 @@ body common control
 }
 ```
 
-**See also:** [`evaluation_order` in `body common control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering]
+**See also:** [`evaluation_order` in `body agent control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering]
 
 **History:**
 

content/reference/components/file_control_promises.markdown

@@ -26,6 +26,66 @@ outside of body and bundle definitions.
 Only [soft classes][Classes and decisions] from common bundles can
 be used in class decisions inside `file control bodies`.
 
+### evaluation_order
+
+**Description:** `evaluation_order` in body file control sets the evaluation order for the subsequent bundles in the file.
+
+This setting allows you to change the order in which components execute policy within a given policy file.
+By default, CFEngine uses a `classic` evaluation order, where promises are executed in a predefined order based on their type (e.g., `vars` before `files`, `files` before `packages`, etc.).
+This is the historical behavior of CFEngine.
+
+By setting `evaluation_order` to `top_down`, you can force components to evaluate promises in the order they are written in the policy file, from top to bottom.
+This can make policy evaluation more familiar and possibly easier to write and understand, especially for new users, as the execution flow follows the visual layout of the code.
+
+This attribute can also be set in `body common control` to affect all components and or `body agent control` to affect all files.
+If set in multiple places, the value in `body agent control` takes precedence for `cf-agent`.
+
+**Type:** `string`
+
+**Allowed input range:** `(classic|top_down)`
+
+**Default value:** `classic`
+
+**Example:**
+
+```cf3
+body file control
+{
+  evaluation_order => "top_down";
+}
+
+bundle agent reports_top_down
+{
+  reports: "Hello world:";
+
+  commands: "/bin/echo hi";
+
+  reports: "bye:";
+}
+bundle agent __main__
+{
+      methods: "reports_top_down";
+}
+
+body agent control
+{
+  evaluation_order => "top_down";
+}
+```
+
+Executed would result in:
+
+```output
+R: Hello world:
+  notice: Q: ".../bin/echo hi": hi
+R: bye:
+```
+
+**See also:** [`evaluation_order` in `body agent control`](/reference/components/cf-agent/#evaluation_order),
+[`evaluation_order` in `body common control`][Components#evaluation_order]
+
+**History:** Introduced in CFEngine 3.27.0
+
 ### inputs
 
 **Description:** The `inputs` slist contains additional filenames to parse for promises.

content/reference/language-concepts/policy-evaluation.markdown

@@ -33,6 +33,11 @@ as early as possible in your configuration. In order to make sure all global
 variables and classes are available early enough policy pre-evaluation step was
 introduced.
 
+Note: Since CFEngine 3.27.0 it's possible to configure the evaluation order from
+the pre-defined normal order to the written order, top down.
+
+**See also:** [`evaluation_order` in `body agent control`](/reference/components/cf-agent/#evaluation_order), [`evaluation_order` in `body common control`][Components#evaluation_order], [`evaluation_order` in `body file control`][file control#evaluation_order]
+
 ### Policy evaluation overview
 
 CFEngine policy evaluation is done in several steps: