Standardize verb usage within the module

[HowardWolosky]

Description

This attempts to rectify some improper verb usage in the module
based on the explanations of intended verb usage from previous
PowerShell documentation.

• 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.

Issues Fixed

None

References

PowerShell documentation on verb usage

Checklist

• You actually ran the code that you just wrote, especially if you did just "one last quick change".
• Comment-based help added/updated, including examples.
• Static analysis
  is reporting back clean.
• New/changed code adheres to our coding guidelines.
• Changes to the manifest file follow the manifest guidance.
• Unit tests were added/updated and are all passing. See testing guidelines.
• Relevant usage examples have been added/updated in USAGE.md.
• If desired, ensure your name is added to our Contributors list

[HowardWolosky]

Definitely interested in hearing thoughts on this:
/cc: @X-Guardian, @rjmholt, @TylerLeonhardt, et. al

[HowardWolosky]

/azp run PowerShellForGitHub-CI

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[TylerLeonhardt]

What's the difference between Restore-GitHubLabel and Set-GitHubLabel now?

[HowardWolosky]

What's the difference between Restore-GitHubLabel and Set-GitHubLabel now?

Currently in master:
Update-GitHubLabel allowed you to modify an existing label in a repo (changing its name, color and/or description).

PowerShellForGitHub/GitHubLabels.ps1

Lines 381 to 385 in 742b853

	function Update-GitHubLabel
	{
	<#
	.SYNOPSIS
	Updates an existing label on a given GitHub repository.

while Set-GitHubLabel will take in an array of labels and either create them if there isn't an existing label with that name, or change the color of the label based on the value in the label if it does exist. It will also remove any labels that are in the repo but not in the array.

PowerShellForGitHub/GitHubLabels.ps1

Lines 502 to 507 in 742b853

	function Set-GitHubLabel
	{
	<#
	.SYNOPSIS
	Sets the entire set of Labels on the given GitHub repository to match the provided list
	of Labels.

The functionality as described in Set-GitHubLabel is what v0.1.0 of the module used to do before I took it over. In v0.1.0 it had been called New-GitHubLabels. I kept it around (although renamed) to help with the migration from any existing 0.1.0 users.

With this change, Set-GitHubLabel now will modify the properties of an individual label, and Restore-GitHubLabel will be what restores the state of the repository's labels to be what is described by the array of labels.

[X-Guardian]

Definitely agree with Set-* instead of Update-*. Not too sure about Restore-GitHubLabel, how about Initialize-GitHubLabel?

[HowardWolosky]

Definitely agree with Set-* instead of Update-*. Not too sure about Restore-GitHubLabel, how about Initialize-GitHubLabel?

Initialize-GitHubLabel also makes sense to me. I'll leave this open for another day to see if there's any further feedback before making that change and merging it in.

[X-Guardian]

I've just seen New-GitHubAssignee - 'Adds a list of assignees to a Github Issue for the given repository.' Surely that should be Add-GitHubAssignee?

[HowardWolosky]

I've just seen New-GitHubAssignee - 'Adds a list of assignees to a Github Issue for the given repository.' Surely that should be Add-GitHubAssignee?

Interesting observation. I could see making that change (and aliasing it back to New-GitHubAssignee to minimize the breaking change impact right now).

Thinking out loud now:
It's hard to tell though how far to take that. New-GitHubProjectColumn for instance....we are creating a new column, but what we're actually doing is adding a new column to an existing project. So...do we Add- it or New- it? I think it's still New....from that link:

Add - Adds a resource to a container, or attaches an item to another item.
New - The New verb is used to create a new resource.

The way that I read that, Add is for making use of existing resources (like an existing user who will now be an assignee) and New is for creating a new resource which may just happen to be assigned to something at the same time (like a ProjectColumn or ProjectCard).

So, given all that, I think that of all the remaining New-* methods, New-GitHubAssignee is the only one that is actually just referencing an existing resource without creating an additional one, so that's the only one to change.

Thanks for bringing this up.

[HowardWolosky]

/azp run PowerShellForGitHub-CI

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[HowardWolosky]

/azp run PowerShellForGitHub-CI

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[TylerLeonhardt]

If you ever wanted to get all the verb descriptions, you can just run Get-Verb 😄

[HowardWolosky]

If you ever wanted to get all the verb descriptions, you can just run Get-Verb 😄

Nope. That only tells you the Name and Grouping. It doesn't give additional context/description of its expected usage. That link I referenced earlier was the first time I found a good explanation regarding the intended usage of the different verbs.

[rjmholt]

I think our documentation got moved and the Approved Verbs page (which itself was a reconstruction of the archived page you linked @HowardWolosky) lost its search engine rank. It's now at https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands.

Possibly Get-Verb has version-specific output? (EDIT: Confirmed, added in 6)

Output on my machine in PS 7.1.0-preview.3:

> get-verb

Verb        AliasPrefix Group          Description
----        ----------- -----          -----------
Add         a           Common         Adds a resource to a container, or attaches an item to anothe…
Clear       cl          Common         Removes all the resources from a container but does not delet…
Close       cs          Common         Changes the state of a resource to make it inaccessible, unav…
Copy        cp          Common         Copies a resource to another name or to another container
Enter       et          Common         Specifies an action that allows the user to move into a resou…
Exit        ex          Common         Sets the current environment or context to the most recently …
Find        fd          Common         Looks for an object in a container that is unknown, implied, …
Format      f           Common         Arranges objects in a specified form or layout
Get         g           Common         Specifies an action that retrieves a resource
Hide        h           Common         Makes a resource undetectable
Join        j           Common         Combines resources into one resource
Lock        lk          Common         Secures a resource
Move        m           Common         Moves a resource from one location to another
New         n           Common         Creates a resource
Open        op          Common         Changes the state of a resource to make it accessible, availa…
Optimize    om          Common         Increases the effectiveness of a resource
Push        pu          Common         Adds an item to the top of a stack
Pop         pop         Common         Removes an item from the top of a stack
Redo        re          Common         Resets a resource to the state that was undone
Remove      r           Common         Deletes a resource from a container
Rename      rn          Common         Changes the name of a resource
Reset       rs          Common         Sets a resource back to its original state
Resize      rz          Common         Changes the size of a resource
Search      sr          Common         Creates a reference to a resource in a container
Select      sc          Common         Locates a resource in a container
Set         s           Common         Replaces data on an existing resource or creates a resource t…
Show        sh          Common         Makes a resource visible to the user
Skip        sk          Common         Bypasses one or more resources or points in a sequence
Split       sl          Common         Separates parts of a resource
Step        st          Common         Moves to the next point or resource in a sequence
Switch      sw          Common         Specifies an action that alternates between two resources, su…
Undo        un          Common         Sets a resource to its previous state
Unlock      uk          Common         Releases a resource that was locked
Watch       wc          Common         Continually inspects or monitors a resource for changes
Connect     cc          Communications Creates a link between a source and a destination
Disconnect  dc          Communications Breaks the link between a source and a destination
Read        rd          Communications Acquires information from a source
Receive     rc          Communications Accepts information sent from a source
Send        sd          Communications Delivers information to a destination
Write       wr          Communications Adds information to a target
Backup      ba          Data           Stores data by replicating it
Checkpoint  ch          Data           Creates a snapshot of the current state of the data or of its…
Compare     cr          Data           Evaluates the data from one resource against the data from an…
Compress    cm          Data           Compacts the data of a resource
Convert     cv          Data           Changes the data from one representation to another when the …
ConvertFrom cf          Data           Converts one primary type of input (the cmdlet noun indicates…
ConvertTo   ct          Data           Converts from one or more types of input to a primary output …
Dismount    dm          Data           Detaches a named entity from a location
Edit        ed          Data           Modifies existing data by adding or removing content
Expand      en          Data           Restores the data of a resource that has been compressed to i…
Export      ep          Data           Encapsulates the primary input into a persistent data store, …
Group       gp          Data           Arranges or associates one or more resources
Import      ip          Data           Creates a resource from data that is stored in a persistent d…
Initialize  in          Data           Prepares a resource for use, and sets it to a default state
Limit       l           Data           Applies constraints to a resource
Merge       mg          Data           Creates a single resource from multiple resources
Mount       mt          Data           Attaches a named entity to a location
Out         o           Data           Sends data out of the environment
Publish     pb          Data           Makes a resource available to others
Restore     rr          Data           Sets a resource to a predefined state, such as a state set by…
Save        sv          Data           Preserves data to avoid loss
Sync        sy          Data           Assures that two or more resources are in the same state
Unpublish   ub          Data           Makes a resource unavailable to others
Update      ud          Data           Brings a resource up-to-date to maintain its state, accuracy,…
Debug       db          Diagnostic     Examines a resource to diagnose operational problems
Measure     ms          Diagnostic     Identifies resources that are consumed by a specified operati…
Ping        pi          Diagnostic     Use the Test verb
Repair      rp          Diagnostic     Restores a resource to a usable condition
Resolve     rv          Diagnostic     Maps a shorthand representation of a resource to a more compl…
Test        t           Diagnostic     Verifies the operation or consistency of a resource
Trace       tr          Diagnostic     Tracks the activities of a resource
Approve     ap          Lifecycle      Confirms or agrees to the status of a resource or process
Assert      as          Lifecycle      Affirms the state of a resource
Build       bd          Lifecycle      Creates an artifact (usually a binary or document) out of som…
Complete    cmp         Lifecycle      Concludes an operation
Confirm     cn          Lifecycle      Acknowledges, verifies, or validates the state of a resource …
Deny        dn          Lifecycle      Refuses, objects, blocks, or opposes the state of a resource …
Deploy      dp          Lifecycle      Sends an application, website, or solution to a remote target…
Disable     d           Lifecycle      Configures a resource to an unavailable or inactive state
Enable      e           Lifecycle      Configures a resource to an available or active state
Install     is          Lifecycle      Places a resource in a location, and optionally initializes it
Invoke      i           Lifecycle      Performs an action, such as running a command or a method
Register    rg          Lifecycle      Creates an entry for a resource in a repository such as a dat…
Request     rq          Lifecycle      Asks for a resource or asks for permissions
Restart     rt          Lifecycle      Stops an operation and then starts it again
Resume      ru          Lifecycle      Starts an operation that has been suspended
Start       sa          Lifecycle      Initiates an operation
Stop        sp          Lifecycle      Discontinues an activity
Submit      sb          Lifecycle      Presents a resource for approval
Suspend     ss          Lifecycle      Pauses an activity
Uninstall   us          Lifecycle      Removes a resource from an indicated location
Unregister  ur          Lifecycle      Removes the entry for a resource from a repository
Wait        w           Lifecycle      Pauses an operation until a specified event occurs
Use         u           Other          Uses or includes a resource to do something
Block       bl          Security       Restricts access to a resource
Grant       gr          Security       Allows access to a resource
Protect     pt          Security       Safeguards a resource from attack or loss
Revoke      rk          Security       Specifies an action that does not allow access to a resource
Unblock     ul          Security       Removes restrictions to a resource
Unprotect   up          Security       Removes safeguards from a resource that were added to prevent…

[HowardWolosky]

Ah, indeed. I had been running Get-Verb on PS 5. I've been running 5 and 7 concurrently for the past couple weeks, but I still tend to default back to PS5. I do see Description when running it on PS7 -- much more helpful.

[HowardWolosky]

I'll be merging this change in later tonight pending any further feedback.

[TylerLeonhardt]

What about Switch?

Specifies an action that alternates between two resources, such as to change between two locations, responsibilities, or states

or Redo?

Resets a resource to the state that was undone

or Use?

Uses or includes a resource to do something

[HowardWolosky]

I appreciate the suggestions there, but none of those resonate.

Switch - Of your suggestions, I think this was the closest, but still I don't think it's as clear as Initialize.

Redo - implies that there was a previous state, but there isn't necessarily a previous label state for a repo

Use - We're not using the labels to do something...we're changing them.

[rjmholt]

I don't want to blow the question out here, but what are the two API endpoints the different functions hit?

If they really have to be different commands with different verbs, I would say:

• Update -> Edit (that's the approved replacement for Update) since it "Modifies existing data by adding or removing content."
• Set stays the same, since it "Replaces data on an existing resource or creates a resource that contains some data"

[HowardWolosky]

The endpoints are identical. Initialize is an old, historical wrapper/helper function that existed before I took the module over. It calls Get to get the current set of labels. Then it loops through the input array, either adding labels (New) if they didn't already exist or updating (Set) the colors for labels that already existed, and then deleting (Remove) any labels that were previously there but not in the new array.

The functionality doesn't match that of any GitHub provided endpoint...it's just a helper function that had been created by the previous owner. I'm just trying to name it correctly.

I wanted to avoid changing over to Edit, because then I'd be changing every Set call over to Edit since they all work similarly which would be a really big breaking change unless I aliased-back to Set-* as well. I figured I'd standardize on Get/Set/New/Remove, as that all felt rather natural and was mostly what we were already doing. I'll mull over if I should do the change Edit and alias back to Set. I definitely can't migrate to Edit without the alias right now.

[HowardWolosky]

/azp run PowerShellForGitHub-CI

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[HowardWolosky]

/azp run PowerShellForGitHub-CI

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).