docs: upgrade guide 2.x: changes on ansible commands

docs/upgrade_guide_to_2.x.md

@@ -6,16 +6,20 @@
     - [Replacing the _command_ argument](#replacing-the-command-argument)
     - [Replacing the _resultsFunc_ argument](#replacing-the-resultsfunc-argument)
     - [Replacing the _options_ argument](#replacing-the-options-argument)
+  - [New interfaces](#new-interfaces)
   - [Changes on the _DefaultExecute_ struct](#changes-on-the-defaultexecute-struct)
     - [Adding _Cmd_ attribute to generate commands](#adding-cmd-attribute-to-generate-commands)
     - [Adding _Exec_ attribute for running external commands](#adding-exec-attribute-for-running-external-commands)
     - [Adding _Output_ attribute for printing execution results](#adding-output-attribute-for-printing-execution-results)
     - [Removing the _ShowDuration_ attribute](#removing-the-showduration-attribute)
-    - [Adpating your code to new the _Transformer_ location](#adpating-your-code-to-new-the-transformer-location)
+    - [Changing the _Transformer_ location](#changing-the-transformer-location)
   - [Changes on the _AnsiblePlaybookCmd_ struct](#changes-on-the-ansibleplaybookcmd-struct)
     - [Removing the _Exec_ attribute and _Run_ method](#removing-the-exec-attribute-and-run-method)
     - [Removing the _StdoutCallback_ attribute](#removing-the-stdoutcallback-attribute)
   - [Changes on the _AnsibleAdhocCmd_ struct](#changes-on-the-ansibleadhoccmd-struct)
+  - [Managing Ansible configuration settings](#managing-ansible-configuration-settings)
+    - [Removing configuration functions](#removing-configuration-functions)
+  - [Managing Ansible Stdout Callback](#managing-ansible-stdout-callback)
   - [Packages Reorganization](#packages-reorganization)
     - [github.com/apenella/go-ansible/pkg/stdoutcallback](#githubcomapenellago-ansiblepkgstdoutcallback)
 
@@ -46,7 +50,7 @@ To align with the updated `Executor` interface, you need to adapt your custom ex
 
 ### Replacing the _command_ argument
 
-Instead of using the _command_ argument, the `Executor` should expect a `Commander` to generates the command to execute. Therefore, your executor should include an attribute of type `Commander`. The `Commander` is interface defined in _github.com/apenella/go-ansible/pkg/execute_ as follows:
+Instead of using the _command_ argument, the `Executor` requires a `Commander` to generate the command to execute. Therefore, your executor should include an attribute of type `Commander`. The `Commander` interface defined in _github.com/apenella/go-ansible/pkg/execute_ as follows:
 
 ```go
 // Commander generates commands to be executed
@@ -62,7 +66,7 @@ You can review changes on `DefaultExecute` [here](#adding-cmd-attribute-to-gener
 
 ### Replacing the _resultsFunc_ argument
 
-The _resultsFunc_ previously managed the results output from command execution. With its removal, your executor should expect a new component to assume this responsibility. That component for handling the results output should be of type `ResultsOutputer`.
+The _resultsFunc_ previously managed the results output from command execution. With its removal, your executor requires a new component to assume this responsibility. That component for handling the results output should be of type `ResultsOutputer`.
 A `ResultsOutputer` is an interface defined in _github.com/apenella/go-ansible/pkg/execute/result_ as follows:
 
 ```go
@@ -93,14 +97,29 @@ To sum it up, to replace the _resultsFunc_, introduce an attribute of type `Resu
 
 By removing the options argument, the ability to overwrite the `Executor` struct attributes in the `Execute` method is no longer available. To configure your executor, you must set it up during the instantiation of the struct.
 
+## New interfaces
+
+// TODO
+
 ## Changes on the _DefaultExecute_ struct
 
 The `DefaultExecute` struct is a ready-to-go component provided by the _go-ansible_ library for executing external commands. You can find its definition in the _github.com/apenella/go-ansible/pkg/execute_ package.
-Changes on the `Executor` interface impacts the `DefaultExecute` struct. You can read more about the changes on the `Executor` interface [here](#changes-on-the-executor-interface).
+Changes on the `Executor` interface impact the `DefaultExecute` struct. You can read more about the changes on the `Executor` interface [here](#changes-on-the-executor-interface).
 
-In version _v2.x_ you need to instantiate the `DefaultExecute` struct to execute the Ansible commands, as is shown in the following code snippet. 
+In version _v2.x_ you need to instantiate the `DefaultExecute` struct to execute the Ansible commands, as is shown in the following code snippet.
 
 ```go
+// Define the AnsiblePlaybookCmd and the required options.
+playbookCmd := &playbook.AnsiblePlaybookCmd{
+  Playbooks:         []string{"site.yml", "site2.yml"},
+  ConnectionOptions: &options.AnsibleConnectionOptions{
+    Connection: "local",
+  },
+  Options:           &playbook.AnsiblePlaybookOptions{
+    Inventory: "all,",
+  },
+}
+
 // playbookCmd is the Commander responsible for generating the command to execute
 exec := execute.NewDefaultExecute(
   execute.WithCmd(playbookCmd),
@@ -117,9 +136,9 @@ If you already configured the `DefaultExecute` struct in your code, you should a
 
 ### Adding _Cmd_ attribute to generate commands
 
-The `DefaultExecute` requires a `Commander` to generate the external ommand to execute. For that reason, it includes the `Cmd` attribute of type `Commander`. Both the `AnsiblePlaybookCmd` and `AnsibleAdhocCmd` structs implement the `Commander` interface.
+The `DefaultExecute` requires a `Commander` to generate the external command to execute. For that reason, it includes the `Cmd` attribute of type `Commander`. Both the `AnsiblePlaybookCmd` and `AnsibleAdhocCmd` structs implement the `Commander` interface.
 
-When you instantiate the `DefaultExecute` struct, you should provide the `Cmd` attribute with a `Commander` to generate the commands. The following code shows how to instantiate the `DefaultExecute` struct using a `AnsiblePlaybookCmd` as the `Commander`.
+When you instantiate the `DefaultExecute` struct, you should provide the `Cmd` attribute with a `Commander` to generate the commands. The following code shows how to instantiate the `DefaultExecute` struct using an `AnsiblePlaybookCmd` as the `Commander`.
 
 ```go
 // Define the AnsiblePlaybookCmd and the required options.
@@ -145,7 +164,7 @@ In the example above, the `playbookCmd` is of type `Commander`. You set the `Cmd
 In the latest _go-ansible_ version, the `DefaultExecute` struct includes the `Exec` attribute of type `Executabler`. The `Exec` component is responsible for executing external commands.
 By default, if you do not define the `Exec` attribute, it uses the `OsExec` struct. The `OsExec` implementation is found in the _github.com/apenella/go-ansible/internal/execute/executable/os/exec_ package. This struct wraps the `os/exec` package.
 
-If you need to implement a custom executabler, you should implement the `Executabler` interface. The interface is defined in _github.com/apenella/go-ansible/pkg/execute_ as follows:
+In case you require to implement a custom _executabler_, it needs to implement the `Executabler` interface. The interface is defined in _github.com/apenella/go-ansible/pkg/execute_ as follows:
 
 ```go
 // Executabler is an interface to run commands
@@ -155,7 +174,7 @@ type Executabler interface {
 }
 ```
 
-Below, you can find an example of how to instantiate a `DefaultExecute` struct with a custom executabler.
+Below, you can find an example of how to instantiate a `DefaultExecute` struct with a custom _executabler_.
 
 ```go
 // Define the AnsiblePlaybookCmd and the required options.
@@ -179,7 +198,7 @@ executor := execute.NewDefaultExecute(
 )
 ```
 
-In the example above, _executable_ implements the `Executabler` interface. When you instantiate a new `DefaultExecute`, you set the `Exec` value to _executable_ using the function `WithExecutable`. So, the `DefaultExecute` will use the _executable_ to execute the command.
+In the example above, the `executable` variable implements the `Executabler` interface. When you instantiate a new `DefaultExecute`, you set the value to `Exec` through the function `WithExecutable`. So, the `DefaultExecute` will use the _executable_ to execute the command.
 
 ### Adding _Output_ attribute for printing execution results
 
@@ -226,7 +245,7 @@ The example above shows how to instantiate a `DefaultExecute` struct with a cust
 
 ### Removing the _ShowDuration_ attribute
 
-As announced in prior go-ansible versions, the `DefaultExecute` has removed the ShowDuration attribute.
+As announced in prior _go-ansible_ versions, the `DefaultExecute` has removed the `ShowDuration` attribute.
 
 Starting from version _v2.0.0_, to measure the duration of the execution, you should use the `ExecutorTimeMeasurement` struct. This struct acts as a decorator over the `Executor` and is available in the _github.com/apenella/go-ansible/pkg/execute/measure_ package.
 
@@ -247,7 +266,7 @@ if err != nil {
 fmt.Println("Duration: ", exec.Duration().String())
 ```
 
-### Adpating your code to new the _Transformer_ location
+### Changing the _Transformer_ location
 
 You can configure a set of transformers to modify the output of the execution's results. The _go-ansible_ library has moved the `transformer` package from _github.com/apenella/go-ansible/pkg/stdoutcallback/results_ to _github.com/apenella/go-ansible/pkg/execute/result/transformer_. So, you should adapt your code to this change.
 
@@ -261,6 +280,8 @@ The `AnsiblePlaygookCmd` struct is not responsible for executing commands anymor
 
 Along with the `Exec` attribute, the `Run` method is not available anymore. To execute a command, you should use an `Executor`. Then, the `Executor` should receive an `AnsiblePlaybookCmd` struct to generate the command to execute.
 
+The following snip showcases a basic example of how to run an `ansible-playbook` command through an `Executor`.
+
 ```go
 // Define the AnsiblePlaybookCmd and the required options.
 playbookCmd := &playbook.AnsiblePlaybookCmd{
@@ -287,8 +308,69 @@ if err != nil {
 
 ### Removing the _StdoutCallback_ attribute
 
+The responsibility to set the stdout callback method is not part of the `AnsiblePlaybookCmd` struct anymore, so the attribute `StdoutCallback` has been removed from there.
+Setting the `StdoutCallback` method implies setting the environment variable `ANSIBLE_STDOUT_CALLBACK` and the component to handle the results output from command execution. From now on, the `Executor` struct is in charge of that setup. So, you should adapt your code to this change.
+
+The library already provides a set of structs that facilitate the stdout callback configuration. These structs act as decorators over the `Executor` struct, and are responsible for setting the stdout callback method, as well as the results output mechanism.
+
+Here you have an example of how to set up the JSON stdout callback method.
+
+```go
+// Define the AnsiblePlaybookCmd and the required options.
+playbookCmd := &playbook.AnsiblePlaybookCmd{
+  Playbooks:         []string{"site.yml", "site2.yml"},
+  ConnectionOptions: &options.AnsibleConnectionOptions{
+    Connection: "local",
+  },
+  Options:           &playbook.AnsiblePlaybookOptions{
+    Inventory: "127.0.0.1,",
+  },
+}
+
+// Use the DefaultExecute struct to execute the command
+exec := execute.NewDefaultExecute(
+  execute.WithCmd(playbookCmd),
+)
+
+// Use the JSONStdoutCallbackExecute struct to set the JSON stdout callback method
+jsonexec := stdoutcallback.NewJSONStdoutCallbackExecute(exec)
+
+// Execute the external command through the executor
+err := jsonexec.Execute(context.TODO())
+if err != nil {
+  panic(err)
+}
+```
+
+Delve into the section [Managing Ansible Stdout Callback](#managing-ansible-stdout-callback) to learn the mechanism to set the stdout callback method.
+
 ## Changes on the _AnsibleAdhocCmd_ struct
 
+Regarding the `AnsibleAdhocCmd` struct, the changes are similar to those on the `AnsiblePlaybookCmd` struct. The `AnsibleAdhocCmd` struct no longer executes commands. Instead, it implements the `Commander` interface, which generates commands for execution. So, you need to adapt your code to these changes.
+
+Review the section [Changes on the _AnsiblePlaybookCmd_ struct](#changes-on-the-ansibleplaybookcmd-struct) to learn how to adapt your code to these changes.
+
+## Managing Ansible configuration settings
+
+// TODO
+AnsibleForceColor
+AnsibleAvoidHostKeyChecking
+AnsibleSetEnv
+
+### Removing configuration functions
+
+// TODO
+
+## Managing Ansible Stdout Callback
+
+// TODO
+
+Setting the StdoutCallback method implies the following. Firstly, set the environment variable `ANSIBLE_STDOUT_CALLBACK` to the name of the stdout callback plugin. Secondly, set the method that manages the results output from command execution. The responsibility to set the StdooutCallback method has been moved to the `Executor` struct. So, you should adapt your code to this change.
+
+remove stdoutcallback packages
+
+results package
+
 ## Packages Reorganization
 
 Version v2.0.0 introduces changes to the package structure, including some reorganization and removals. This section outlines the necessary steps to migrate from the older packages to the new ones.