[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] new-master b83d412 013/128: README: Document usage of this reposi
From: |
Stefan Monnier |
Subject: |
[elpa] new-master b83d412 013/128: README: Document usage of this repository in detail. |
Date: |
Mon, 14 Dec 2020 15:39:22 -0500 (EST) |
branch: new-master
commit b83d412e2286167ac9eb4442504eecc41f15cf90
Author: Chong Yidong <cyd@stupidchicken.com>
Commit: Chong Yidong <cyd@stupidchicken.com>
README: Document usage of this repository in detail.
---
README | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 125 insertions(+), 11 deletions(-)
diff --git a/README b/README
index 2fa9ffa..65a6ae2 100644
--- a/README
+++ b/README
@@ -1,19 +1,127 @@
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2010-2011 Free Software Foundation, Inc.
See the end of the file for license conditions.
-This is the Emacs repository for ELPA-style packages.
+This branch contains the sources, deployment scripts, and auxilliary
+files for the Emacs Lisp package archive (elpa.gnu.org).
-packages/ contains all the packages
-admin/ contains all the fetch and deployment scripts
-html/ contains the HTML to run the repo.
+This file explains the branch layout, how to add and edit packages,
+and how to deploy the archive (either on elpa.gnu.org, or a local copy
+for testing purposes).
-To make your own copy of this repo:
-bzr cat bzr://bzr.savannah.gnu.org/emacs/elpa/admin/package-update.sh
-chmod +x package-update.sh
-./package-update.sh $INSTALLDIR
-# what did the installer do? let's check...
-cat $INSTALLDIR/update-log
+
+* DIRECTORY LAYOUT
+
+** admin/ -- scripts for deploying the package archive.
+ See the DEPLOYMENT section for details.
+** html/ -- HTML for the elp.gnu.org website.
+** packages/ -- source code for the packages.
+
+
+* PACKAGES
+
+** Contents of the packages/ directory:
+
+This directory holds the package sources. Unlike the deployed package
+archive, multi-file packages are present here as directories, not tar
+files. So, edits to the sources can be easily managed by Bzr.
+
+*** archive-contents
+This file contains a Lisp form recording the hosted package names and
+their attributes. Once the archive is deployed, Emacs learns the
+archive contents by reading this file (normally via HTTP).
+
+In the future, we'll remove this file from the repository, and
+generate it automatically during deployment.
+
+*** Package sources
+In the form of *.el files for simple (1-file) packages, or
+subdirectories for multi-file packages.
+
+*** Readme files
+When the archive is deployed, Emacs retrieves the package descriptions
+by reading these files (normally via HTTP).
+
+In the future, we'll remove these files from the repository, and
+generate them during deployment.
+
+** To add a package:
+
+*** Add a simple (1-file) package as packages/NAME-VERSION.el.
+
+*** Add a multi-file package a directory, packages/NAME-VERSION.
+
+*** Add a readme file, packages/NAME-readme.txt. This should be a
+copy of the commentary section for a simple package, or the README
+file for a multi-file package.
+
+*** Edit archive-contents and add an entry for the new package.
+
+*** Commit your changes
+This is done the usual way ("bzr add", "bzr commit", etc).
+
+Changes in the Bzr repository do not immediately propagate to the
+user-facing archive (what users see when they do `M-x list-packages').
+That is done by deploying the archive (see below).
+
+
+* DEPLOYMENT
+
+** The package-update.sh script
+
+Use the script admin/package-update.sh to deploy a partial or full
+copy of the package archive. To run a partial deployment:
+
+ /PATH/TO/admin/package-update.sh DEST
+
+This deploys the packages in packages/ to DEST/packages.
+
+To run a full deployment:
+
+ /PATH/TO/admin/package-update.sh DEST 1
+
+A full deployment additionally copies the admin scripts to DEST/admin,
+creates a full tarball in DEST/packages/emacs-packages-latest.tgz, and
+fetches externally hosted packages (currently, the Org daily builds)
+and adds them to the archive.
+
+The package-update.sh script only works if it lives in a bzr
+repository. It uses `bzr export' to deploy from the repository to the
+destination directory. If you have uncommitted changes in the working
+copy, those changes are not deployed.
+
+You can view the deployment log at DEST/update-log.
+
+The other scripts in the admin/ subdirectory are used for fetching the
+Org dailies.
+
+** Accessing a deployed archive
+
+To access the archive via HTPP, have a symlink (say) /var/www/packages
+pointing to DEST/packages, and set up Emacs with
+
+ (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
+
+You can also access the archive via normal file access. Such "local
+archives" are useful for debugging:
+
+ (setq package-archives '(("local-elpa" . "DEST/packages")))
+
+** Notes specific to elpa.gnu.org
+
+The way things are set up on this machine, we refresh the archive by
+logging in (login access set up by FSF admins), and
+
+su elpa
+cd ~elpa/elpa
+bzr up
+./admin/package-update /home/elpa/staging/ 1
+
+The symlink /var/www/packages points to /home/elpa/staging/packages.
+
+The Org mode dailies are fetched and added by the script
+admin/org-synch.sh, which is run as a cron job (we also run this
+script during deployment).
This file is part of GNU Emacs.
@@ -30,3 +138,9 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
+
+
+Local variables:
+mode: outline
+paragraph-separate: "[ ]*$"
+end:
- [elpa] branch new-master created (now 61bd755), Stefan Monnier, 2020/12/14
- [elpa] new-master a1502c2 008/128: Track original positions in the face of possible edits. Intended use in debugging where one might edit the file but continue editing., Stefan Monnier, 2020/12/14
- [elpa] new-master 989f788 006/128: Added comment about installing with multiple emacsen., Stefan Monnier, 2020/12/14
- [elpa] new-master e33caa0 011/128: * html/index.html, html/layout.css : Initial import., Stefan Monnier, 2020/12/14
- [elpa] new-master 226da6a 007/128: Added script and documentation for installing from CVS, Stefan Monnier, 2020/12/14
- [elpa] new-master d14b47a 010/128: * COPYING, ChangeLog, README, admin/org-synch.el,, Stefan Monnier, 2020/12/14
- [elpa] new-master 385d3ec 012/128: * README: Explain how to run the repo build script., Stefan Monnier, 2020/12/14
- [elpa] new-master b83d412 013/128: README: Document usage of this repository in detail.,
Stefan Monnier <=
- [elpa] new-master 3ec9dc4 002/128: # Added comment about loading supplied classes separately., Stefan Monnier, 2020/12/14
- [elpa] new-master 7a4e787 016/128: Update README to describe the new repository layout., Stefan Monnier, 2020/12/14
- [elpa] new-master f232d97 017/128: Add full licence text (COPYING), Stefan Monnier, 2020/12/14
- [elpa] new-master 54a4cb6 018/128: Initial checkin of files. These files were initially part of the, Stefan Monnier, 2020/12/14
- [elpa] new-master c1b76ff 019/128: Rework test-unit into something even simpler., Stefan Monnier, 2020/12/14
- [elpa] new-master fd0dc42 024/128: Initial Import, Stefan Monnier, 2020/12/14
- [elpa] new-master feebdea 029/128: README.md, load-relative.el: Go over documentation. Makefile.am: add targets test and test-short, Stefan Monnier, 2020/12/14
- [elpa] new-master 74b4742 035/128: Make html/index.html be consistent with other gnu.org websites., Stefan Monnier, 2020/12/14
- [elpa] new-master da544ac 036/128: Minor cleanup., Stefan Monnier, 2020/12/14
- [elpa] new-master 8b71768 039/128: seems to be generally usable, added a README, Stefan Monnier, 2020/12/14