CFE-3299: Docs for evaulation_order => top_down

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

@@ -36,7 +36,7 @@ The other is reader optimized where promises are written in the
 order they make sense to the reader. Both styles have their merits,
 but there seems to be a trend toward the reader optimized style.
 
-1. Normal Order
+### Normal Order
 
 Here is an example of a policy written in the Normal Order. Note how
 `packages` are listed after `files`. This could confuse a novice who
@@ -77,29 +77,39 @@ bundle agent main
 }
 ```
 
-2. Reader Optimized
+### Reader Optimized
 
 Here is an example of a policy written to be optimized for the reader.
 Note how packages are listed before files in the order which users
 think about taking imperitive action. This style can make it
-significantly easier for a novice to understand the desired state, but
-it is important to remember that Normal ordering still applies and
-that the promises will not be actuated in the order they are written.
+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.
 
 ```cf3
-bundle agent main
+body common control
 {
-  vars:
+  evaluation_order => "top_down";
+}
 
-      "sshd_config"
-        string => "/etc/ssh/sshd_config";
+bundle agent main
+{
 
   packages:
 
       "ssh"
         policy => "present";
         package_module => apt_get;
 
+  vars:
+
+      "sshd_config"
+       string => "/etc/ssh/sshd_config";
+
   files:
 
       "$(sshd_config)"
@@ -119,6 +129,8 @@ bundle agent main
 }
 ```
 
+When using `top_down` evaluation, the "Reader Optimized" style becomes the actual execution order.
+
 ## Whitespace and line length
 
 Spaces are preferred to tab characters.

content/reference/components/_index.markdown

@@ -130,6 +130,37 @@ vars:
 you expect your policies to be run by older version, you'll need an explicit
 `bundlesequence`.
 
+### evaluation_order
+
+**Description:** Controls the evaluation order of promises within a bundle.
+
+This setting allows you to change how `cf-agent` executes promises. 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 `cf-agent` to evaluate promises in the order they are written in the policy file, from top to bottom. This can make policy easier to write and understand, especially for new users, as the execution flow follows the visual layout of the code.
+
+This attribute can be set in `body common control` to affect all components, or in `body agent control` to affect only `cf-agent`.
+
+**Type:** `string`
+
+**Allowed input range:** `(classic|top_down)`
+
+**Default value:** `classic`
+
+**Example:**
+
+```cf3
+body common control
+{
+  evaluation_order => "top_down";
+}
+```
+
+**See also:** [`evaluation_order` in `body common control`][cf-agent#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering]
+
+**History:**
+
+- Introduced in CFEngine 3.27.0
+
 ### bwlimit
 
 **Description:** Coarse control of bandwidth any cf-serverd or cf-agent process

content/reference/components/cf-agent.markdown

@@ -743,6 +743,37 @@ body action example
 
 **See also:** [`body action expireafter`][Promise types#expireafter], [`body contain exec_timeout`][commands#exec_timeout], [`body executor control agent_expireafter`][cf-execd#agent_expireafter]
 
+### evaluation_order
+
+**Description:** Controls the evaluation order of promises within a bundle for `cf-agent`.
+
+This setting allows you to change how `cf-agent` executes promises. 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 `cf-agent` to evaluate promises in the order they are written in the policy file, from top to bottom. This can make policy 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. If set in both, 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 agent control
+{
+  evaluation_order => "top_down";
+}
+```
+
+**See also:** [`evaluation_order` in `body common control`][Components#evaluation_order], [Policy style guide on promise ordering][Policy style guide#Promise ordering]
+
+**History:**
+
+- Introduced in CFEngine 3.27.0
+
 ### files_auto_define
 
 **Description:** The `files_auto_define` slist contains a list of regular expressions matching filenames. When a file matching one of these regular expressions is **copied to** classes prefixed with `auto_` are defined.