René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"What is the right way to implement deprecation in PowerShell?","articleBody":"Follow-up from https://github.com/PowerShell/PowerShell/issues/11662#issuecomment-577861216:\r\n\r\n### Context:\r\n\r\nNote: _Deprecation_ in the context of PowerShell is _always_ \"soft\" deprecation in the sense that, given the commitment to backward compatibility, features are never _removed_, so that old code _continues to function_. Instead, deprecation means _discouraging use_ of a given feature, for various reasons: having been superseded by a superior alternative, general obsoleteness, security concerns.\r\n\r\nDeprecation can be implemented in the following, potentially complementary ways:\r\n\r\n* _Documentation_ warnings: Clearly state that a given cmdlet / one of its parameters is deprecated and should not be used in new code.\r\n\r\n* _Design-time_ warnings: Implement a PSScriptAnalyzer (PSSA) warning that is ideally also surfaced in Visual Studio Code, via the PowerShell extension's integrated PowerShell Editor Services (PSES).  \r\nThis is currently mostly _not_ implemented (see details below).\r\n\r\n* _Runtime_ warnings:\r\nCurrently, a warning (to stream `3`) is emitted when a deprecated feature is called.\r\n\r\nThe latter are currently implemented by a _repurposing_ of the general [`System.ObsoleteAttribute`](https://docs.microsoft.com/en-US/dotnet/api/System.ObsoleteAttribute) attribute, whose purpose is to provide _compile-time_ warnings (and optionally _errors_) about obsolete features: given that PowerShell code isn't compiled, the PowerShell engine explicitly surfaces `Obsolete` attributes on _cmdlets_ or their _parameters_ (but seemingly not SDK classes with the attribute) with a PowerShell warning _at runtime_.\r\n\r\nExamples of features currently deprecated this way are `Send-MailMessage` and the `-Raw` parameter of the `Format-Hex`  cmdlet; e.g.:\r\n\r\n```powershell\r\nPS\u003e 'foo' | Format-Hex -Raw\r\nWARNING: Parameter 'Raw' is obsolete. Raw parameter is deprecated.\r\n... # regular output\r\n```\r\n\r\n`3\u003e$null`  or `-WarningAction Ignore` can be used to suppress the warning, but old code written pre-deprecation _will_  show the warning.\r\n\r\nAs an aside: The combination of the boilerplate part of the warning (`Parameter 'Raw' is obsolete`) with the attribute-specific message (`Raw parameter is deprecated`) could use some revising.\r\n\r\n----\r\n\r\n### Relevant questions are:\r\n\r\n* Should deprecation be signaled _at runtime_ at all?\r\n  * If so, is the current approach the right one?\r\n\r\n* Is it sufficient to warn at _design time_, knowing that not every user will see those warnings, given that they may use an editor other than Visual Studio Code and not install and routinely run `Invoke-ScriptAnalyzer` after installing the [`PSScriptAnalyzer`](https://www.powershellgallery.com/packages/PSScriptAnalyzer/) module?\r\n\r\n  * As of this writing, PSSA (warning) rules seems to comprise just _one_ relating to one specific deprecated feature, [`AvoidUsingDeprecatedManifestFields`](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/AvoidUsingDeprecatedManifestFields.md), whereas several more deprecated features exist - full list of rules is [here](https://github.com/PowerShell/PSScriptAnalyzer/tree/master/RuleDocumentation).\r\n\r\n  * Perhaps a more promising approach is to let PSSA directly surface `Obsolete` attributes encountered in code, if technically feasible.","author":{"url":"https://github.com/mklement0","@type":"Person","name":"mklement0"},"datePublished":"2020-01-24T16:11:23.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":48},"url":"https://github.com/11674/PowerShell/issues/11674"}