[elpa] elpa-admin 0f9bfa0 12/12: Merge branch 'readme-sync'

[Jonas Bernoulli]

branch: elpa-admin
commit 0f9bfa05466284f4976916aad4746900ea9a167f
Merge: d1a6387 ec86817
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Merge branch 'readme-sync'
---
 README     | 155 ++++++++++++++++++++++++++++++++-----------------------------
 README.org |  49 ++++++++++++-------
 2 files changed, 115 insertions(+), 89 deletions(-)

diff --git a/README b/README
index 558fbc7..46dc7fe 100644
--- a/README
+++ b/README
@@ -4,6 +4,15 @@
 Copyright (C) 2010-2021 Free Software Foundation, Inc. \\
 See the end of the file for license conditions.
 
+#+BEGIN_COMMENT
+This file exists in two branches ~elpa-admin~ and ~elpa~.  The two version
+differ slightly.  The introductory text before the first heading
+differs and their are minor differences concerning the ~externals/*~ to
+~elpa/*~ transition.  Please make sure you always update this file in
+both locations to avoid introducing additional differences.  This
+duplication will be removed eventually.
+#+END_COMMENT
+
 This branch contains the source code used to build and manage
 the [[https://elpa.gnu.org/][GNU ELPA]] and NonGNU ELPA archives.
 
@@ -12,6 +21,36 @@ the [[https://elpa.gnu.org/][GNU ELPA]] and NonGNU ELPA 
archives.
 Start with source that is cloned directly from Savannah.  See 
[[https://savannah.gnu.org/git/?group=emacs][the Savannah page]]
 and look for "ELPA".  Using a clone of a clone does not work.
 
+You must then do some setup:
+#+begin_src shell
+   make setup
+#+end_src
+
+That leaves the =packages= directory empty; you must check out the
+ones you want.
+
+If you wish to check out all the packages into the =packages=
+directory, you can run the command:
+
+#+begin_src shell
+   make worktrees
+#+end_src
+
+You can check out a specific package =<pkgname>= into the =packages=
+directory with this command:
+
+#+begin_src
+   make packages/<pkgname>
+#+end_src
+
+If you already have a =packages/<pkgname>= directory with a previous
+checkout, you can update it like this:
+
+#+begin_src
+   cd packages/PACKAGE
+   git pull
+#+end_src
+
 * Directory layout
 
 This code expects to be used in a directory that has the following layout:
@@ -209,15 +248,14 @@ Delete all the files generated by =make 
packages/[PKGNAME]=.
 This directory holds the package sources, with one subdirectory for
 each package.
 
-Each directory in here corresponds to a package, which can be
-either a single-file package or a multifile package.
+Each directory in here corresponds to a package.
 
 A nightly cron job refreshes the GNU ELPA archive from this repository.
 
 This cron job only creates a new package when the "version" (as specified in
 the =Version:= header) of a package is modified.  This means that you can
 safely work on the next version here without worrying about the unstable
-code making it to GNU ELPA, and simply update the "version" when you want to
+code making it to GNU ELPA, and simply update the =Version:= when you want to
 release the new code.
 
 ** To add a package: (submission, submit)
@@ -261,19 +299,19 @@ Start your message with an explanation about the package. 
 A
 copy-paste of the package's =Summary= and =Commentary= is perfectly fine
 here, but you can write more or less than that if you'd like.
 
-At the bottom of the message contents include the changes you're going
-to make (the patch).  For a single-file package this can be the
-package file itself instead of the patch.  If you prefer (and if you
+In your message include the URL of a Git repository where your package can
+be found (or if that's not convenient and the package is small enough,
+include a copy of its code as an attachment).  If you prefer (and if you
 have push access), you can push your changes to a branch called
 =scratch/<pkg-name>=, and mention the branch in your message.
 
 After 48 hours, or once any issues have been addressed, someone will push
 your changes for you.  You should probably also subscribe to
-[[https://lists.gnu.org/mailman/listinfo/emacs-devel][emacs-devel@gnu.org]], 
since that's where we discuss about GNU Elpa, and
+[[https://lists.gnu.org/mailman/listinfo/emacs-devel][emacs-devel@gnu.org]], 
since that's where we discuss about GNU ELPA, and
 to 
[[https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs][bug-gnu-emacs@gnu.org]],
 since that's where people will report bugs
 about your package.
 
-*** Add a simple (1-file) package as =packages/<pkg-name>/<pkg-name>.el.=
+*** Add a simple package as =<pkg-name>.el=.
 
 The file needs to follow the usual coding conventions (most importantly start
 with =";;; <file> --- <description> -*- lexical-binding: t -*-"=) and have a
@@ -285,9 +323,9 @@ For some examples, see 
[[https://www.gnu.org/software/emacs/manual/html_node/eli
     (info "(elisp) Simple Packages")
 #+end_src
 
-*** Add a multi-file package as a directory: =packages/<pkg-name>=
+*** Add a multi-file package as a directory
 
-It needs to have a file named =packages/<pkg-name>/<pkg-name>.el= which 
follows the
+It needs to have a file named =<pkg-name>/<pkg-name>.el= which follows the
 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]]
@@ -330,14 +368,11 @@ and the web-pages from this source code:
   in the format used for single-file packages: the =<pkg-name>-pkg.el= file is
   auto-generated from it.
 - Every package should have both a =Version:= /and/ a =Maintainer:=.
+- The =Version:= must be acceptable to =version-to-list=.
 - The =URL:= header can be used to specify the home page
   of the package, if it's maintained externally.
 - A =News:= section (or "NEWS" file) can/should be used to list the
   user-visible changes of each version.
-- The =Package-Type:= header can be used to force the type of package
-  created (can be either =simple= for single-file packages or =multi= for
-  tarballs).  By default the type is decided based on whether there are
-  several Elisp files in the source.
 - If you want some files to not be included in the tarball, you can
   put a =.elpaignore= file in the root of your package directory, where you
   can list patterns of files to ignore (this file is passed to =tar='s =-X=).
@@ -359,20 +394,15 @@ correctly in the commit.
 
 ** External branches
 
-The above instructions are enough to add regular packages, those that
-are maintained primarily here in the repository and are fairly small.
-The instructions below are for those maintainers who prefer to use a dedicated
-repository or branch for the package or for largish packages.
-
-In any case, a copy of the code is kept in the =elpa.git= repository
-(not in the default branch) and should be sync'd with the
+A copy of the code of every package is kept in the =elpa.git= repository
+(not in the =main= branch) and if applicable should be sync'd with the
 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 the default branch but in the
+The copy of the code is not kept in the =main= branch but in the
 =elpa/<pkg-name>= branch in the =elpa.git= repository.
 
-To add a new external package, first add this =elpa.git= repository as a
+To add a new package, first add this =elpa.git= repository as a
 new remote in your existing repository.
 
 Then push a local branch to a
@@ -397,32 +427,10 @@ Then edit the =elpa-packages= file as mentioned above, 
add the line
    ("realgud-ipdb" :url "https://github.com/realgud/realgud-ipdb";)
 #+end_src
 
-and push that change to the default branch of =elpa=.  After it's added to
+and push that change to the =main= branch of =elpa=.  After it's added to
 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 packages into the =packages=
-directory, you can run the command:
-
-#+begin_src shell
-   make worktrees
-#+end_src
-
-You can check out a specific package =<pkgname>= into the =packages=
-directory with these commands:
-
-#+begin_src
-   make packages/<pkgname>
-#+end_src
-
-If you already have a =packages/<pkgname>= directory with a previous
-checkout, you can update it like this:
-
-#+begin_src 
-   cd packages/PACKAGE
-   git pull
-#+end_src
-
 ** Public incubation
 
 If you want to develop a package publicly prior to its first release (to
@@ -452,37 +460,18 @@ This compiles and generates autoloads for all the 
packages in the
 
 ** To deploy the package repository as a remotely-accessible archive:
 
-The deployment process creates sibling directories, so start by creating
-a clean directory to work in:
-
-#+begin_src shell
-   mkdir elpa ; cd elpa
-#+end_src
-
-The above step is optional, but recommended.
-
 #+begin_src shell
-   git -c fetch.fsckObjects=false clone .../elpa
-   (cd elpa; git clone .../emacs)    #If you want to generate :core packages.
-   mkdir build
-   cd build
-   (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
-   ln -s ../elpa/admin
-   ln -s ../elpa/GNUmakefile
-   admin/update-archive.sh
+   make build-all
 #+end_src
 
-This deploys the packages to the =staging/= directory (sibling of =build=).
+This deploys the packages to the =archive/= subdirectory.
 Unlike =make=, this makes a full copy of the packages, tars up
 multi-file packages, and doesn't byte-compile any files.
 
-The =fetch.fsckObjects= setting works around a glitch in the ELPA
-repository.  (See [[https://debbugs.gnu.org/22690][Bug#22690]].)
-
 ** To access a deployed archive
 
 To access the archive via HTTP, have a symlink (say) =/var/www/packages=
-pointing to =DEST/packages=, and set up Emacs with
+pointing to the =archive/= subdirectory, and set up Emacs with
 
 #+begin_src elisp
   (setq package-archives '(("new-elpa" . "https://foo.com/packages";)))
@@ -492,25 +481,45 @@ You can also access the archive via normal file access.  
Such "local
 archives" are useful for debugging:
 
 #+begin_src elisp
-  (setq package-archives '(("local-elpa" . ".../elpa/packages")))
+  (setq package-archives '(("local-elpa" . ".../elpa/archive")))
 #+end_src
 
 ** Notes specific to =elpa.gnu.org=
 
+*** Periodic builds
 The way things are set up on this machine, we refresh the archive by
 a cron job.  You can do it by hand by logging in (access set up by FSF
 admins), and
 
 #+begin_src shell
-   su elpa
-   cd ~elpa/build
-   admin/update-archive.sh
+   su - elpa
+   cd elpa
+   make build-all
 #+end_src
 
 Which makes a full archive deployment, as discussed above.  The symlink
-=/var/www/packages= points to the staging package directory under
+=/var/www/packages= points to the corresponding directory under
 =/home/elpa/=.
 
+*** Release and devel archives
+elpa.gnu.org serves the gnu and nongnu package collections (roughly,
+gnu requires FSF copyright assign, nongnu doesn't, but these terms are
+not fully defined here).
+
+In addition, elpa.gnu.org serves release and devel versions of each
+package. The release version is defined by a change in the =Version:=
+header of a package; the devel version is the latest commit.
+
+The release version is accessed at:
+
+gnu    - https://elpa.gnu.org/packages/
+nongnu - https://elpa.nongnu.org/nongnu/
+
+The devel version is accessed at:
+
+gnu    - https://elpa.gnu.org/devel
+nongnu - https://elpa.nongnu.org/nongnu-devel/
+
 * License
 This file is part of GNU Emacs.
 
diff --git a/README.org b/README.org
index d050698..b2f2a33 100644
--- a/README.org
+++ b/README.org
@@ -1,9 +1,16 @@
 #+TITLE: NonGNU ELPA README
-#+DATE: 2020-12-21
+#+DATE: 2021-10-19
 
-Copyright (C) 2020 Free Software Foundation, Inc. \\
+Copyright (C) 2020-2021 Free Software Foundation, Inc. \\
 See the end of the file for license conditions.
 
+#+BEGIN_COMMENT
+This file exists in two repositories, in the ~elpa-admin~ branch of
+the ~emacs/elpa.git~ repository and in the ~main~ branch of the
+~emacs/nongnu.git~ repository.  Please make sure you always update
+it in both locations.  This duplication will be removed eventually.
+#+END_COMMENT
+
 This repository contains the sources, deployment scripts, and auxiliary files
 for [[https://nongnu.elpa.org][NonGNU ELPA]] (=elpa.nongnu.org=).  NonGNU ELPA 
is a [[https://www.gnu.org/philosophy/free-sw.html][free software]] Emacs Lisp
 Package Archive (ELPA) with extensions to 
[[https://www.gnu.org/software/emacs/][GNU Emacs]].
@@ -12,6 +19,26 @@ This file explains the repository layout, how to add and 
edit packages, and how
 to deploy the archive (either on =elpa.nongnu.org=, or a local copy for testing
 purposes).
 
+* Initial setup
+
+To do anything with, you first have to have a local clone, which you can get
+with:
+
+#+begin_src sh
+    git clone .../nongnu.git $FOO
+#+end_src
+
+and which you may have done already if you're reading this file.
+The main branch on =nongnu.git= only holds the list of specifications
+of the packages included, but not the scripts to build them.
+So after doing this, you need to do:
+
+#+begin_src sh
+    make
+#+end_src
+
+This will fetch a branch from =elpa.git= containing all the build scripts
+and makefiles and place them where needed.
 
 * Building the archive
 
@@ -27,13 +54,6 @@ directory.  This format is described in the Emacs Lisp 
Reference Manual chapter
 To build the archive(s), all it takes is:
 
 #+begin_src sh
-    git clone .../nongnu.git $FOO
-#+end_src
-
-which you presumably have done already if you're reading this file.
-And then
-
-#+begin_src sh
     cd .../nongnu
     make build-all
 #+end_src
@@ -55,27 +75,25 @@ to do:
     rm archive/[PKG]-[VERSION].tar; make build/[PKG]
 #+end_src
 
-
 * Using packages in-place
 
 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 worktrees=, and then you can to add that =.../packages=
-to your =package-directory-list=.  And once that is done you can do:
+sure the package(s) you care about are placed in the =packages= subdirectory,
+e.g. with =make worktrees=, and then you can add that =.../packages= to your
+=package-directory-list=.  And once that is done, you can do:
 
 #+begin_src sh
     make packages/[PKG]
 #+end_src
 
 to create the =[PKG]-pkg.el= and =[PKG]-autoloads.el= file as well as compile
-all the ELisp files in that package.  You can also do that on all the
+all the ELisp files in that package.  You can also do that for all the
 packages with:
 
 #+begin_src sh
     make
 #+end_src
 
-
 * Guidance for accepting packages
 
 ** We don't ask for copyright assignments to include packages in NonGNU ELPA.
@@ -189,7 +207,6 @@ packages with:
    the package, and you can mention fan items that you sell directly to
    the users.
 
-
 * Adding a package
 
 Once the NonGNU ELPA maintainers decides that we want to add a package =[PKG]=,