add deprecation for stat get_md5 (#33002)

lib/ansible/modules/windows/win_stat.ps1

@@ -62,7 +62,7 @@ function Date_To_Timestamp($start_date, $end_date)
 $params = Parse-Args $args -supports_check_mode $true
 
 $path = Get-AnsibleParam -obj $params -name "path" -type "path" -failifempty $true -aliases "dest","name"
-$get_md5 = Get-AnsibleParam -obj $params -name "get_md5" -type "bool" -default $true
+$get_md5 = Get-AnsibleParam -obj $params -name "get_md5" -type "bool" -default $false
 $get_checksum = Get-AnsibleParam -obj $params -name "get_checksum" -type "bool" -default $true
 $checksum_algorithm = Get-AnsibleParam -obj $params -name "checksum_algorithm" -type "str" -default "sha1" -validateset "md5","sha1","sha256","sha384","sha512"
 
@@ -73,9 +73,10 @@ $result = @{
     }
 }
 
-# Backward compatibility
-if ($get_md5 -eq $true -and (Get-Member -inputobject $params -name "get_md5") ) {
-    Add-DeprecationWarning -obj $result -message "The parameter 'get_md5' is being replaced with 'checksum_algorithm: md5'" -version 2.7
+# get_md5 will be an undocumented option in 2.9 to be removed at a later
+# date if possible (3.0+)
+if (Get-Member -inputobject $params -name "get_md5") {
+    Add-DepreactionWarning -obj $result -message "get_md5 has been deprecated along with the md5 return value, use get_checksum=True and checksum_algorithm=md5 instead" -version 2.9
 }
 
 $info = Get-FileItem -path $path
@@ -159,7 +160,7 @@ If ($info -ne $null)
             try {
                 $result.stat.md5 = Get-FileChecksum -path $path -algorithm "md5"
             } catch {
-                Fail-Json -obj $result -message "failed to get MD5 hash of file, set get_md5 to False to ignore this error: $($_.Exception.Message)"
+                Fail-Json -obj $result -message "failed to get MD5 hash of file, remove get_md5 to ignore this error: $($_.Exception.Message)"
             }
         }
 

lib/ansible/modules/windows/win_stat.py

@@ -42,28 +42,29 @@ options:
               and 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible
               2.3 this is back to an MD5. Will return None if host is unable to
               use specified algorithm.
-            - This option is deprecated in Ansible 2.3 and is replaced with
-              C(checksum_algorithm=md5).
-            - This option will be removed in Ansible 2.7
-        required: no
-        default: True
+            - The default of this option changed from C(yes) to C(no) in Ansible 2.5
+              and will be removed altogether in Ansible 2.9.
+            - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an
+              md5 hash under the C(checksum) return value.
+        type: bool
+        default: 'no'
     get_checksum:
         description:
             - Whether to return a checksum of the file (default sha1)
-        required: no
-        default: True
+        type: bool
+        default: 'yes'
         version_added: "2.1"
     checksum_algorithm:
         description:
             - Algorithm to determine checksum of file. Will throw an error if
               the host is unable to use specified algorithm.
-        required: no
         default: sha1
         choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512']
         version_added: "2.3"
 notes:
      - For non-Windows targets, use the M(stat) module instead.
-author: "Chris Church (@cchurch)"
+author:
+- Chris Church (@cchurch)
 '''
 
 EXAMPLES = r'''
@@ -200,8 +201,8 @@ stat:
             type: string
             sample: C:\temp
         md5:
-            description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.7
-            returned: success, path exist, path is a file, get_md5 == True, md5 is supported
+            description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9
+            returned: success, path exist, path is a file, get_md5 == True
             type: string
             sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
         owner: