VMware: Deprecate vsphere_guest module (#35648)

This change deprecates vsphere_guest in favor of vmware_guest and other
related modules.

The major reasons behind deprecation are -

- Pysphere - Unofficial Python bindings of vCenter deprecated in the year 2013.
- VMware provides official Python bindings for vCenter, which is used in vmware_guest.
- vcsim - simulator used in integration testing of vmware module does not support PySphere
  APIs, which makes it more difficult to test vsphere_guest.

Please see [deprecation plan](https://github.com/ansible/community/wiki/VMware%3A-vsphere_guest_deprecation)

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

CHANGELOG.md

@@ -40,6 +40,7 @@ Ansible Changes By Release
 * nxos_switchport module is deprecated in Ansible 2.5. Use nxos_l2_interface module instead.
 * ec2_ami_find has been deprecated, use ec2_ami_facts.
 * panos_security_policy: Use panos_security_rule - the old module uses deprecated API calls
+* vsphere_guest is deprecated in Ansible 2.5 and will be removed in Ansible-2.9. Use vmware_guest module instead.
 
 See [Porting Guide](http://docs.ansible.com/ansible/devel/porting_guides.html) for more information
 

docs/docsite/rst/porting_guide_2.5.rst

@@ -141,6 +141,7 @@ The following modules will be removed in Ansible 2.9. Please update update your
 * :ref:`nxos_portchannel <nxos_portchannel>` use :ref:`nxos_linkagg <nxos_linkagg>` instead.
 * :ref:`nxos_switchport <nxos_switchport>` use :ref:`nxos_l2_interface <nxos_l2_interface>` instead.
 * :ref:`panos_security_policy <panos_security_policy>` use :ref:`panos_security_rule <panos_security_rule>` instead.
+* :ref:`vsphere_guest <vsphere_guest>` use :ref:`vmware_guest <vmware_guest>` instead.
 
 Noteworthy module changes
 -------------------------

lib/ansible/modules/cloud/vmware/_vsphere_guest.py

@@ -8,7 +8,7 @@ __metaclass__ = type
 
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
+                    'status': ['deprecated'],
                     'supported_by': 'community'}
 
 
@@ -16,6 +16,10 @@ DOCUMENTATION = '''
 ---
 module: vsphere_guest
 short_description: Create/delete/manage a guest VM through VMware vSphere.
+deprecated:
+    removed_in: "2.9"
+    why: "Replaced by M(vmware_guest) module. Also, 'Pysphere' is deprecated in favor of VMware's Official Python bindings - 'Pyvmomi'."
+    alternative: Use M(vmware_guest) and other vmware guest related modules instead.
 description:
      - Create/delete/reconfigure a guest VM through VMware vSphere. This module has a dependency on pysphere >= 1.7
 version_added: "1.6"
@@ -1768,6 +1772,8 @@ def main():
         ],
     )
 
+    module.deprecate("The 'vsphere_guest' module has been deprecated. Use 'vmware_guest' instead.", version=2.9)
+
     if not HAS_PYSPHERE:
         module.fail_json(msg='pysphere module required')