Standardize verb usage within the module (#228)

This attempts to rectify some improper verb usage in the module based on the explanations of intended verb usage from [previous PowerShell documentation](https://web.archive.org/web/20171222220053/https://msdn.microsoft.com/en-us/library/windows/desktop/ms714428(v=vs.85).aspx). * We're standardizing on the following pattern for most object actions: `Get` / `Set` / `New` / `Remove` * We will continue to alias `Remove-*` as `Delete-*`. * When possible, this change attempts to avoid breaking changes by re-aliasing the newly named functions with their previous names. This was not possible in one instance, hence this is still a breaking change (although based on telemetry, it should be minimally impacting). Result: * `Update-GitHubCurrentUser` -> `Set-GitHubProfile` `[Alias('Update-GitHubCurrentUser')]` * `Update-GitHubIssue` -> `Set-GitHubIssue` `[Alias('Update-GitHubIssue')]` * `Update-GitHubRepository` -> `Set-GitHubRepository` `[Alias('Update-GitHubRepository')]` * `New-GitHubAssignee` -> `Add-GitHubAssignee` `[Alias('New-GitHubAssignee')]` * [breaking] `Update-GitHubLabel` -> `Set-GitHubLabel` `[Alias('Update-GitHubLabel')]` * [breaking] `Set-GitHubLabel` -> `Initialize-GitHubLabel` `<no alias due to above>` Changing an existing label has much more regular usage than replacing all of the labels in a repository, hence allowing the _new_ `Set-GitHubLabel` to keep the alias of `Update-GitHubLabel`. Our usage of the `Set-*` verb in general is a bit arguable based on the documentation ... in theory `Edit-*` might be a better fit since we're _editing_ aspects of an object as opposed to _replacing_ the entire content of an object. However, I think `Set-*` _feels_ ok in this module. We're _setting_ the state of these objects. Again...arguable, but this is a much smaller breaking change to get to a consistent terminology state.
microsoft · Jun 29, 2020 · e57a956 · e57a956
1 parent d32bd11
commit e57a956
Show file tree

Hide file tree

Showing 13 changed files with 105 additions and 100 deletions.
diff --git a/GitHubAssignees.ps1 b/GitHubAssignees.ps1
@@ -247,7 +247,7 @@ filter Test-GitHubAssignee
     }
 }
 
-function New-GitHubAssignee
+function Add-GitHubAssignee
 {
 <#
     .DESCRIPTION
@@ -308,15 +308,15 @@ function New-GitHubAssignee
 
     .EXAMPLE
         $assignees = @('octocat')
-        New-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1 -Assignee $assignee
+        Add-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1 -Assignee $assignee
 
         Additionally assigns the usernames in $assignee to Issue #1
         from the microsoft\PowerShellForGitHub project.
 
     .EXAMPLE
         $assignees = @('octocat')
         $repo = Get-GitHubRepository -OwnerName microsoft -RepositoryName PowerShellForGitHub
-        $repo | New-GitHubAssignee -Issue 1 -Assignee $assignee
+        $repo | Add-GitHubAssignee -Issue 1 -Assignee $assignee
 
         Additionally assigns the usernames in $assignee to Issue #1
         from the microsoft\PowerShellForGitHub project.
@@ -325,14 +325,14 @@ function New-GitHubAssignee
         $assignees = @('octocat')
         Get-GitHubRepository -OwnerName microsoft -RepositoryName PowerShellForGitHub |
             Get-GitHubIssue -Issue 1 |
-            New-GitHubAssignee -Assignee $assignee
+            Add-GitHubAssignee -Assignee $assignee
 
         Additionally assigns the usernames in $assignee to Issue #1
         from the microsoft\PowerShellForGitHub project.
 
     .EXAMPLE
         $octocat = Get-GitHubUser -UserName 'octocat'
-        $octocat | New-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1
+        $octocat | Add-GitHubAssignee -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 1
 
         Additionally assigns the user 'octocat' to Issue #1
         from the microsoft\PowerShellForGitHub project.
@@ -341,6 +341,7 @@ function New-GitHubAssignee
         SupportsShouldProcess,
         DefaultParameterSetName='Elements')]
     [OutputType({$script:GitHubIssueTypeName})]
+    [Alias('New-GitHubAssignee')] # Non-standard usage of the New verb, but done to avoid a breaking change post 0.14.0
     [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(

diff --git a/GitHubIssues.ps1 b/GitHubIssues.ps1
@@ -654,14 +654,14 @@ filter New-GitHubIssue
     return (Invoke-GHRestMethod @params | Add-GitHubIssueAdditionalProperties)
 }
 
-filter Update-GitHubIssue
+filter Set-GitHubIssue
 {
 <#
     .SYNOPSIS
-        Create a new Issue on GitHub.
+        Updates an Issue on GitHub.
 
     .DESCRIPTION
-        Create a new Issue on GitHub.
+        Updates an Issue on GitHub.
 
         The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
 
@@ -744,12 +744,13 @@ filter Update-GitHubIssue
         GitHub.Issue
 
     .EXAMPLE
-        Update-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 4 -Title 'Test Issue' -State Closed
+        Set-GitHubIssue -OwnerName microsoft -RepositoryName PowerShellForGitHub -Issue 4 -Title 'Test Issue' -State Closed
 #>
     [CmdletBinding(
         SupportsShouldProcess,
         DefaultParameterSetName='Elements')]
     [OutputType({$script:GitHubIssueTypeName})]
+    [Alias('Update-GitHubIssue')] # Non-standard usage of the Update verb, but done to avoid a breaking change post 0.14.0
     [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')]

diff --git a/GitHubLabels.ps1 b/GitHubLabels.ps1
@@ -486,7 +486,7 @@ filter Remove-GitHubLabel
     }
 }
 
-filter Update-GitHubLabel
+filter Set-GitHubLabel
 {
 <#
     .SYNOPSIS
@@ -555,7 +555,7 @@ filter Update-GitHubLabel
         GitHub.Label
 
     .EXAMPLE
-        Update-GitHubLabel -OwnerName microsoft -RepositoryName PowerShellForGitHub -Label TestLabel -NewName NewTestLabel -Color BBBB00
+        Set-GitHubLabel  -OwnerName microsoft -RepositoryName PowerShellForGitHub -Label TestLabel -NewName NewTestLabel -Color BBBB00
 
         Updates the existing label called TestLabel in the PowerShellForGitHub project to be called
         'NewTestLabel' and be colored yellow.
@@ -564,6 +564,7 @@ filter Update-GitHubLabel
         SupportsShouldProcess,
         DefaultParameterSetName='Elements')]
     [OutputType({$script:GitHubLabelTypeName})]
+    [Alias('Update-GitHubLabel')] # Non-standard usage of the Update verb, but done to avoid a breaking change post 0.14.0
     [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')]
@@ -637,15 +638,15 @@ filter Update-GitHubLabel
     return (Invoke-GHRestMethod @params | Add-GitHubLabelAdditionalProperties)
 }
 
-filter Set-GitHubLabel
+filter Initialize-GitHubLabel
 {
 <#
     .SYNOPSIS
-        Sets the entire set of Labels on the given GitHub repository to match the provided list
+        Replaces the entire set of Labels on the given GitHub repository to match the provided list
         of Labels.
 
     .DESCRIPTION
-        Sets the entire set of Labels on the given GitHub repository to match the provided list
+        Replaces the entire set of Labels on the given GitHub repository to match the provided list
         of Labels.
 
         Will update the color/description for any Labels already in the repository that match the
@@ -697,7 +698,7 @@ filter Set-GitHubLabel
         GitHub.Repository
 
     .EXAMPLE
-        Set-GitHubLabel -OwnerName microsoft -RepositoryName PowerShellForGitHub -Label @(@{'name' = 'TestLabel'; 'color' = 'EEEEEE'}, @{'name' = 'critical'; 'color' = 'FF000000'; 'description' = 'Needs immediate attention'})
+        Initialize-GitHubLabel -OwnerName microsoft -RepositoryName PowerShellForGitHub -Label @(@{'name' = 'TestLabel'; 'color' = 'EEEEEE'}, @{'name' = 'critical'; 'color' = 'FF000000'; 'description' = 'Needs immediate attention'})
 
         Removes any labels not in this Label array, ensure the current assigned color and descriptions
         match what's in the array for the labels that do already exist, and then creates new labels
@@ -769,7 +770,7 @@ filter Set-GitHubLabel
         else
         {
             # Update label's color if it already exists
-            $null = Update-GitHubLabel -Label $labelToConfigure.name -NewName $labelToConfigure.name -Color $labelToConfigure.color @commonParams
+            $null = Set-GitHubLabel -Label $labelToConfigure.name -NewName $labelToConfigure.name -Color $labelToConfigure.color @commonParams
         }
     }
 

diff --git a/GitHubRepositories.ps1 b/GitHubRepositories.ps1
@@ -1015,11 +1015,11 @@ filter Rename-GitHubRepository
     )
 
     # This method was created by mistake and is now retained to avoid a breaking change.
-    # Update-GitHubRepository is able to handle this scenario just fine.
-    return Update-GitHubRepository @PSBoundParameters
+    # Set-GitHubRepository is able to handle this scenario just fine.
+    return Set-GitHubRepository @PSBoundParameters
 }
 
-filter Update-GitHubRepository
+filter Set-GitHubRepository
 {
 <#
     .SYNOPSIS
@@ -1125,18 +1125,18 @@ filter Update-GitHubRepository
         GitHub.Repository
 
     .EXAMPLE
-        Update-GitHubRepository -OwnerName microsoft -RepositoryName PowerShellForGitHub -Description 'The best way to automate your GitHub interactions'
+        Set-GitHubRepository -OwnerName microsoft -RepositoryName PowerShellForGitHub -Description 'The best way to automate your GitHub interactions'
 
         Changes the description of the specified repository.
 
     .EXAMPLE
-        Update-GitHubRepository -Uri https://github.com/PowerShell/PowerShellForGitHub -Private:$false
+        Set-GitHubRepository -Uri https://github.com/PowerShell/PowerShellForGitHub -Private:$false
 
         Changes the visibility of the specified repository to be public.
 
     .EXAMPLE
         Get-GitHubRepository -Uri https://github.com/PowerShell/PowerShellForGitHub |
-            Update-GitHubRepository -NewName 'PoShForGitHub' -Force
+            Set-GitHubRepository -NewName 'PoShForGitHub' -Force
 
         Renames the repository without any user confirmation prompting.  This is identical to using
         Rename-GitHubRepository -Uri https://github.com/PowerShell/PowerShellForGitHub -NewName 'PoShForGitHub' -Confirm:$false
@@ -1146,6 +1146,7 @@ filter Update-GitHubRepository
         DefaultParameterSetName='Elements',
         ConfirmImpact='High')]
     [OutputType({$script:GitHubRepositoryTypeName})]
+    [Alias('Update-GitHubRepository')] # Non-standard usage of the Update verb, but done to avoid a breaking change post 0.14.0
     [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')]

diff --git a/GitHubUsers.ps1 b/GitHubUsers.ps1
@@ -300,14 +300,14 @@ filter Get-GitHubUserContextualInformation
     return $result
 }
 
-function Update-GitHubCurrentUser
+function Set-GitHubProfile
 {
 <#
     .SYNOPSIS
-        Updates information about the current authenticated user on GitHub.
+        Updates profile information for the current authenticated user on GitHub.
 
     .DESCRIPTION
-        Updates information about the current authenticated user on GitHub.
+        Updates profile information for the current authenticated user on GitHub.
 
         The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
 
@@ -347,13 +347,14 @@ function Update-GitHubCurrentUser
         GitHub.User
 
     .EXAMPLE
-        Update-GitHubCurrentUser -Location 'Seattle, WA' -Hireable:$false
+        Set-GitHubProfile -Location 'Seattle, WA' -Hireable:$false
 
         Updates the current user to indicate that their location is "Seattle, WA" and that they
         are not currently hireable.
 #>
     [CmdletBinding(SupportsShouldProcess)]
     [OutputType({$script:GitHubUserTypeName})]
+    [Alias('Update-GitHubCurrentUser')] # Non-standard usage of the Update verb, but done to avoid a breaking change post 0.14.0
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
     param(
         [string] $Name,

diff --git a/PowerShellForGitHub.psd1 b/PowerShellForGitHub.psd1
@@ -55,6 +55,7 @@
 
     # Functions to export from this module
     FunctionsToExport = @(
+        'Add-GitHubAssignee',
         'Add-GitHubIssueLabel',
         'Backup-GitHubConfiguration',
         'Clear-GitHubAuthentication',
@@ -102,14 +103,14 @@
         'Get-GitHubViewTraffic',
         'Group-GitHubIssue',
         'Group-GitHubPullRequest',
+        'Initialize-GitHubLabel',
         'Invoke-GHRestMethod',
         'Invoke-GHRestMethodMultipleResult',
         'Join-GitHubUri',
         'Lock-GitHubIssue',
         'Move-GitHubProjectCard',
         'Move-GitHubProjectColumn',
         'Move-GitHubRepositoryOwnership',
-        'New-GitHubAssignee',
         'New-GitHubIssue',
         'New-GitHubIssueComment',
         'New-GitHubLabel',
@@ -136,24 +137,23 @@
         'Set-GitHubAuthentication',
         'Set-GitHubConfiguration',
         'Set-GitHubContent',
+        'Set-GitHubIssue',
         'Set-GitHubIssueComment',
         'Set-GitHubIssueLabel',
         'Set-GitHubLabel',
         'Set-GitHubMilestone',
+        'Set-GitHubProfile',
         'Set-GitHubProject',
         'Set-GitHubProjectCard',
         'Set-GitHubProjectColumn',
+        'Set-GitHubRepository'
         'Set-GitHubRepositoryTopic',
         'Split-GitHubUri',
         'Test-GitHubAssignee',
         'Test-GitHubAuthenticationConfigured',
         'Test-GitHubOrganizationMember',
         'Test-GitHubRepositoryVulnerabilityAlert',
-        'Unlock-GitHubIssue',
-        'Update-GitHubCurrentUser',
-        'Update-GitHubIssue',
-        'Update-GitHubLabel',
-        'Update-GitHubRepository'
+        'Unlock-GitHubIssue'
     )
 
     AliasesToExport = @(
@@ -167,10 +167,15 @@
         'Delete-GitHubRepository',
         'Get-GitHubBranch',
         'Get-GitHubComment',
+        'New-GitHubAssignee',
         'New-GitHubComment',
         'Remove-GitHubComment',
         'Set-GitHubComment',
         'Transfer-GitHubRepositoryOwnership'
+        'Update-GitHubIssue',
+        'Update-GitHubLabel',
+        'Update-GitHubCurrentUser',
+        'Update-GitHubRepository'
     )
 
     # Cmdlets to export from this module

diff --git a/Tests/GitHubAssignees.tests.ps1 b/Tests/GitHubAssignees.tests.ps1
@@ -112,7 +112,7 @@ try
                 $issue.assignees | Should -BeNullOrEmpty
             }
 
-            $updatedIssue = New-GitHubAssignee -OwnerName $script:ownerName -RepositoryName $repo.name -Issue $issue.number -Assignee $owner.login
+            $updatedIssue = Add-GitHubAssignee -OwnerName $script:ownerName -RepositoryName $repo.name -Issue $issue.number -Assignee $owner.login
             It 'Should have returned the same issue' {
                 $updatedIssue.number | Should -Be $issue.number
             }
@@ -149,7 +149,7 @@ try
                 $issue.assignees | Should -BeNullOrEmpty
             }
 
-            $updatedIssue = $repo | New-GitHubAssignee -Issue $issue.number -Assignee $owner.login
+            $updatedIssue = $repo | Add-GitHubAssignee -Issue $issue.number -Assignee $owner.login
             It 'Should have returned the same issue' {
                 $updatedIssue.number | Should -Be $issue.number
             }
@@ -186,7 +186,7 @@ try
                 $issue.assignees | Should -BeNullOrEmpty
             }
 
-            $updatedIssue = $issue | New-GitHubAssignee -Assignee $owner.login
+            $updatedIssue = $issue | Add-GitHubAssignee -Assignee $owner.login
             It 'Should have returned the same issue' {
                 $updatedIssue.number | Should -Be $issue.number
             }
@@ -223,7 +223,7 @@ try
                 $issue.assignees | Should -BeNullOrEmpty
             }
 
-            $updatedIssue = $owner | New-GitHubAssignee -OwnerName $script:ownerName -RepositoryName $repo.name -Issue $issue.number
+            $updatedIssue = $owner | Add-GitHubAssignee -OwnerName $script:ownerName -RepositoryName $repo.name -Issue $issue.number
             It 'Should have returned the same issue' {
                 $updatedIssue.number | Should -Be $issue.number
             }

diff --git a/Tests/GitHubEvents.tests.ps1 b/Tests/GitHubEvents.tests.ps1
@@ -45,7 +45,7 @@ try
 
         Context 'For getting Issue events from a repository' {
             $issue = $repo | New-GitHubIssue -Title 'New Issue'
-            $issue = $issue | Update-GitHubIssue -State Closed
+            $issue = $issue | Set-GitHubIssue -State Closed
             $events = @($repo | Get-GitHubEvent)
 
             It 'Should have an event from closing an issue' {
@@ -82,8 +82,8 @@ try
         }
 
         Context 'For getting events from an issue' {
-            $issue = $issue | Update-GitHubIssue -State Closed
-            $issue = $issue | Update-GitHubIssue -State Open
+            $issue = $issue | Set-GitHubIssue -State Closed
+            $issue = $issue | Set-GitHubIssue -State Open
             $events = @(Get-GitHubEvent -OwnerName $ownerName -RepositoryName $repositoryName)
 
             It 'Should have two events from closing and opening the issue' {
@@ -98,8 +98,8 @@ try
             $repositoryName = [Guid]::NewGuid()
             $repo = New-GitHubRepository -RepositoryName $repositoryName
             $issue = $repo | New-GitHubIssue -Title 'New Issue'
-            $issue = $issue | Update-GitHubIssue -State Closed
-            $issue = $issue | Update-GitHubIssue -State Open
+            $issue = $issue | Set-GitHubIssue -State Closed
+            $issue = $issue | Set-GitHubIssue -State Open
             $events = @($repo | Get-GitHubEvent)
         }