ENT-9751: Moved policy writing and module development into tutorials section

.github/workflows/formatting.yml

@@ -7,7 +7,7 @@ permissions:
 
 jobs:
   check:
-    name: Check formatting using cfengine dev docs-format
+    name: Check formatting using CFEngine CLI
     runs-on: ubuntu-24.04
     steps:
       - name: Checks-out repository

content/_index.markdown

@@ -35,15 +35,7 @@ aliases:
             <div>Know more about your infrastructure and hosts, their data, compliance and make changes from within the Web UI.</div>
          </li>
          <li>
-            <a href="/getting-started/writing-policy">Writing policy</a>
-            <div>Write and deploy your first policy files to make changes to systems.</div>
-         </li>
-         <li>
-            <a href="/getting-started/developing-modules">Developing modules</a>
-            <div>Turn your policy, reports, or python code into CFEngine Build modules for others to use.</div>
-         </li>
-         <li>
-            <a href="/examples/tutorials/writing-and-serving-policy">Tutorial series on policy language</a>
+            <a href="/examples/tutorials/policy-writing">Tutorial series on policy language</a>
             <div>In-depth tutorials on how to work with CFEngine policy.</div>
          </li>
       </ul>

content/api/enterprise-api-ref/vcs-settings.markdown

@@ -35,7 +35,7 @@ curl -k --user <username>:<password> \
     "data": {
         "GIT_URL": "https://github.com/cfengine/masterfiles.git",
         "GIT_REFSPEC": "master",
-        "PROJECT_SUBDIRECTORY": "path/to/policies",
+        "PROJECT_SUBDIRECTORY": "path/to/policy",
         "GIT_USERNAME": "username",
         "GIT_PASSWORD": "passwordOrToken",
         "GIT_WORKING_BRANCH": "CF_WORKING_BRANCH",

content/enterprise-cfengine-guide/_index.markdown

@@ -45,11 +45,11 @@ The CFEngine Enterprise `Mission Portal` provides System Administrators and Infr
 
 ### Federation and SQL reporting
 
-CFEngine Enterprise has the ability to create federated structures, in which parts of organizations can have their own configuration policies, while at the same time the central IT organization may impose some policies that are more global in nature.
+CFEngine Enterprise has the ability to create federated structures, in which parts of organizations can have their own configuration, while at the same time the central IT organization may impose some policy that is more global in nature.
 
 ### Monitoring and reporting
 
-The CFEngine Enterprise Mission Portal contains continual reporting that details compliance with policies, repairs and any failures of hosts to match their desired state.
+The CFEngine Enterprise Mission Portal contains continual reporting that details compliance with policy, repairs and any failures of hosts to match their desired state.
 
 ### Role-based access control
 

content/enterprise-cfengine-guide/install-get-started.markdown

@@ -33,13 +33,13 @@ For Enterprise 3.6 local mail relay is used, and it is assumed the server has a
 
 The default FROM email for all emails sent from the Mission Portal is `[email protected]`. This can be changed on the CFE Server in `/var/cfengine/httpd/htdocs/application/config/appsettings.php:$config['appemail']`.
 
-### Version your policies
+### Version your policy
 
-Consider enabling the built-in version control of your policies as
+Consider enabling the built-in version control of your policy as
 described in
 [Version control and configuration policy][Best practices#Version control and configuration policy]
 
-Whether you do or not, please put your policies in some kind of
+Whether you do or not, please put your policy in some kind of
 backed-up VCS. Losing work because of "fat fingering" `rm` commands is
 very, very depressing.
 

content/examples/_index.markdown

@@ -37,7 +37,7 @@ In this tutorial, you will perform the following:
 
 ### "Hello world" policy example
 
-Policies contain **bundles**, which are collections of promises. A **promise** is a declaration of
+Policy files contain **bundles**, which are collections of promises. A **promise** is a declaration of
 intent. Bundles allow related promises to be grouped together, as illustrated in the steps that follow.
 
 Following these steps, you will login to your policy server via the SSH protocol, use the vi command line editor to create a policy file named hello_world.cf, and create a bundle that calls a promise to display some text.

content/examples/tutorials/dashboard-alerts.markdown

@@ -54,6 +54,6 @@ If you click on the Dashboard tab and go to the front page, you will see that ou
 
 2. Conclusions
 
-In this tutorial, we have shown how easy it is to prove compliance of any of your policies by using the Dashboard alert functionality.
+In this tutorial, we have shown how easy it is to prove compliance with your policy by using the Dashboard alert functionality.
 
 If you would like to get an overview of whenever CFEngine is making a change to your system, simply create another alert, but this time set the Promise Status to 'Repaired'. This time you will see an alert whenever CFEngine is repairing a drift, for instance if a user is accidentially deleted.

content/examples/tutorials/distribute-files-from-a-central-location.markdown

@@ -6,7 +6,7 @@ aliases:
   - "/examples-tutorials-distribute-files-from-a-central-location.html"
 ---
 
-CFEngine can manage many machines simply by distributing policies to all its hosts.
+CFEngine can manage many machines simply by distributing policy files to all its hosts.
 This tutorial describes how to distribute files to hosts from a central policy server location.
 For this example, we will distribute software patches.
 

content/examples/tutorials/manage-ntp.markdown

@@ -94,7 +94,7 @@ The handle uniquely identifies a promise within a policy. A recommended naming s
 classes         => results("bundle", "ntp_package_");
 ```
 
-`classes` provide context which can help drive the logic in your policies. In this example, classes for each promise outcome are defined prefixed with `ntp_package_`, for details check out the implementation of `body classes results` in the stdlib. For example, `ntp_package_repaired` will be defined if cf-agent did not have the ntp package installed and had to install it. `ntp_package_kept` would be defined if the ntp package is already installed and `ntp_package_notkept` would be defined.
+`classes` provide context which can help drive the logic in your policy. In this example, classes for each promise outcome are defined prefixed with `ntp_package_`, for details check out the implementation of `body classes results` in the stdlib. For example, `ntp_package_repaired` will be defined if cf-agent did not have the ntp package installed and had to install it. `ntp_package_kept` would be defined if the ntp package is already installed and `ntp_package_notkept` would be defined.
 
 On your hub create `services/ntp.cf` inside _masterfiles_ with the following content:
 
@@ -281,7 +281,7 @@ You have now written a complete policy to ensure that the NTP package is install
 
 Now we will manage the configuration file using the built-in mustache templating engine, set up appropriate file permissions, and restart the service when necessary.
 
-By default, the NTP service leverages configuration properties specified in /etc/ntp.conf. In this tutorial, we introduce the concept of the files promise type. With this promise type, you can create, delete, and edit files using CFEngine policies. The example policy below illustrates the use of the files promise.
+By default, the NTP service leverages configuration properties specified in /etc/ntp.conf. In this tutorial, we introduce the concept of the files promise type. With this promise type, you can create, delete, and edit files using CFEngine policy. The example policy below illustrates the use of the files promise.
 
 ```cf3
 bundle agent ntp

content/examples/tutorials/writing-and-serving-policy/_index.markdown → content/examples/tutorials/policy-writing/_index.markdown

@@ -1,12 +1,13 @@
 ---
 layout: default
-title: Writing and serving policy
+title: Policy writing
 sorting: 100
 aliases:
   - "/examples-tutorials-writing-and-serving-policy.html"
+  - "/examples/tutorials/writing-and-serving-policy"
 ---
 
-## About policies and promises
+## About policy and promises
 
 Central to CFEngine's effectiveness in system administration is the concept of a "promise," which defines the intent and expectation of how some part of an overall system should behave.
 
@@ -104,7 +105,7 @@ needless fragility and keep two independent quality assurance processes apart.
 
 - [Bundles best practices][Bundles best practices] Refer to this page as you decide when to make a bundle and when to use classes and/or variables in them.
 
-- [Testing policies][Testing policies] This page describes how to locally test CFEngine and play with configuration files.
+- [Testing policy][Testing policy] This page describes how to locally test CFEngine and play with configuration files.
 
 ## See also
 

content/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown → content/examples/tutorials/policy-writing/authoring-policy-tools-and-workflow.markdown

@@ -4,6 +4,7 @@ title: Authoring policy tools & workflow
 sorting: 5
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-authoring-policy-tools-and-workflow.html"
+  - "/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow"
 ---
 
 There are several ways to approach authoring promises and ensuring they are copied into and then deployed properly from the `masterfiles` directory:

content/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown → content/examples/tutorials/policy-writing/bundles-best-practices.markdown

@@ -4,6 +4,7 @@ title: Bundles best practices
 sorting: 20
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-bundles-best-practices.html"
+  - "/examples/tutorials/writing-and-serving-policy/bundles-best-practices"
 ---
 
 The following contains practices to remember when creating bundles as

content/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown → content/examples/tutorials/policy-writing/controlling-frequency.markdown

@@ -4,6 +4,7 @@ title: Controlling frequency
 sorting: 90
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-controlling-frequency.html"
+  - "/examples/tutorials/writing-and-serving-policy/controlling-frequency"
 ---
 
 By default CFEngine runs relatively frequently (every 5 minutes) but you may not

content/examples/tutorials/writing-and-serving-policy/editors.markdown → content/examples/tutorials/policy-writing/editors.markdown

@@ -4,13 +4,14 @@ title: Editors
 sorting: 10
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-editors.html"
+  - "/examples/tutorials/writing-and-serving-policy/editors"
 ---
 
 Using an editor that provides syntax highlighting and other features can significantly enhance prodcutivity and quality of life.
 
 ## Emacs
 
-For Emacs users, editing CFEngine policies is easy with the built-in CFEngine 3 mode in the [cfengine.el library](https://github.com/cfengine/core/blob/master/contrib/cfengine.el). For an overview of the capabilities, see the [webinar by Ted Zlatanov](https://www.youtube.com/watch?v=-PPVhwSKNdE) and Appendix A of Diego Zamboni's [Learning CFEngine](https://leanpub.com/learning-cfengine/) book.
+For Emacs users, editing CFEngine policy is easy with the built-in CFEngine 3 mode in the [cfengine.el library](https://github.com/cfengine/core/blob/master/contrib/cfengine.el). For an overview of the capabilities, see the [webinar by Ted Zlatanov](https://www.youtube.com/watch?v=-PPVhwSKNdE) and Appendix A of Diego Zamboni's [Learning CFEngine](https://leanpub.com/learning-cfengine/) book.
 
 ![Emacs](guide-writing-and-serving-policy-editors-emacs.png)
 
@@ -22,7 +23,7 @@ Spacemacs has a [CFEngine layer](https://github.com/syl20bnr/spacemacs/blob/deve
 
 ## Vi/Vim
 
-Vi/Vim users can edit CFEngine policies with Neil Watson's CFEngine 3 scripts, available as GPL-software [on GitHub](https://github.com/neilhwatson/vim_cf3). Neil's vi mode is also described in Appendix B of Diego Zamboni's "Learning CFEngine" book.
+Vi/Vim users can edit CFEngine policy with Neil Watson's CFEngine 3 scripts, available as GPL-software [on GitHub](https://github.com/neilhwatson/vim_cf3). Neil's vi mode is also described in Appendix B of Diego Zamboni's "Learning CFEngine" book.
 
 ![Vim](guide-writing-and-serving-policy-editors-vim.png)
 

content/examples/tutorials/writing-and-serving-policy/external_data.markdown → content/examples/tutorials/policy-writing/external_data.markdown

@@ -4,6 +4,7 @@ title: External data
 sorting: 50
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-external_data.html"
+  - "/examples/tutorials/writing-and-serving-policy/external-data"
 ---
 
 It is common to integrate CFEngine with external data sources. External data

content/examples/tutorials/write-cfengine-policy.markdown → content/examples/tutorials/policy-writing/introduction-to-policy-writing.markdown

@@ -1,17 +1,18 @@
 ---
 layout: default
-title: Writing CFEngine policy
+title: Introduction to policy writing
 sorting: 3
 aliases:
   - "/examples-tutorials-write-cfengine-policy.html"
+  - "/examples/tutorials/write-cfengine-policy"
 ---
 
 To define new Desired States in CFEngine, you need to write policy files. These are plain text-files, traditionally with a `.cf` extension.
 
 ## /var/cfengine/inputs and promises.cf
 
-In CFEngine, `cf-agent` executes all policies. `cf-agent` runs every 5 minutes
-by default, and it executes policies found locally in the `/var/cfengine/inputs`
+In CFEngine, `cf-agent` enforces your policy. `cf-agent` runs every 5 minutes
+by default, and it evaluates policy files found locally in the `/var/cfengine/inputs`
 directory. The default policy entry is a file called `promises.cf`. In this file
 you normally reference bundles and other policy files.
 
@@ -102,9 +103,9 @@ Stand Alone system. The next two sections will cover each of the options.
 
 ### Option#1: Running the policy on a stand alone system
 
-Since CFEngine is fully distributed we can run policies locally. This can come
+Since CFEngine is fully distributed we can run policy locally. This can come
 in handy as the result of a run is instant, especially during the design phase
-where you would like to test out various policies.
+where you would like to test out various policy files.
 
 To run the file locally, you can log into any of your hosts that has CFEngine
 installed and follow these steps. For this tutorial, use your Policy Server for
@@ -124,7 +125,7 @@ cf-agent -Kf /tmp/example.cf
 ```
 
 As you can see, the response is immediate! Running CFEngine locally like this is
-ideal for testing out new policies. To check that the file has been successfully
+ideal for testing out new policy. To check that the file has been successfully
 created type:
 
 ```command
@@ -144,7 +145,7 @@ In a Stand Alone system, to make and run a policy remember to:
 
 CFEngine is designed for large-scale systems. It is fully distributed which
 means that all the logic and decision making takes place on the end-points, or
-hosts as we call them in CFEngine. The hosts fetch their policies from one
+hosts as we call them in CFEngine. The hosts fetch their policy from one
 central distribution point. To continue with this option you need to have
 CFEngine running on at least one host and one policy server.
 
@@ -157,7 +158,7 @@ By default `cf-serverd` will serve policy from the `/var/cfengine/masterfiles`
 directory. When the content changes, cf-agent will download the updated files to
 `/var/cfengine/inputs` before executing them locally.
 
-This means that by default you should store all your policies in the
+This means that by default you should store all your policy in the
 `/var/cfengine/masterfiles` directory on your policy server. So, now create
 `/var/cfengine/masterfiles/example.cf` with the content of the test policy
 previously authored.
@@ -198,5 +199,5 @@ this a promise repaired. If the file exists during a run, the result would be
 promise kept.
 
 Congratulations! You now have the basic knowledge needed to write and run
-CFEngine policies. Let's continue with an example on how to manage users. Click
+CFEngine policy. Let's continue with an example on how to manage users. Click
 here to continue.

content/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction.markdown → content/examples/tutorials/policy-writing/policy-layers-abstraction.markdown

@@ -4,6 +4,7 @@ title: Layers of abstraction in policy
 sorting: 2
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-policy-layers-abstraction.html"
+  - "/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction"
 ---
 
 CFEngine offers a number of layers of abstraction. The most fundamental atom

content/examples/tutorials/writing-and-serving-policy/policy-style.markdown → content/examples/tutorials/policy-writing/policy-style.markdown

@@ -4,6 +4,7 @@ title: Policy style guide
 sorting: 10
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-policy-style.html"
+  - "/examples/tutorials/writing-and-serving-policy/policy-style"
 ---
 
 Style is a very personal choice and the contents of this guide should only be

content/getting-started/04-writing-policy.markdown → content/examples/tutorials/policy-writing/policy-writing-with-cfbs.markdown

@@ -1,14 +1,14 @@
 ---
 layout: default
-title: Writing policy
+title: Policy writing with cfbs
 sorting: 40
 aliases:
   - "/getting-started-writing-policy.html"
   - "/getting-started/writing-policy"
+  - "/getting-started/04-writing-policy"
 ---
 
-Now that we are familiar with how CFEngine works, and how you can use modules and the web UI, let's take a look at policy.
-CFEngine policy language is a flexible, declarative language for describing the desired state of your infrastructure (or individual host).
+In this tutorial we will show how to write and run CFEngine policy for someone already using `cfbs` and `cf-remote`.
 
 To start, create a new file and open it, or the folder, in your editor:
 
@@ -207,10 +207,6 @@ To speed it up, you can click the hostname to go to the host info page, and the
 ## Next steps
 
 This is by no means a complete guide to policy writing, but should give you an idea of how to use modules, and get started building and experimenting.
-Next, we will look at implementing modules, such as the git promise type we used here:
-
-[Developing modules][Developing modules]
-
 If you would like to learn more about policy writing, these are some good resources to look at:
 
 - [Language concepts][Language concepts]

content/examples/tutorials/writing-and-serving-policy/promises-available-in-cfengine.markdown → content/examples/tutorials/policy-writing/promises-available-in-cfengine.markdown

@@ -4,6 +4,7 @@ title: Promises available in CFEngine
 sorting: 4
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-promises-available-in-cfengine.html"
+  - "/examples/tutorials/writing-and-serving-policy/promises-available-in-cfengine"
 ---
 
 ### meta - information about promise bundles

content/examples/tutorials/writing-and-serving-policy/testing-policies.markdown → content/examples/tutorials/policy-writing/testing-policy.markdown

@@ -1,9 +1,11 @@
 ---
 layout: default
-title: Testing policies
+title: Testing policy
 sorting: 50
 aliases:
   - "/examples-tutorials-writing-and-serving-policy-testing-policies.html"
+  - "/examples/tutorials/writing-and-serving-policy/testing-policies"
+  - "/examples/tutorials/policy-writing/testing-policies"
 ---
 
 One of the practical advantages of CFEngine is that you can test it without

content/getting-started/05-developing-modules.markdown → content/examples/tutorials/promise-type-module-development.markdown

@@ -1,13 +1,14 @@
 ---
 layout: default
-title: Developing modules
+title: Promise type module development
 sorting: 50
 aliases:
   - "/getting-started-developing-modules.html"
   - "/getting-started/developing-modules"
+  - "/getting-started/05-developing-modules"
 ---
 
-Modules, such as the one we've used for git promises, are easy to write.
+Promise type modules are easy to write.
 In this tutorial, we will focus on implementing a new promise type in Python, with the provided CFEngine library, since this is the easiest and recommended way.
 If you are interested in how modules are implemented, or how you could do it in another programming language, see the [complete documentation][custom].
 

content/getting-started/01-installation/installation-overview.markdown

@@ -24,7 +24,7 @@ Additional options for configuring CFEngine policy are as follows:
   Learn how to control frequency settings for verifying CFEngine policy.
 
 - [Version control]
-  Learn how to put your CFEngine policies under version control.
+  Learn how to put your CFEngine policy under version control.
 
 - [Masterfiles Policy Framework]
   Learn what options are available out of the box in CFEngine to configure its masterfiles operation.

content/getting-started/03-reporting-and-web-ui.markdown

@@ -83,4 +83,4 @@ At this point you have a good overview of what CFEngine does, and you can choose
 Once you feel comfortable with the CFEngine Hub, modules, and reports, you are ready to move on, and learn CFEngine's expressive policy language and powerful module system.
 You're not limited by what modules others have made, you can write the code you need to get things done:
 
-[Writing policy][Writing policy]
+[Policy writing][Policy writing]

content/getting-started/_index.markdown

@@ -21,5 +21,3 @@ Afterwards, we will continue to more advanced topics, such as policy writing and
 1. [Part 1: Installation][Installation]
 2. [Part 2: Modules from CFEngine Build][Modules from CFEngine Build]
 3. [Part 3: Reporting and web UI][Reporting and web UI]
-4. [Part 4: Writing policy][Writing policy]
-5. [Part 5: Developing modules][Developing modules]