Merge pull request #2643 from AdmiringWorm/2641-Mark-Chocolatey-shims-chocolatey-cinst-clist-cpush-cuninst-cup-are-deprecated

(#2641) Add deprecation messages for shims

Author: gep13

GenerateDocs.ps1

@@ -1,4 +1,5 @@
-# Copyright © 2017 Chocolatey Software, Inc
+#Requires -PSEdition Desktop
+# Copyright © 2017 Chocolatey Software, Inc
 # Copyright © 2011 - 2017 RealDimensions Software, LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -206,7 +207,7 @@ param(
     return
   }
   $commandText = $commandText -creplace '^(.+)(\s+Command\s*)$', "# `$1`$2 (choco $commandName)"
-  $commandText = $commandText -creplace '^(Usage|Troubleshooting|Examples|Exit Codes|Connecting to Chocolatey.org|See It In Action|Alternative Sources|Resources|Packages.config|Scripting \/ Integration - Best Practices \/ Style Guide)', '## $1'
+  $commandText = $commandText -creplace '^(DEPRECATION NOTICE|Usage|Troubleshooting|Examples|Exit Codes|Connecting to Chocolatey.org|See It In Action|Alternative Sources|Resources|Packages.config|Scripting \/ Integration - Best Practices \/ Style Guide)', '## $1'
   $commandText = $commandText -replace '^(Commands|How To Pass Options)', '## $1'
   $commandText = $commandText -replace '^(WebPI|Windows Features|Ruby|Cygwin|Python)\s*$', '### $1'
   $commandText = $commandText -replace 'NOTE\:', '> :memo: **NOTE**'
@@ -351,6 +352,23 @@ function Generate-CommandReference($commandName, $order) {
 
   $commandOutput += @("---$lineFeed")
   $commandOutput += @("<!-- This file is automatically generated based on output from $($sourceCommands)/Chocolatey$($commandName)Command.cs using $($sourceLocation)GenerateDocs.ps1. Contributions are welcome at the original location(s). If the file is not found, it is not part of the open source edition of Chocolatey or the name of the file is different. --> $lineFeed")
+
+  $commandOutput += @(@"
+> :memo: **WARNING** SHIM DEPRECATION
+>
+> In version 1.0.0 of Chocolatey Open Source we have deprecated the following shims/shortcuts:
+>
+> - `chocolatey` (Alias for `choco`)
+> - `cinst` (Shortcut for `choco install`)
+> - `cpush` (Shortcut for `choco push`)
+> - `cuninst` (Shortcut for `cuninst`)
+> - `cup` (Shortcut for `choco upgrade`)
+>
+> We recommend that any scripts calling these shims be updated to use the full command, as
+> these shims will be removed in Chocolatey v2.0.0.
+
+"@)
+
   $commandOutput += $(& $chocoExe $commandName.ToLower() -h -r)
   $commandOutput += @("$lineFeed~~~$lineFeed$lineFeed[Command Reference](xref:choco-commands)")
   $commandOutput += @("$lineFeed$lineFeed*NOTE:* This documentation has been automatically generated from ``choco $($commandName.ToLower()) -h``. $lineFeed")

nuget/chocolatey/tools/chocolateysetup.psm1

@@ -314,6 +314,7 @@ param(
 
     $from = "$chocolateyPathOld\bin"
     $to = "$chocolateyPath\bin"
+    # TODO: This exclusion list needs to be updated once shims are removed
     $exclude = @("choco.exe", "chocolatey.exe", "cinst.exe", "clist.exe", "cpack.exe", "cpush.exe", "cuninst.exe", "cup.exe", "cver.exe", "RefreshEnv.cmd")
     Get-ChildItem -Path $from -recurse -Exclude $exclude |
       % {

src/chocolatey/infrastructure.app/commands/ChocolateyHelpCommand.cs

@@ -93,6 +93,13 @@ public static void display_help_message(Container container = null)
             }
 
             "chocolatey".Log().Info(@"This is a listing of all of the different things you can pass to choco.
+");
+
+            "chocolatey".Log().Warn(ChocolateyLoggers.Important, "DEPRECATION NOTICE");
+            "chocolatey".Log().Warn(@"
+The shims `chocolatey`, `cinst`, `clist`, `cpush`, `cuninst` and `cup` are deprecated.
+We recommend updating all scripts to use their full command equivalent as these will be
+removed in v2.0.0 of Chocolatey.
 ");
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Options and Switches");
 
@@ -160,7 +167,8 @@ Following this guide will ensure your experience is not frustrating
 based on choco not receiving things you think you are passing to it.
 
  * For consistency, always use `choco`, not `choco.exe`. Never use
-   shortcut commands like `cinst` or `cup`.
+   shortcut commands like `cinst` or `cup` (The shortcuts `cinst`
+   and `cup` will be removed in v2.0.0).
  * Always have the command as the first argument to `choco`. e.g.
    `choco install`, where `install` is the command.
  * If there is a subcommand, ensure that is the second argument. e.g.

src/chocolatey/infrastructure.app/commands/ChocolateyInstallCommand.cs

@@ -23,7 +23,6 @@ namespace chocolatey.infrastructure.app.commands
     using commandline;
     using configuration;
     using infrastructure.commands;
-    using infrastructure.configuration;
     using logging;
     using services;
 
@@ -238,19 +237,25 @@ public virtual void help_message(ChocolateyConfiguration configuration)
             this.Log().Info(ChocolateyLoggers.Important, "Install Command");
             this.Log().Info(@"
 Installs a package or a list of packages (sometimes specified as a
- packages.config). Some may prefer to use `cinst` as a shortcut for
- `choco install`.
+ packages.config).
 
 NOTE: 100% compatible with older chocolatey client (0.9.8.32 and below)
  with options and switches. Add `-y` for previous behavior with no
  prompt. In most cases you can still pass options and switches with one
  dash (`-`). For more details, see the command reference (`choco -?`).
 ");
 
+            "chocolatey".Log().Warn(ChocolateyLoggers.Important, "DEPRECATION NOTICE");
+            "chocolatey".Log().Warn(@"
+Starting in v2.0.0 the shortcut `cinst` will be removed and can not be used
+to install packages anymore. We recommend you make sure that you always
+use the full command going forward (`choco install`).
+");
+
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
             "chocolatey".Log().Info(@"
     choco install <pkg|packages.config> [<pkg2> <pkgN>] [<options/switches>]
-    cinst <pkg|packages.config> [<pkg2> <pkgN>] [<options/switches>]
+    cinst <pkg|packages.config> [<pkg2> <pkgN>] [<options/switches>] (DEPRECATED, will be removed in v2.0.0)
 
 NOTE: `all` is a special package keyword that will allow you to install
  all packages from a custom feed. Will not work with Chocolatey default

src/chocolatey/infrastructure.app/commands/ChocolateyListCommand.cs

@@ -1,4 +1,4 @@
-// Copyright © 2017 - 2021 Chocolatey Software, Inc
+// Copyright © 2017 - 2021 Chocolatey Software, Inc
 // Copyright © 2011 - 2017 RealDimensions Software, LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -28,7 +28,7 @@ namespace chocolatey.infrastructure.app.commands
     using services;
 
     [CommandFor("list", "lists remote or local packages")]
-    [CommandFor("search", "searches remote or local packages (alias for list)")]
+    [CommandFor("search", "searches remote or local packages")]
     [CommandFor("find", "searches remote or local packages (alias for search)")]
     public class ChocolateyListCommand : IListCommand<PackageResult>
     {
@@ -166,6 +166,16 @@ and switches  with one dash (`-`). For more details, see
  the command reference (`choco -?`).
 ");
 
+            "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
+            // TODO: use command name in usage and examples, instead of hard
+            // coding the names?
+            "chocolatey".Log().Info(@"
+    choco find <filter> [<options/switches>]
+    choco list <filter> [<options/switches>]
+    choco search <filter> [<options/switches>]
+    clist <filter> [<options/switches>] (DEPRECATED, will be removed in v2.0.0)
+");
+
             if (configuration.CommandName.is_equal_to("list"))
             {
                 "chocolatey".Log().Warn(ChocolateyLoggers.Important, "DEPRECATION NOTICE");
@@ -177,18 +187,12 @@ Starting in v2.0.0 the list command will be made local only and will only
 
 To avoid breakage, change any calls made to remote sources to use `choco search`
  or `choco find` instead. These will continue to work as usual.
-");
-            }
 
-            "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
-            // TODO: use command name in usage and examples, instead of hard
-            // coding the names?
-            "chocolatey".Log().Info(@"
-    choco find <filter> [<options/switches>]
-    choco list <filter> [<options/switches>]
-    choco search <filter> [<options/switches>]
-    clist <filter> [<options/switches>]
+Starting in v2.0.0 the shortcut `clist` will be removed and can not be used
+ to list package anymore. We recommend you make sure that you always
+ use the full command going forward (`choco list`).
 ");
+            }
 
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Examples");
             "chocolatey".Log().Info(@"

src/chocolatey/infrastructure.app/commands/ChocolateyPushCommand.cs

@@ -114,7 +114,6 @@ public virtual void help_message(ChocolateyConfiguration configuration)
             this.Log().Info(ChocolateyLoggers.Important, "Push Command");
             this.Log().Info(@"
 Chocolatey will attempt to push a compiled nupkg to a package feed.
- Some may prefer to use `cpush` as a shortcut for `choco push`.
 
 NOTE: 100% compatible with older chocolatey client (0.9.8.32 and below)
  with options and switches. In most cases you can still pass options and 
@@ -132,12 +131,16 @@ the command reference (`choco -?`).
 Default push location is deprecated and will be removed by v2.0.0.
 It is recommended to always specify the source you want to push to
 using the `--source` argument.
+
+Starting in v2.0.0 the shortcut `cpush` will be removed and can not be used
+to push packages anymore. We recommend you make sure that you always
+use the full command going forward (`choco push`).
 ");
 
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
             "chocolatey".Log().Info(@"
     choco push [<path to nupkg>] [<options/switches>]
-    cpush [<path to nupkg>] [<options/switches>]
+    cpush [<path to nupkg>] [<options/switches>] (DEPRECATED, will be removed in v2.0.0)
 
 NOTE: If there is more than one nupkg file in the folder, the command
  will require specifying the path to the file.

src/chocolatey/infrastructure.app/commands/ChocolateyUninstallCommand.cs

@@ -154,8 +154,7 @@ public virtual void help_message(ChocolateyConfiguration configuration)
         {
             this.Log().Info(ChocolateyLoggers.Important, "Uninstall Command");
             this.Log().Info(@"
-Uninstalls a package or a list of packages. Some may prefer to use
- `cuninst` as a shortcut for `choco uninstall`.
+Uninstalls a package or a list of packages.
 
 NOTE: 100% compatible with older chocolatey client (0.9.8.32 and below)
  with options and switches. Add `-y` for previous behavior with no
@@ -204,10 +203,17 @@ and licensed enhancements have the ability to inspect more locations
  to determine how to automatically uninstall software.
 ");
 
+            "chocolatey".Log().Warn(ChocolateyLoggers.Important, "DEPRECATION NOTICE");
+            "chocolatey".Log().Warn(@"
+Starting in v2.0.0 the shortcut `cuninst` will be removed and can not be used
+to uninstall packages anymore. We recommend you make sure that you always
+use the full command going forward (`choco uninstall`).
+");
+
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
             "chocolatey".Log().Info(@"
     choco uninstall <pkg|all> [pkg2 pkgN] [options/switches]
-    cuninst <pkg|all> [pkg2 pkgN] [options/switches]
+    cuninst <pkg|all> [pkg2 pkgN] [options/switches] (DEPRECATED, will be removed in v2.0.0)
 
 NOTE: `all` is a special package keyword that will allow you to
  uninstall all packages.

src/chocolatey/infrastructure.app/commands/ChocolateyUpgradeCommand.cs

@@ -1,4 +1,4 @@
-// Copyright © 2017 - 2021 Chocolatey Software, Inc
+// Copyright © 2017 - 2021 Chocolatey Software, Inc
 // Copyright © 2011 - 2017 RealDimensions Software, LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -267,8 +267,7 @@ public virtual void help_message(ChocolateyConfiguration configuration)
         {
             this.Log().Info(ChocolateyLoggers.Important, "Upgrade Command");
             this.Log().Info(@"
-Upgrades a package or a list of packages. Some may prefer to use `cup`
- as a shortcut for `choco upgrade`. If you do not have a package
+Upgrades a package or a list of packages. If you do not have a package
  installed, upgrade will install it.
 
 NOTE: 100% compatible with older Chocolatey client (0.9.8.x and below)
@@ -277,10 +276,17 @@ prompt. In most cases you can still pass options and switches with one
  dash (`-`). For more details, see the command reference (`choco -?`).
 ");
 
+            "chocolatey".Log().Warn(ChocolateyLoggers.Important, "DEPRECATION NOTICE");
+            "chocolatey".Log().Warn(@"
+Starting in v2.0.0 the shortcut `cup` will be removed and can not be used
+to upgrade or install packages anymore. We recommend you make sure that you always
+use the full command going forward (`choco upgrade`).
+");
+
             "chocolatey".Log().Info(ChocolateyLoggers.Important, "Usage");
             "chocolatey".Log().Info(@"
     choco upgrade <pkg|all> [<pkg2> <pkgN>] [<options/switches>]
-    cup <pkg|all> [<pkg2> <pkgN>] [<options/switches>]
+    cup <pkg|all> [<pkg2> <pkgN>] [<options/switches>] (DEPRECATED, will be removed in v2.0.0)
 
 NOTE: `all` is a special package keyword that will allow you to upgrade
  all currently installed packages.