bug#62750: 29.0.50; Commands 'package-update' and 'package-update-all' should be called '*-upgrade'

[Dmitry Gutov <dmitry@gutov.dev>]

[-- Attachment #1: Type: text/plain, Size: 1236 bytes --]

On 15/04/2023 04:34, Dmitry Gutov wrote:
> On 12/04/2023 16:34, Stefan Monnier wrote:
>>>> I hadn't realized that `package-update` hasn't been in a release 
>>>> yet, so
>>>> we don't need such a compatibility alias.
>>> Even though these commands were available under those names for the
>>> last year or so?
>> Well, that's for you to judge 😄
> 
> Since they're not very likely to be used in Lisp code, I'd say it's 
> unlikely to be a problem.
> 
> Alternatively, we'll probably get around to fixing this inconsistency 
> sometime after this release, and then carry the compatibility aliases 
> for a number of years.

Here's a couple of other existing functions:

   package--update-selected-packages
   package--update-downloads-in-progress

Neither of these relate to upgrading packages. Although the former could 
be easy to mistake for that now.

In all older functions, the term "update" (in comments and variable 
names) refers to updating the value of some variable, not packages.

By analogy, 'M-x package-update-all' might be easy enough to mistake for 
updating the list of packages available for installation, for example.

Here's a patch that does the rename. Also including package-vc-update* 
that Philip mentioned.

[-- Attachment #2: 0001-Rename-all-functions-called-package-update-to-packag.patch --]
[-- Type: text/x-patch, Size: 8537 bytes --]

From 13ff1f26da07f7302e898638ef4a5341c2913948 Mon Sep 17 00:00:00 2001
From: Dmitry Gutov <dmitry@gutov.dev>
Date: Mon, 24 Apr 2023 02:00:54 +0300
Subject: [PATCH] Rename all functions called package-*-update-* to
 package-*-upgrade-*

* lisp/emacs-lisp/package-vc.el (package-vc-upgrade-all):
Rename from 'package-vc-update-all'.
(package-vc-upgrade): Rename from 'package-vc-update'.

* lisp/emacs-lisp/package.el (package-upgrade):
Rename from 'package-update' (bug#62750).
(package--upgradeable-packages):
Rename from 'package--updateable-packages'.
(package-upgrade-all): Rename from 'package-update-all'.
---
 doc/emacs/package.texi        | 14 +++++++-------
 etc/NEWS                      |  6 +++---
 lisp/emacs-lisp/package-vc.el | 18 +++++++++---------
 lisp/emacs-lisp/package.el    | 34 +++++++++++++++++-----------------
 4 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 2b03399b0a7..d1766026db2 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -329,15 +329,15 @@ Package Installation
 @section Package Installation
 
 @findex package-install
-@findex package-update
-@findex package-update-all
+@findex package-upgrade
+@findex package-upgrade-all
   Packages are most conveniently installed using the package menu
 (@pxref{Package Menu}), but you can also use the command @kbd{M-x
 package-install}.  This prompts for the name of a package with the
 @samp{available} status, then downloads and installs it.  Similarly,
-if you want to update a package, you can use the @kbd{M-x
-package-update} command, and if you just want to update all the
-packages, you can use the @kbd{M-x package-update-all} command.
+if you want to upgrade a package, you can use the @kbd{M-x
+package-upgrade} command, and if you want to upgrade all the packages,
+you can use the @kbd{M-x package-upgrade-all} command.
 
 @cindex package requirements
   A package may @dfn{require} certain other packages to be installed,
@@ -551,8 +551,8 @@ Fetching Package Sources
 source code for a package directly from source.  The command will also
 automatically ensure that all files are byte-compiled and auto-loaded,
 just like with a regular package.  Packages installed this way behave
-just like any other package.  You can update them using
-@code{package-update} or @code{package-update-all} and delete them
+just like any other package.  You can upgrade them using
+@code{package-upgrade} or @code{package-upgrade-all} and delete them
 again using @code{package-delete}.  They are even displayed in the
 regular package listing.  If you just wish to clone the source of a
 package, without adding it to the package list, use
diff --git a/etc/NEWS b/etc/NEWS
index 1822ff17265..b6c9d9012b6 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1828,13 +1828,13 @@ this includes "binary" buffers like 'archive-mode' and 'image-mode'.
 ** Package
 
 +++
-*** New command 'package-update'.
+*** New command 'package-upgrade'.
 This command allows you to upgrade packages without using 'M-x
 list-packages'.
 
 +++
-*** New command 'package-update-all'.
-This command allows updating all packages without any queries.
+*** New command 'package-upgrade-all'.
+This command allows upgrading all packages without any queries.
 
 +++
 *** New commands 'package-recompile' and 'package-recompile-all'.
diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
index af57095f8ce..fa9fce24acc 100644
--- a/lisp/emacs-lisp/package-vc.el
+++ b/lisp/emacs-lisp/package-vc.el
@@ -24,7 +24,7 @@
 
 ;; While packages managed by package.el use tarballs for distributing
 ;; the source code, this extension allows for packages to be fetched
-;; and updated directly from a version control system.
+;; and upgraded directly from a version control system.
 ;;
 ;; To install a package from source use `package-vc-install'.  If you
 ;; aren't interested in activating a package, you can use
@@ -660,19 +660,19 @@ package-vc--read-package-desc
                #'string=)))
 
 ;;;###autoload
-(defun package-vc-update-all ()
-  "Attempt to update all installed VC packages."
+(defun package-vc-upgrade-all ()
+  "Attempt to upgrade all installed VC packages."
   (interactive)
   (dolist (package package-alist)
     (dolist (pkg-desc (cdr package))
       (when (package-vc-p pkg-desc)
-        (package-vc-update pkg-desc))))
-  (message "Done updating packages."))
+        (package-vc-upgrade pkg-desc))))
+  (message "Done upgrading packages."))
 
 ;;;###autoload
-(defun package-vc-update (pkg-desc)
-  "Attempt to update the package PKG-DESC."
-  (interactive (list (package-vc--read-package-desc "Update VC package: " t)))
+(defun package-vc-upgrade (pkg-desc)
+  "Attempt to upgrade the package PKG-DESC."
+  (interactive (list (package-vc--read-package-desc "Upgrade VC package: " t)))
   ;; HACK: To run `package-vc--unpack-1' after checking out the new
   ;; revision, we insert a hook into `vc-post-command-functions', and
   ;; remove it right after it ran.  To avoid running the hook multiple
@@ -870,7 +870,7 @@ package-vc-rebuild
 cookies, re-compiling Emacs Lisp files, building and installing
 any documentation, downloading any missing dependencies.  This
 command does not fetch new revisions from a remote server.  That
-is the responsibility of `package-vc-update'.  Interactively,
+is the responsibility of `package-vc-upgrade'.  Interactively,
 prompt for the name of the package to rebuild."
   (interactive (list (package-vc--read-package-desc "Rebuild package: " t)))
   (package-vc--unpack-1 pkg-desc (package-desc-dir pkg-desc)))
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index ffa6272dd1f..e15536c9f50 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2263,24 +2263,24 @@ package-install
           (message  "Package `%s' installed." name))
       (message "`%s' is already installed" name))))
 
-(declare-function package-vc-update "package-vc" (pkg))
+(declare-function package-vc-upgrade "package-vc" (pkg))
 
 ;;;###autoload
-(defun package-update (name)
-  "Update package NAME if a newer version exists."
+(defun package-upgrade (name)
+  "Upgrade package NAME if a newer version exists."
   (interactive
    (list (completing-read
-          "Update package: " (package--updateable-packages) nil t)))
+          "Upgrade package: " (package--upgradeable-packages) nil t)))
   (let* ((package (if (symbolp name)
                       name
                     (intern name)))
          (pkg-desc (cadr (assq package package-alist))))
     (if (package-vc-p pkg-desc)
-        (package-vc-update pkg-desc)
+        (package-vc-upgrade pkg-desc)
       (package-delete pkg-desc 'force)
       (package-install package 'dont-select))))
 
-(defun package--updateable-packages ()
+(defun package--upgradeable-packages ()
   ;; Initialize the package system to get the list of package
   ;; symbols for completion.
   (package--archives-initialize)
@@ -2298,23 +2298,23 @@ package--updateable-packages
     package-alist)))
 
 ;;;###autoload
-(defun package-update-all (&optional query)
+(defun package-upgrade-all (&optional query)
   "Refresh package list and upgrade all packages.
-If QUERY, ask the user before updating packages.  When called
+If QUERY, ask the user before upgrading packages.  When called
 interactively, QUERY is always true."
   (interactive (list (not noninteractive)))
   (package-refresh-contents)
-  (let ((updateable (package--updateable-packages)))
-    (if (not updateable)
-        (message "No packages to update")
+  (let ((upgradeable (package--upgradeable-packages)))
+    (if (not upgradeable)
+        (message "No packages to upgrade")
       (when (and query
                  (not (yes-or-no-p
-                       (if (length= updateable 1)
-                           "One package to update.  Do it? "
-                         (format "%s packages to update.  Do it?"
-                                 (length updateable))))))
-        (user-error "Updating aborted"))
-      (mapc #'package-update updateable))))
+                       (if (length= upgradeable 1)
+                           "One package to upgrade.  Do it? "
+                         (format "%s packages to upgrade.  Do it?"
+                                 (length upgradeable))))))
+        (user-error "Upgrade aborted"))
+      (mapc #'package-upgrade upgradeable))))
 
 (defun package--dependencies (pkg)
   "Return a list of all dependencies PKG has.
-- 
2.37.2