Powershell: Need info on getting a verb added

[sharpninja]

Summary of the new feature/enhancement

I was directed to create this from https://github.com/MicrosoftDocs/PowerShell-Docs/issues/6278.

We need a link to somewhere we can request having a verb added to the approved list. This link needs to be added to:
|
Document Details
⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

ID: 5c285b90-bf7e-60c8-2eef-3ba0a57e06cb
Version Independent ID: 19b205d5-c044-389c-f887-946123130034
Content: Get-Verb (Microsoft.PowerShell.Utility) - PowerShell
Content Source: reference/6/Microsoft.PowerShell.Utility/Get-Verb.md
Product: powershell
Technology: powershell-cmdlets
GitHub Login: @JamesWTruher
Microsoft Alias: jimtru

Proposed technical implementation details (optional)

[SeeminglyScience]

This is the place to suggest a new approved verb. What's the verb? Ideally also include a pitch for why it is needed and why none of the existing verbs fit.

[sharpninja]

New (n) | Creates a resource. (The Set verb can also be used when creating a resource that includes data, such as the Set-Variable cmdlet.) | For this action, do not use verbs such as Create, Generate, Build, Make, or Allocate.

[sharpninja]

First, I think Build or Compile are needed. Much of what we do as developers centers around these activities and the New verb is not semantically accurate.

|Verb (alias) |Action |Comments
|---|---|---
New (n) | Creates a resource. (The Set verb can also be used when creating a resource that includes data, such as the Set-Variable cmdlet.) | For this action, do not use verbs such as Create, Generate, Build, Make, or Allocate.

I create scripts to compile code in various ways all the time. Naming the script or function Compile-Xxx is much more accurate and user friendly than New-Xxx.

Transform is another verb that deserves to be added. Mutate is another that would be helpful.

[vexx32]

Build is already an approved verb:

PS /Users/joelfrancis> get-verb build

Verb  AliasPrefix Group     Description
----  ----------- -----     -----------
Build bd          Lifecycle Creates an artifact (usually a binary or document) out of some set of input files (usually…

Transform and Mutate are synonyms of one another in at least one usage, if not more. Going off the patterns of the existing approved verbs, I don't think both would be permissible.

Is there a reason the Convert / ConvertTo / ConvertFrom verbs don't serve the purpose you're looking for with Transform / Mutate?

[sharpninja]

https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7 does not list Build as an approved verb.

I think Transform is more readable by general audiences, so I would lean towards that. To me, Convert means you are only changing format of the data, not changing the data itself. Transform, and especially Mutate, imply the output has been processed in someway to be different from the input. An example is populating a template from a dataset.

Approved Verbs for PowerShell Commands - PowerShell

[vexx32]

Build shows under Lifecycle verbs for me.

---

Hmm. To me, that usage of Transform feels like it may already be covered by verbs like Import, Initialize, or Merge?

[SeeminglyScience]

https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7 does not list Build as an approved verb.

It's there, third one under Lifecycle.

I think Transform is more readable by general audiences, so I would lean towards that. To me, Convert means you are only changing format of the data, not changing the data itself. Transform, and especially Mutate, imply the output has been processed in someway to be different from the input. An example is populating a template from a dataset.

What about Set, Edit or Import?

Approved Verbs for PowerShell Commands - PowerShell

[sharpninja]

It's there, third one under Lifecycle.

Yeah, I see it now.

I think Transform is more readable by general audiences, so I would lean towards that. To me, Convert means you are only changing format of the data, not changing the data itself. Transform, and especially Mutate, imply the output has been processed in someway to be different from the input. An example is populating a template from a dataset.

What about Set, Edit or Import?

Set would be the closest. To me, Edit has the connotation of human interaction and Import means bring in something verbatim. May the solution is:

| Verb | Meaning
|---|---
|Set| Put a value into a container verbatim.
|SetFrom| Override a value with a newly calculated one.
|'SetTo| Set a new value by calculating from an existing one.

# So, to populate some templates, you would have:
foreach($data in $dataset) {
    SetTo-Template -Name 'TempX' -Values $data `
        | Set-Contents $filename+$data[0];
}

# To parse a template to a set
foreach($template in templates) {
    $dataset+= ($template | SetFrom-Template -Name 'TempX');
}

Edit: Swapped the meaning of SetTo and SetFrom after looking at my example. This feels better. But, it really shows that using better verbs such as Populate and Parse would be better. (Neither currently exist).

PS C:\> Get-Verb populate
PS C:\> Get-Verb parse
PS C:\>