Powershell: Add DevOps relevant verbs to approved verb list

[HemantMahawar]

https://windowsserver.uservoice.com/forums/301869-powershell/suggestions/12303924-add-a-compile-verb

NEW Verbs:

• Build

[joeyaiello]

I think we also talked about Deploy, right?

[SteveL-MSFT]

@joeyaiello @HemantMahawar These would be under Lifecycle, correct? Give me a description of Build and Deploy

[dragonwolf83]

Deploy seems to already have a comparable Lifecycle verb, Install. Based on the existing description below, I would think Install would be the more appropriate verb.

Install (is)
Places a resource in a location, and optionally initializes it. This verb is paired with Uninstall.
For this action, do not a use verb such as Setup.

If you have a Deploy, you also need a Rollback verb. Install and Uninstall both already cover those concepts quite well.

On the other hand, you could change the Install language to say it is intended for local resources while Deploy is used for remote resources.

For Build, I think in software dev it makes more sense than any other verb. The guidance for New though should be updated to remove Build from the list of "do not use" verbs.

[SteveL-MSFT]

@joeyaiello will write up descriptions of the verbs: build and deploy

[joeyaiello]

Here's a first pass, can I get a review from @SteveL-MSFT, @HemantMahawar, and @BrucePay ?

Build

Creates an artifact (usually a binary or ) out of some set of input files (usually source code or declarative documents). For PowerShell's purposes this may include the "linking" step of a compilation process.

Comments: do not use Compile

Deploy

Sends an application, website, or solution to a remote target[s] in such a way that a consumer of that solution can access it after deployment is complete. This differs from Install because it sends this application to a remote target (or targets) to be installed whereas Install targets a local instance. This differs from Publish because Deploy is used for the application lifecycle rather than data or content.

[RichardSiddaway]

I think you also need Rollback to complete the set - Similar argument that Uninstall is local while Rollback is remote - also rollback has the connotation of setting the state back to the point before the deployment.
Deploy/Rollback then tend to function almost as a transaction

[ArieHein]

Although PS likes verbs to have a "positive" and "negative" effects ,I dont think RollBack is necessary the way forwards, in quite a few DevOps pipelines, Rollback is simple a Deploy -Version "last working one", which you can also say that Uninstall is basically Install -U or Install -Action U so while I can understand Install/Uninstall being the English language, RollBack isn't necessary the opposite of Deploy.
Its kind of like the Verb Set, you set a value to a paramaeter, we dont have a UnSet verb, you just Set it to a new value which underneath implies there was an unset.

Hope this makes sense somewhat :)

[SteveL-MSFT]

@HemantMahawar can you comment on RollBack verb?

[dragonwolf83]

The trick of keeping standard verbs and buzzwords..... Playing Devil's Advocate here.

I just remembered that there is also a Publish and Unpublish verb-set.

Makes a resource available to others. This verb is paired with Unpublish.
For this action, do not use verbs such as Deploy, Release, or Install.

Publish is used in Visual Studio instead of Deploy for some of the built-in deployment option. So between Install, Deploy, and Publish you have major overlaps of similar concepts. Is it really worth muddling the waters more? I'm assuming its because of the DevOps push and to be more generally accepted driving this. With better guidance, it can be made to work though.

Thinking in terms of Deploy itself. Does it make sense in the context of a Cmdlet vs a Script? When is it better to have a Deploy verb vs a Deploy script with no need for an approved verb? Deployments often are a series of commands (hopefully cmdlets) that do a Build | Copy | Register | Update-SqlSchema | Update-SqlData. Should I wrap that into a Deploy cmdlet or would I have a Deploy script that did all of the actions needed? Does wrapping that many things into a single cmdlet go with the original principles of doing one thing well?

@ArieHein For simple deployments, yes, a Deploy -Version works, I also wonder why you would be using Deploy in that case and not just Copy-Item. Build -Version | Copy -Destination. More complex deployments change the state of the machine or data. In those scenarios, you might have to run unregister/uninstall commands, restore database commands, etc. While you could do that with a -Rollback parameter, that goes against the idea of the Verb-Noun concept in PowerShell and doing one thing well.

Food for thought. I would love to see more feedback on how people are planning to use these verbs and if it makes the most sense to have Deploy/Rollback Cmdlets over a Deploy Script. Personally, I've been doing larger tasks like that as scripts and using Cmdlets to build up re-usable tasks.

[ArieHein]

By Copy-Item you assume file shares / ports are open between source and target.
Deploy might be the ability to set the transfer method and then do it.
Publish on the other hand is packaging to smaller size to then transfer to the destination.
VS actually uses Build and Release.
Didnt say I'm a fan of Deploy, was just commenting that if Deploy is to be used, not sure RollBack is the right verb.

[dragonwolf83]

I was referring to ASP.NET and SQL Server Data Tools. They both use Publish to indicate you are pushing a build to a web/database server. You can see an example on MSDN.

[SteveL-MSFT]

@joeyaiello thoughts on the RollBack verb?

[joeyaiello]

Yeah, we should probably bring in @grayzu on this, he'll have stronger opinions than me on Deploy vs. Publish and Rollback or no.

[grayzu]

Let me start by saying that I agree with @dragonwolf83 (nice alias btw). From a DevOps perspective these verbs would typically be used for a script vs a single cmdlet where multiple tasks, steps, things would be done during build or deploy. What that means from an approved verb perspective I will leave up to @joeyaiello, @HemantMahawar & co.

As far as Deploy vs Install goes, I see Deploy as more than just a remote vs local thing. Deployments will typically consist of a number of different actions such as configuration, installation, etc. against a number of different targets. For example deploying a web application consists of copying bits, opening ports, configuring IIS, etc. I think the unique thing with deployments vs installations is that deployments will configure components that are not "Owned" by the component being deployed. So I do think that deploy make sense as an additional verb and is different than install.

I agree with @ArieHein points on a Rollback verb. Rollback in a DevOps is typically just another Deployment with the previous configuration. If a component does do an actual rollback where the system is reverted to the previous state, not just applying old config, then the verb would make sense.

[SteveL-MSFT]

@PowerShell/powershell-committee reviewed this and agree on Build and Deploy, however, don't believe there is a need to have Rollback. For Rollback usage, our recommendation is (other than Deploy a different config) use -Rollback switch to Deploy or use the Repair verb.

[iSazonov]

@SteveL-MSFT Should we change the Issue label?

[joeyaiello]

I changed the definition of Deploy up above, that's what we decided to go with.

[joeyaiello]

And I think we agreed both Build and Deploy should be in the Lifecycle group.

[SteveL-MSFT]

@joeyaiello the short versions of the descriptions are only effectively comments in the code as VerbInfo type today doesn't have a description property (we should probably fix in the future; created https://github.com/PowerShell/PowerShell/issues/4732). The actual descriptions you put should be in https://github.com/PowerShell/PowerShell-Docs/issues/1630