BREAKING CHANGE: Add confirmation prompts and examples for Remove- fu…

…nctions (#174) Updates all Remove-* functions to set `ConfirmImpact='High'`, wraps the execution in `$PSCmdlet.ShouldProcess()`, and adds examples which show how to call the functions with `-Confirm:$false` to avoid the confirmation prompt. ## Breaking Change This will be considered a breaking change for anyone using this module in an automated, scripted basis and calling any Remove-* methods. They will need to add `-Confirm:$false` to those API calls, similar to what was done for the unit tests. Fixes #171
microsoft · Jun 1, 2020 · a6a27aa · a6a27aa
1 parent 21e6139
commit a6a27aa
Show file tree

Hide file tree

Showing 19 changed files with 178 additions and 129 deletions.
diff --git a/GitHubAssignees.ps1 b/GitHubAssignees.ps1
@@ -328,11 +328,16 @@ function Remove-GithubAssignee
         Remove-GithubAssignee -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Assignee $assignees
 
         Lists the available assignees for issues from the Microsoft\PowerShellForGitHub project.
+
+    .EXAMPLE
+        Remove-GithubAssignee -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Assignee $assignees -Confirm:$false
+
+        Lists the available assignees for issues from the Microsoft\PowerShellForGitHub project. Will not prompt for confirmation, as -Confirm:$false was specified.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(ParameterSetName='Elements')]
@@ -374,17 +379,20 @@ function Remove-GithubAssignee
         'assignees' = $Assignee
     }
 
-    $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/issues/$Issue/assignees"
-        'Body' = (ConvertTo-Json -InputObject $hashBody)
-        'Method' = 'Delete'
-        'Description' =  "Removing assignees from issue $Issue for $RepositoryName"
-        'AccessToken' = $AccessToken
-        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+    if ($PSCmdlet.ShouldProcess($Assignee -join ', ', "Remove assignee(s)"))
+    {
+        $params = @{
+            'UriFragment' = "repos/$OwnerName/$RepositoryName/issues/$Issue/assignees"
+            'Body' = (ConvertTo-Json -InputObject $hashBody)
+            'Method' = 'Delete'
+            'Description' =  "Removing assignees from issue $Issue for $RepositoryName"
+            'AccessToken' = $AccessToken
+            'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
+
+        return Invoke-GHRestMethod @params
     }
-
-    return Invoke-GHRestMethod @params
 }
diff --git a/GitHubComments.ps1 b/GitHubComments.ps1
@@ -452,12 +452,17 @@ function Remove-GitHubComment
         Remove-GitHubComment -OwnerName Microsoft -RepositoryName PowerShellForGitHub -CommentID 1
 
         Deletes a Github comment from the Microsoft\PowerShellForGitHub project.
+
+    .EXAMPLE
+        Remove-GitHubComment -OwnerName Microsoft -RepositoryName PowerShellForGitHub -CommentID 1 -Confirm:$false
+
+        Deletes a Github comment from the Microsoft\PowerShellForGitHub project without prompting confirmation.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Alias('Delete-GitHubComment')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(ParameterSetName='Elements')]
@@ -491,16 +496,19 @@ function Remove-GitHubComment
         'CommentID' =  (Get-PiiSafeString -PlainText $CommentID)
     }
 
-    $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/issues/comments/$CommentID"
-        'Method' = 'Delete'
-        'Description' =  "Removing comment $CommentID for $RepositoryName"
-        'AccessToken' = $AccessToken
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
-    }
+    if ($PSCmdlet.ShouldProcess($CommentID, "Remove comment"))
+    {
+        $params = @{
+            'UriFragment' = "repos/$OwnerName/$RepositoryName/issues/comments/$CommentID"
+            'Method' = 'Delete'
+            'Description' =  "Removing comment $CommentID for $RepositoryName"
+            'AccessToken' = $AccessToken
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
 
-    return Invoke-GHRestMethod @params
+        return Invoke-GHRestMethod @params
+    }
 }
 
diff --git a/GitHubLabels.ps1 b/GitHubLabels.ps1
@@ -316,11 +316,16 @@ function Remove-GitHubLabel
         Remove-GitHubLabel -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Name TestLabel
 
         Removes the label called "TestLabel" from the PowerShellForGitHub project.
+
+    .EXAMPLE
+        Remove-GitHubLabel -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Name TestLabel -Confirm:$false
+
+        Removes the label called "TestLabel" from the PowerShellForGitHub project. Will not prompt for confirmation, as -Confirm:$false was specified.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     [Alias('Delete-GitHubLabel')]
     param(
@@ -356,18 +361,21 @@ function Remove-GitHubLabel
         'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
     }
 
-    $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/labels/$Name"
-        'Method' = 'Delete'
-        'Description' =  "Deleting label $Name from $RepositoryName"
-        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
-        'AccessToken' = $AccessToken
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
-    }
+    if ($PSCmdlet.ShouldProcess($Name, "Remove label"))
+    {
+        $params = @{
+            'UriFragment' = "repos/$OwnerName/$RepositoryName/labels/$Name"
+            'Method' = 'Delete'
+            'Description' =  "Deleting label $Name from $RepositoryName"
+            'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+            'AccessToken' = $AccessToken
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
 
-    return Invoke-GHRestMethod @params
+        return Invoke-GHRestMethod @params
+    }
 }
 
 function Update-GitHubLabel
@@ -614,7 +622,7 @@ function Set-GitHubLabel
         if ($labelName -notin $labelNames)
         {
             # Remove label if it exists but is not in desired label list
-            $null = Remove-GitHubLabel -Name $labelName @commonParams
+            $null = Remove-GitHubLabel -Name $labelName @commonParams -Confirm:$false
         }
     }
 }
@@ -865,11 +873,16 @@ function Remove-GitHubIssueLabel
         Remove-GitHubIssueLabel -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Name TestLabel -Issue 1
 
         Removes the label called "TestLabel" from issue 1 in the PowerShellForGitHub project.
+
+    .EXAMPLE
+        Remove-GitHubIssueLabel -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Name TestLabel -Issue 1 -Confirm:$false
+
+        Removes the label called "TestLabel" from issue 1 in the PowerShellForGitHub project. Will not prompt for confirmation, as -Confirm:$false was specified.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Alias('Delete-GitHubLabel')]
     param(
         [Parameter(Mandatory, ParameterSetName='Elements')]
@@ -915,18 +928,21 @@ function Remove-GitHubIssueLabel
         $description = "Deleting all labels from issue $Issue in $RepositoryName"
     }
 
-    $params = @{
-        'UriFragment' = "/repos/$OwnerName/$RepositoryName/issues/$Issue/labels/$Name"
-        'Method' = 'Delete'
-        'Description' =  $description
-        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
-        'AccessToken' = $AccessToken
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
-    }
+    if ($PSCmdlet.ShouldProcess($Name, "Remove label"))
+    {
+        $params = @{
+            'UriFragment' = "/repos/$OwnerName/$RepositoryName/issues/$Issue/labels/$Name"
+            'Method' = 'Delete'
+            'Description' =  $description
+            'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+            'AccessToken' = $AccessToken
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
 
-    return Invoke-GHRestMethod @params
+        return Invoke-GHRestMethod @params
+    }
 }
 
 # A set of labels that a project might want to initially populate their repository with

diff --git a/GitHubMilestones.ps1 b/GitHubMilestones.ps1
@@ -500,12 +500,17 @@ function Remove-GitHubMilestone
         Remove-GitHubMilestone -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Milestone 1
 
         Deletes a Github milestone from the Microsoft\PowerShellForGitHub project.
+
+    .EXAMPLE
+        Remove-GitHubMilestone -OwnerName Microsoft -RepositoryName PowerShellForGitHub -Milestone 1 -Confirm:$false
+
+        Deletes a Github milestone from the Microsoft\PowerShellForGitHub project. Will not prompt for confirmation, as -Confirm:$false was specified.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Alias('Delete-GitHubMilestone')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(Mandatory, ParameterSetName='Elements')]
@@ -538,15 +543,18 @@ function Remove-GitHubMilestone
         'Milestone' =  (Get-PiiSafeString -PlainText $Milestone)
     }
 
-    $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/milestones/$Milestone"
-        'Method' = 'Delete'
-        'Description' =  "Removing milestone $Milestone for $RepositoryName"
-        'AccessToken' = $AccessToken
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
-    }
+    if ($PSCmdlet.ShouldProcess($Milestone, "Remove milestone"))
+    {
+        $params = @{
+            'UriFragment' = "repos/$OwnerName/$RepositoryName/milestones/$Milestone"
+            'Method' = 'Delete'
+            'Description' =  "Removing milestone $Milestone for $RepositoryName"
+            'AccessToken' = $AccessToken
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
 
-    return Invoke-GHRestMethod @params
+        return Invoke-GHRestMethod @params
+    }
 }
diff --git a/GitHubProjectCards.ps1 b/GitHubProjectCards.ps1
@@ -370,7 +370,6 @@ function Remove-GitHubProjectCard
         SupportsShouldProcess,
         ConfirmImpact = 'High')]
     [Alias('Delete-GitHubProjectCard')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification = "Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(Mandatory)]

diff --git a/GitHubProjectColumns.ps1 b/GitHubProjectColumns.ps1
@@ -266,7 +266,6 @@ function Remove-GitHubProjectColumn
         SupportsShouldProcess,
         ConfirmImpact = 'High')]
     [Alias('Delete-GitHubProjectColumn')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification = "Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(Mandatory)]

diff --git a/GitHubProjects.ps1 b/GitHubProjects.ps1
@@ -465,6 +465,11 @@ function Remove-GitHubProject
 
         Remove project with ID '4387531'.
 
+    .EXAMPLE
+        Remove-GitHubProject -Project 4387531 -Confirm:$false
+
+        Remove project with ID '4387531' without prompting for confirmation.
+
     .EXAMPLE
         $project = Get-GitHubProject -OwnerName Microsoft -RepositoryName PowerShellForGitHub | Where-Object Name -eq 'TestProject'
         Remove-GitHubProject -Project $project.id
@@ -476,7 +481,6 @@ function Remove-GitHubProject
         SupportsShouldProcess,
         ConfirmImpact = 'High')]
     [Alias('Delete-GitHubProject')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification = "Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "", Justification="One or more parameters (like NoStatus) are only referenced by helper methods which get access to it from the stack via Get-Variable -Scope 1.")]
     param(
         [Parameter(Mandatory)]

diff --git a/GitHubRepositories.ps1 b/GitHubRepositories.ps1
@@ -217,12 +217,17 @@ function Remove-GitHubRepository
 
     .EXAMPLE
         Remove-GitHubRepository -Uri https://github.com/You/YourRepoToDelete
+
+    .EXAMPLE
+        Remove-GitHubRepository -Uri https://github.com/You/YourRepoToDelete -Confirm:$false
+
+        Remove repository with the given URI, without prompting for confirmation.
 #>
     [CmdletBinding(
         SupportsShouldProcess,
-        DefaultParameterSetName='Elements')]
+        DefaultParameterSetName='Elements',
+        ConfirmImpact="High")]
     [Alias('Delete-GitHubRepository')]
-    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     param(
         [Parameter(ParameterSetName='Elements')]
         [string] $OwnerName,
@@ -250,18 +255,20 @@ function Remove-GitHubRepository
         'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
         'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
     }
+    if ($PSCmdlet.ShouldProcess($RepositoryName, "Remove repository"))
+    {
+        $params = @{
+            'UriFragment' = "repos/$OwnerName/$RepositoryName"
+            'Method' = 'Delete'
+            'Description' =  "Deleting $RepositoryName"
+            'AccessToken' = $AccessToken
+            'TelemetryEventName' = $MyInvocation.MyCommand.Name
+            'TelemetryProperties' = $telemetryProperties
+            'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+        }
 
-    $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName"
-        'Method' = 'Delete'
-        'Description' =  "Deleting $RepositoryName"
-        'AccessToken' = $AccessToken
-        'TelemetryEventName' = $MyInvocation.MyCommand.Name
-        'TelemetryProperties' = $telemetryProperties
-        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+        return Invoke-GHRestMethod @params
     }
-
-    return Invoke-GHRestMethod @params
 }
 
 function Get-GitHubRepository