provisioners/ansible(both): Review of PR #8913

- Keep the Programming Errors with corresponding Exception class and
  en.yml message template. Fix the alphabetical order in errors.rb by
  the way.
- Fix English wording in the documentation and en.yml messages
- Use StandardError for unknown error rescuing.

Thanks @chrisroberts!

plugins/provisioners/ansible/errors.rb

@@ -11,25 +11,30 @@ module VagrantPlugins
         error_key(:ansible_command_failed)
       end
 
-      class AnsibleNotFoundOnHost < AnsibleError
+      class AnsibleCompatibilityModeConflict < AnsibleError
-        error_key(:ansible_not_found_on_host)
+        error_key(:ansible_compatibility_mode_conflict)
       end
 
       class AnsibleNotFoundOnGuest < AnsibleError
         error_key(:ansible_not_found_on_guest)
       end
 
+      class AnsibleNotFoundOnHost < AnsibleError
+        error_key(:ansible_not_found_on_host)
+      end
+
       class AnsiblePipInstallIsNotSupported < AnsibleError
         error_key(:cannot_support_pip_install)
       end
 
+      class AnsibleProgrammingError < AnsibleError
+        error_key(:ansible_programming_error)
+      end
+
       class AnsibleVersionMismatch < AnsibleError
         error_key(:ansible_version_mismatch)
       end
 
-      class AnsibleCompatibilityModeConflict < AnsibleError
-        error_key(:ansible_compatibility_mode_conflict)
-      end
     end
   end
 end

plugins/provisioners/ansible/provisioner/base.rb

@@ -55,7 +55,7 @@ module VagrantPlugins
         def set_and_check_compatibility_mode
           begin
             set_gathered_ansible_version(gather_ansible_version)
-          rescue Exception => e
+          rescue StandardError => e
             # Nothing to do here, as the fallback on safe compatibility_mode is done below
             @logger.error("Error while gathering the ansible version: #{e.to_s}")
           end
@@ -83,7 +83,9 @@ module VagrantPlugins
           end
 
           unless Ansible::COMPATIBILITY_MODES.slice(1..-1).include?(config.compatibility_mode)
-            raise "Programming Error: compatibility_mode must correctly set at this stage!"
+            raise Ansible::Errors::AnsibleProgrammingError,
+              message: "The config.compatibility_mode must be correctly set at this stage!",
+              details: "config.compatibility_mode: '#{config.compatibility_mode}'"
           end
 
           @lexicon = ANSIBLE_PARAMETER_NAMES[config.compatibility_mode]
@@ -353,7 +355,12 @@ module VagrantPlugins
 
         def detect_compatibility_mode
           if !@gathered_version_major || config.compatibility_mode != Ansible::COMPATIBILITY_MODE_AUTO
-            raise "Programming Error: detect_compatibility_mode() shouldn't have been called."
+            raise Ansible::Errors::AnsibleProgrammingError,
+              message: "The detect_compatibility_mode() function shouldn't have been called!",
+              details: %Q(config.compatibility_mode: '#{config.compatibility_mode}'
+gathered version major number: '#{@gathered_version_major}'
+gathered version stdout version:
+#{@gathered_version_stdout})
           end
 
           if @gathered_version_major.to_i <= 1

templates/locales/en.yml

@@ -2338,6 +2338,11 @@ en:
           ansible_command_failed: |-
             Ansible failed to complete successfully. Any error output should be
             visible above. Please fix these errors and try again.
+          ansible_compatibility_mode_conflict: |-
+            The requested Ansible compatibility mode (%{compatibility_mode}) is in conflict with
+            the Ansible installation on your Vagrant %{system} system (currently: %{ansible_version}).
+            See https://docs.vagrantup.com/v2/provisioning/ansible_common.html#compatibility_mode
+            for more information.
           ansible_not_found_on_guest: |-
             The Ansible software could not be found! Please verify
             that Ansible is correctly installed on your guest system.
@@ -2355,6 +2360,18 @@ en:
             on your host system. Vagrant can't do this for you in a safe and
             automated way.
             Please check https://docs.ansible.com for more information.
+          ansible_programming_error: |-
+            Ansible Provisioner Programming Error:
+
+            %{message}
+
+            Internal Details:
+
+            %{details}
+
+            Sorry, but this Vagrant error should never occur.
+            Please check https://github.com/mitchellh/vagrant/issues for any
+            existing bug report. If needed, please create a new issue. Thank you!
           cannot_support_pip_install: |-
             Unfortunately Vagrant does not support yet installing Ansible
             from pip for the guest OS running in the machine.
@@ -2370,17 +2387,12 @@ en:
             or adapt the provisioner `version` option in your Vagrantfile.
             See https://docs.vagrantup.com/v2/provisioning/ansible_common.html#version
             for more information.
-          ansible_compatibility_mode_conflict: |-
-            The requested Ansible compatibility mode (%{compatibility_mode}) is in conflict with
-            the Ansible installation on your Vagrant %{system} system (currently: %{ansible_version}).
-            See https://docs.vagrantup.com/v2/provisioning/ansible_common.html#compatibility_mode
-            for more information.
           config_file_not_found: |-
             `%{config_option}` does not exist on the %{system}: %{path}
           extra_vars_invalid: |-
             `extra_vars` must be a hash or a path to an existing file. Received: %{value} (as %{type})
           no_compatibility_mode: |-
-            `compatibility_mode` must be correctly set (possible values: %{valid_modes}).
+            `compatibility_mode` must be a valid mode (possible values: %{valid_modes}).
           no_playbook: |-
             `playbook` file path must be set.
           raw_arguments_invalid: |-

website/source/docs/provisioning/ansible_common.html.md

@@ -17,15 +17,15 @@ These options get passed to the `ansible-playbook` command that ships with Ansib
 
 Some of these options are for advanced usage only and should not be used unless you understand their purpose.
 
-- `become` (boolean) - Cause Ansible to perform all the playbook tasks [as another user](http://docs.ansible.com/ansible/become.html), different from the one used to log into the guest system.
+- `become` (boolean) - Perform all the Ansible playbook tasks [as another user](http://docs.ansible.com/ansible/become.html), different from the user used to log into the guest system.
 
     The default value is `false`.
 
 - `become_user` (string) - Set the default username to be used by the Ansible `become` [privilege escalation](http://docs.ansible.com/ansible/become.html) mechanism.
 
-    By default this option is not defined, and the Ansible default value (`root`) will be used.
+    By default this option is not set, and the Ansible default value (`root`) will be used.
 
-- `compatibility_mode` (string) - Set the **minimal** version of Ansible to be supported. Vagrant will use some parameters that are only compatible since the given version.
+- `compatibility_mode` (string) - Set the **minimal** version of Ansible to be supported. Vagrant will only use parameters that are compatible with the given version.
 
     Possible values:
 
@@ -33,7 +33,7 @@ Some of these options are for advanced usage only and should not be used unless
     - `"1.8"` _(Ansible versions prior to 1.8 should mostly work well, but some options might not be supported)_
     - `"2.0"` _(The generated Ansible inventory will be incompatible with Ansible 1.x)_
 
-    By default this option is set to `"auto"`. If Vagrant is not able to detect any supported Ansible version, it will falls back on the compatibility mode `"1.8"` with a warning.
+    By default this option is set to `"auto"`. If Vagrant is not able to detect any supported Ansible version, it will fall back on the compatibility mode `"1.8"` with a warning.
 
     Vagrant will error if the specified compatibility mode is incompatible with the current Ansible version.
 
@@ -44,7 +44,7 @@ Some of these options are for advanced usage only and should not be used unless
 
     <div class="alert alert-info">
       <strong>Compatibility Note:</strong>
-      This option was introduced in Vagrant 2.0. Previous Vagrant versions behave like if this option was set to `"1.8"`.
+      This option was introduced in Vagrant 2.0. The behavior of previous Vagrant versions can be simulated by setting the `compatibility_mode` to `"1.8"`.
     </div>
 
 - `config_file` (string) - The path to an [Ansible Configuration file](https://docs.ansible.com/intro_configuration.html).