branch: elpa-admin
commit 0b8402335c316ac86c8ba429a342cfc78b4c9c69
Author: Stefan Monnier <monn...@iro.umontreal.ca>
Commit: Stefan Monnier <monn...@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-sour...@gnu.org"
(defvar elpaa--email-from nil) ;;"ELPA update <do.not.re...@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 _)
