May 14th, 2007

RFC: Deprecating Parameters

PowerShell Team
PowerShell Team

Request For Comment

One of our partners asked what the guidance was for a product that releases a cmdlet and then decides that they need to deprecate one or more of the parameters in a future release. We don’t currently have guidance on this topic so I thought I would tell you what we were thinking of saying and then you can comment about whether that is reasonable or not.

Background

The problem is that a bunch of scripts might have been written to use that parameter so if they just drop the parameter in the next release, it will break those scripts.

It’s easy to say, “never drop a parameter” but that isn’t realistic. Things change and teams need the flexibility to adapt.

Proposed Guidance

Avoid dropping parameters whenever possible since doing may break customer scripts.

If you must drop a parameter, do so over the course of a couple of releases. Depreciate it in the next release and then drop it in the release after that.

Deprecate the parameter by:

  1. Documenting this in your release notes.
  2. Add this information to the HELP content for this cmdlet. Put a note under the NOTES section and in the PARAMETER details section.
  3. Modify the implementation of the CMDLET to issue a message on the WARNING channel (WriteWarning()) when the deprecated parameter is used.

Validate that all the data binding scenarios (pipelining) scenarios continue to work property after dropping the parameters.

Note

One possibility is for PowerShell to provide explicit support for this scenario. We could create a DEPECREATED stream and have a DEPRECATED attribute that you could put on your parameters and then we could change the engine to look for this and issue a standardized error message. In the end, this would consume a lot of pm/dev/test calories for a scenario that I really hope doesn’t happens. I’d rather spend those calories on some amazing remoting capabilities so I’m strongly disinclined to go down that path.

What do you think?

Jeffrey Snover [MSFT]
Windows Management Partner Architect
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

Category
PowerShell

Author

PowerShell Team
PowerShell Team

PowerShell is a task-based command-line shell and scripting language built on .NET. PowerShell helps system administrators and power-users rapidly automate tasks that manage operating systems (Linux, macOS, and Windows) and processes.

1 comment

Discussion is closed. Login to edit/delete existing comments.