[elpa] elpa-admin 0b84023: * elpa-admin.el: Fix confusing uses of word "external"

[Stefan Monnier]

branch: elpa-admin
commit 0b8402335c316ac86c8ba429a342cfc78b4c9c69
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    * elpa-admin.el: Fix confusing uses of word "external"
    
    (elpaa--branch-prefix, elpaa--release-branch-prefix):
    Use "elpa" instead of "external".
    (elpaa--specs-file): Change name to "elpa-packages".
    (elpaa--get-specs): Use `elpaa--specs-file`, as intended.
    (elpaa--worktree-sync): Rename from `elpaa--external-package-sync`.
    (elpaa-add/remove/update-worktrees): Rename from
    `elpaa-add/remove/update-externals`.
    (elpaa-batch-archive-update-worktrees): Use `:url` instead of `:external`.
    (elpaa--branch): Don't hardcode "master".
    (elpaa--urtb): Use our own name for the remote tracking branch instead
    of using the name used in the upstream repository.  Use "main" for the
    the main (development) branch.
    (elpaa--fetch, elpaa--push): Same, and use "release" to track the
    release branch.
    
    * GNUmakefile (worktrees): New target name to replace "externals".
    
    * README, README.org: Update old uses of "external".
---
 GNUmakefile   |  6 +++---
 README        | 49 +++++++++++++++++++++++------------------------
 README.org    |  8 ++++----
 elpa-admin.el | 61 +++++++++++++++++++++++++++++------------------------------
 4 files changed, 61 insertions(+), 63 deletions(-)

diff --git a/GNUmakefile b/GNUmakefile
index 04a4ea6..ca2f120 100644
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -203,10 +203,10 @@ sync-all:
 
 ############### Rules to prepare the externals ################################
 
-.PHONY:
-externals:
+.PHONY: externals worktrees
+externals worktrees:   # "externals" is the old name we used to use.
        $(EMACS) -l admin/elpa-admin.el \
-           -f elpaa-add/remove/update-externals
+           -f elpaa-add/remove/update-worktrees
 
 
 ################### Testing ###############
diff --git a/README b/README
index 1118fab..cb295c5 100644
--- a/README
+++ b/README
@@ -18,7 +18,7 @@ This code expects to be used in a directory that has the 
following layout:
 
 - =admin/=              -- Directory containing a copy of the here files
 - =GNUmakefile=         -- A copy of or symlink to =admin/GNUmakefile=
-- =externals-list=      -- The specifications of the packages
+- =elpa-packages=       -- The specifications of the packages
 - =copyright_exceptions= -- List of exceptions for the copyright-notices checks
 
 The =copyright_exceptions= file can be absent, in which case copyright notices
@@ -41,14 +41,16 @@ that should be part of the archive.  Each element has the 
form
 
 where NAME is the name of the ELisp package and PLIST is a property list
 giving additional info about that package.  It has to have either
-an =:external= or a =:core= property, all others are optional.
+a =:url= or a =:core= property, all others are optional.
 The properties are the following:
 
-** =:external URL=
+** =:url URL=
+This property has to come first.
 Gives the URL where the upstream Git repository for that package can be found.
 The URL can be =nil= if there is no upstream repository.
 
 ** =:core FILES=
+This property has to come first.
 Indicates that this is a special package which will be built by extracting
 files directly from Emacs's source code.  For this to work, the Emacs
 source code should be available in the =emacs= subdirectory.
@@ -139,15 +141,15 @@ instructions below, but the gist of it is that you:
 2. Push your package's code to its branch on elpa.git with:
 
    #+begin_src shell
-   git push elpa <mybranch>:refs/heads/externals/<pkgname>
+   git push elpa <mybranch>:refs/heads/elpa/<pkgname>
    #+end_src
 
    where =<mybranch>= will probably be =master= for most people.
 
-3. Edit the =externals-list= file to add an entry for =<pkgname>=.
-   It has to have an =:external= property specified but that
+3. Edit the =elpa-packages= file to add an entry for =<pkgname>=.
+   It has to have an =:url= property specified but that
    property can be nil.
-4. =git add externals-list=, =git commit= and =git push=.
+4. =git add elpa-packages=, =git commit= and =git push=.
 
 If you don't have push access to the repository, someone will do steps
 2-4 for you.
@@ -198,9 +200,7 @@ For some examples, see 
[[https://www.gnu.org/software/emacs/manual/html_node/eli
 *** Add a multi-file package as a directory: =packages/<pkg-name>=
 
 It needs to have a file named =packages/<pkg-name>/<pkg-name>.el= which 
follows the
-same rules as above.  Note that if your package is large, we recommend you
-add it as an "external" into its own branch, see below discussion of
-[[External branches][external branches]].
+same rules as above.
 
 It additionally follows the same guidelines described in 
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Multi_002dfile-Packages.html][Multi-File
 Packages]]
 (web link) or in Emacs
@@ -282,16 +282,16 @@ upstream every once in a while.  This copy may include 
local changes,
 although these should be kept to a minimum.
 
 The copy of the code is not kept in =master= but in the
-=externals/<pkg-name>= branch in the =elpa.git= repository.
+=elpa/<pkg-name>= branch in the =elpa.git= repository.
 
 To add a new external package, first add this =elpa.git= repository as a
 new remote in your existing repository.
 
 Then push a local branch to a
-new remote branch in =elpa.git=, named =externals/<pkgname>=.  For example:
+new remote branch in =elpa.git=, named =elpa/<pkgname>=.  For example:
 
 #+begin_src shell
-   git push elpa <mybranch>:refs/heads/externals/<pkgname>
+   git push elpa <mybranch>:refs/heads/elpa/<pkgname>
 #+end_src
 
 For example, let's say that you want to add =realgud-ipdb= which is currently
@@ -300,32 +300,31 @@ checked out in =$HOME/github/realgud-ipdb=:
 #+begin_src shell
    cd $HOME/github/realgud-ipdb
    git remote add elpa ${USER}@git.sv.gnu.org:/srv/git/emacs/elpa.git
-   git push elpa master:refs/heads/externals/realgud-ipdb
+   git push elpa master:refs/heads/elpa/realgud-ipdb
 #+end_src
 
-Then edit the =externals-list= file as mentioned above, add the line
+Then edit the =elpa-packages= file as mentioned above, add the line
 
 #+begin_src elisp
-   ("realgud-ipdb" :external "https://github.com/realgud/realgud-ipdb";)
+   ("realgud-ipdb" :url "https://github.com/realgud/realgud-ipdb";)
 #+end_src
 
 and push that change to the master branch of =elpa=.  After it's added to
-the =externals-list= file, the package can be maintained just by
-pushing changes to the =externals/<pkgname>= branch.
+the =elpa-packages= file, the package can be maintained just by
+pushing changes to the =elpa/<pkgname>= branch.
 
-If you wish to check out all the external packages into the =packages=
+If you wish to check out all the packages into the =packages=
 directory, you can run the command:
 
 #+begin_src shell
-   make externals
+   make worktrees
 #+end_src
 
-You can check out a specific external =<pkgname>= into the =packages=
+You can check out a specific package =<pkgname>= into the =packages=
 directory with these commands:
 
-#+begin_src 
-   cd packages
-   git worktree add PACKAGE externals/<pkgname>
+#+begin_src
+   make packages/<pkgname>
 #+end_src
 
 If you already have a =packages/<pkgname>= directory with a previous
@@ -351,7 +350,7 @@ you have two choices:
 ** To install all the packages "in place":
 
 #+begin_src shell
-   make externals
+   make worktrees
    make
 #+end_src
 
diff --git a/README.org b/README.org
index 946cf7b..bdcadf2 100644
--- a/README.org
+++ b/README.org
@@ -60,7 +60,7 @@ to do:
 
 The packages can be installed and used in-place.  First you need to make
 sure the package(s) you can about are placed in the =packages= subdirectory,
-e.g. with =make externals=, and then you can to add that =.../packages=
+e.g. with =make worktrees=, and then you can to add that =.../packages=
 to your =package-directory-list=.  And once that is done you can do:
 
 #+begin_src sh
@@ -194,7 +194,7 @@ packages with:
 
 Once it is decided we want to add a package =[PKG]=, here's what it takes:
 
-- Add a corresponding entry to the file =externals-list=, then
+- Add a corresponding entry to the file =elpa-packages=, then
 
   #+begin_src sh
     make fetch/<pkgname>
@@ -216,10 +216,10 @@ Once it is decided we want to add a package =[PKG]=, 
here's what it takes:
     make sync/<pkgname>
   #+end_src
 
-- Commit and push the change to =externals-list=:
+- Commit and push the change to =elpa-packages=:
 
   #+begin_src sh
-    git commit -m "* externals-list (<pkgname>): New package" -- externals-list
+    git commit -m "* elpa-packages (<pkgname>): New package" -- elpa-packages
     git push
   #+end_src
 
diff --git a/elpa-admin.el b/elpa-admin.el
index fe5f485..db6c3d9 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -40,10 +40,10 @@
 (defvar elpaa--gitrepo "emacs/nongnu.git")
 (defvar elpaa--url "https://elpa.gnu.org/nongnu/";)
 
-(defvar elpaa--branch-prefix "externals/")
-(defvar elpaa--release-branch-prefix "externals-release/")
+(defvar elpaa--branch-prefix "elpa/")
+(defvar elpaa--release-branch-prefix "elpa-release/")
 
-(defvar elpaa--specs-file "externals-list")
+(defvar elpaa--specs-file "elpa-packages")
 (defvar elpaa--copyright-file "copyright_exceptions")
 (defvar elpaa--email-to nil) ;;"gnu-emacs-sources@gnu.org"
 (defvar elpaa--email-from nil) ;;"ELPA update <do.not.reply@elpa.gnu.org>"
@@ -141,7 +141,7 @@ Delete backup files also."
         (elpaa--html-make-index (cdr ac))))))
 
 (defun elpaa--get-specs ()
-  (elpaa--form-from-file-contents "externals-list"))
+  (elpaa--form-from-file-contents elpaa--specs-file))
 
 (defun elpaa--spec-get (pkg-spec prop &optional default)
   (or (plist-get (cdr pkg-spec) prop) default))
@@ -435,7 +435,7 @@ Return non-nil if a new tarball was created."
                                                         verdate))))
 
 (defun elpaa--get-package-spec (pkgname)
-  "Retrieve the property list for PKGNAME from `externals-list'."
+  "Retrieve the property list for PKGNAME from `elpaa--specs-file'."
   (let* ((specs (elpaa--get-specs))
          (spec (assoc pkgname specs)))
     (if (null spec)
@@ -463,7 +463,7 @@ Return non-nil if a new tarball was created."
          (dir (expand-file-name pkgname "packages"))
          (_ (if (eq (nth 1 pkg-spec) :core)
                 (elpaa--core-package-sync pkg-spec)
-              (elpaa--external-package-sync pkg-spec)))
+              (elpaa--worktree-sync pkg-spec)))
          (_ (elpaa--message "pkg-spec for %s: %S" pkgname pkg-spec))
          (metadata (elpaa--metadata dir pkg-spec))
          (vers (nth 1 metadata)))
@@ -1006,7 +1006,7 @@ Rename DIR/ to PKG-VERS/, and return the descriptor."
                      " " "\n")
                  (buffer-string))))))
 
-;;; Maintain external packages.
+;;; Maintain worktrees in the `packages' subdirectory
 
 (defun elpaa--sync-emacs-repo ()
   "Sync Emacs repository, if applicable.
@@ -1035,10 +1035,10 @@ Return non-nil if there's an \"emacs\" repository 
present."
         (throw 'found-important-file file)))
     nil))
 
-(defun elpaa--cleanup-packages (externals-list with-core)
+(defun elpaa--cleanup-packages (specs with-core)
   "Remove unknown subdirectories of `packages/'.
 This is any subdirectory inside `packages/' that's not under
-version control nor listed in EXTERNALS-LIST.
+version control nor listed in SPECS.
 If WITH-CORE is non-nil, it means we manage :core packages as well."
   (when (file-directory-p (expand-file-name "packages/"))
     (let ((default-directory (expand-file-name "packages/")))
@@ -1047,15 +1047,15 @@ If WITH-CORE is non-nil, it means we manage :core 
packages as well."
          ((file-symlink-p dir)
           ;; There are normally no such thing, but the user may elect to
           ;; add symlinks to other projects.  If so, update them, as if they
-          ;; were "externals".
+          ;; were "our" worktrees.
           (when (file-directory-p (expand-file-name ".git" dir))
             (elpaa--pull dir)))
-         ((or (not (file-directory-p dir)) )
+         ((not (file-directory-p dir))
           ;; We only add/remove plain directories in elpa/packages (not
           ;; symlinks).
           nil)
          ((member dir '("." "..")) nil)
-         ((assoc dir externals-list) nil)
+         ((assoc dir specs) nil)        ;One of our packages.
          ((file-directory-p (expand-file-name (format "%s/.git" dir)))
           (let ((status
                  (with-temp-buffer
@@ -1082,8 +1082,8 @@ If WITH-CORE is non-nil, it means we manage :core 
packages as well."
           ))))))
 
 
-(defun elpaa--external-package-sync (pkg-spec)
-  "Sync external package named PKG-SPEC."
+(defun elpaa--worktree-sync (pkg-spec)
+  "Sync worktree of PKG-SPEC."
   (let ((name (car pkg-spec))
         (default-directory (expand-file-name "packages/")))
     (unless (file-directory-p default-directory)
@@ -1128,7 +1128,7 @@ If WITH-CORE is non-nil, it means we manage :core 
packages as well."
                      (buffer-string))))
              (message "Cloning branch %s:\n%s" name output)))
           ((not (file-exists-p (concat name "/.git")))
-           (message "%s is in the way of an external, please remove!" name))
+           (message "%s is in the way of our worktree, please remove!" name))
           (t (elpaa--pull name)))))
 
 (defun elpaa--core-package-empty-dest-p (dest)
@@ -1227,8 +1227,8 @@ If WITH-CORE is non-nil, it means we manage :core 
packages as well."
           (elpaa--core-package-link-file
            file dest emacs-repo-root package-root exclude-regexp))))))
 
-(defun elpaa-add/remove/update-externals ()
-  "Remove non-package directories and fetch external packages."
+(defun elpaa-add/remove/update-worktrees ()
+  "Remove leftover worktrees and set worktrees for packages."
   (let ((command-line-args-left '("-")))
     (elpaa-batch-archive-update-worktrees)))
 
@@ -1242,7 +1242,7 @@ If WITH-CORE is non-nil, it means we manage :core 
packages as well."
       (let* ((pkg-spec (assoc pkg specs))
              (kind (nth 1 pkg-spec)))
         (pcase kind
-          (`:external (elpaa--external-package-sync pkg-spec))
+          ((or ':url `:external) (elpaa--worktree-sync pkg-spec))
           (`:core (when with-core (elpaa--core-package-sync pkg-spec)))
           (_ (if pkg-spec
                  (message "Unknown package kind `%S' for %s" kind pkg)
@@ -1437,12 +1437,11 @@ More at " (elpaa--default-url pkgname))
 ;;; Fetch updates from upstream
 
 (defun elpaa--branch (pkg-spec)
-  (elpaa--spec-get pkg-spec :branch "master"))
+  (elpaa--spec-get pkg-spec :branch))
 
 (defun elpaa--urtb (pkg-spec &optional branch)
   "Return our upstream remote tracking branch for PKG-SPEC."
-  (format "refs/remotes/upstream/%s/%s" (car pkg-spec)
-          (or branch (elpaa--branch pkg-spec))))
+  (format "refs/remotes/upstream/%s/%s" (car pkg-spec) (or branch "main")))
 
 (defun elpaa--ortb (pkg-spec)
   "Return our origin remote tracking branch for PKG-SPEC."
@@ -1456,17 +1455,19 @@ More at " (elpaa--default-url pkgname))
 
 (defun elpaa--fetch (pkg-spec &optional k)
   (let* ((pkg (car pkg-spec))
-         (url (elpaa--spec-get pkg-spec :external))
+         (url (or (elpaa--spec-get pkg-spec :external)
+                  (elpaa--spec-get pkg-spec :url)))
          (branch (elpaa--branch pkg-spec))
          (release-branch (elpaa--spec-get pkg-spec :release-branch))
          (urtb (elpaa--urtb pkg-spec))
-         (refspec (format "refs/heads/%s:%s" branch urtb))
+         ;; FIXME: Don't hardcode "master" here.
+         (refspec (format "+refs/heads/%s:%s" (or branch "master") urtb))
          (release-refspec (if release-branch
-                              (format "refs/heads/%s:%s"
+                              (format "+refs/heads/%s:%s"
                                       release-branch
-                                      (elpaa--urtb pkg-spec release-branch)))))
+                                      (elpaa--urtb pkg-spec "release")))))
     (if (not url)
-        (message "Missing upstream URL in externals-list for %s" pkg)
+        (message "No upstream URL in %s for %s" elpaa--specs-file pkg)
       (message "Fetching updates for %s..." pkg)
       (with-temp-buffer
         (cond
@@ -1491,8 +1492,6 @@ More at " (elpaa--default-url pkgname))
 
 (defun elpaa--push (pkg-spec)
   (let* ((pkg (car pkg-spec))
-         ;; (url (plist-get (cdr pkg-spec) :external))
-         ;; (branch (elpaa--branch pkg-spec))
          (release-branch (elpaa--spec-get pkg-spec :release-branch))
          (ortb (elpaa--ortb pkg-spec))
          (urtb (elpaa--urtb pkg-spec)))
@@ -1514,11 +1513,11 @@ More at " (elpaa--default-url pkgname))
                         (when release-branch
                           (list
                            (format "%s:refs/heads/%s%s"
-                                   (elpaa--urtb pkg-spec release-branch)
+                                   (elpaa--urtb pkg-spec "release")
                                    elpaa--release-branch-prefix pkg)))))
         (message "Pushed %s successfully:\n%s" pkg (buffer-string))
         (when (file-directory-p (expand-file-name (car pkg-spec) "packages"))
-          (elpaa--external-package-sync pkg-spec)))
+          (elpaa--worktree-sync pkg-spec)))
        (t
         (message "Push error for %s:\n%s" pkg (buffer-string)))))))
 
@@ -1531,7 +1530,7 @@ More at " (elpaa--default-url pkgname))
       (let* ((pkg-spec (assoc pkg specs)))
         (if (not pkg-spec) (message "Unknown package: %s" pkg)
           ;; (unless (file-directory-p (expand-file-name pkg "packages"))
-          ;;   (elpaa--external-package-sync pkg-spec))
+          ;;   (elpaa--worktree-sync pkg-spec))
           (elpaa--fetch pkg-spec k))))))
 
 (defun elpaa-batch-fetch-and-show (&rest _)