X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/0612bb8d1ad8dab7b864e461e45a99b72eba509b..368dbd026fe0ebd0f9f50be09d0f2a5f58d06c0a:/README

diff --git a/README b/README
index 891cc4318..097e43049 100644
--- a/README
+++ b/README
@@ -1,11 +1,97 @@
-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
+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).
+
+
+* DIRECTORY LAYOUT
+
+** admin/    -- scripts for administering the package archive.
+** html/     -- HTML for the elpa.gnu.org website.
+** packages/ -- source code for the packages.
+
+
+* PACKAGES
+
+** Contents of the packages/ directory:
+This directory holds the package sources, with one subdirectory for
+each package.
+
+** To add a package:
+
+*** Add a simple (1-file) package as packages/NAME/NAME.el.
+
+*** Add a multi-file package as a directory, packages/NAME.
+
+*** Commit your changes 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.
+
+
+* DEPLOYMENT
+
+** To use the package repository as a "site installation" of packages:
+
+  make site
+
+This compiles and generates autoloads for all the packages in the
+packages/ directory, and creates a site/ directory containing symlinks
+to the package directories.
+
+Now you have to add this site/ directory to `package-directory-list',
+and all the packages will be available.
+
+** To deploy the package repository as a remotely-accessible archive:
+
+  make archive
+
+or
+
+  make archive-full
+
+This deploys the packages to the archive/ directory.  Unlike "make
+site", this makes a full copy of the packages, and tars up multi-file
+packages.
+
+A full deployment also copies the admin scripts to archive/admin, and
+fetches externally hosted packages (currently, the Org daily builds)
+and adds them to the archive.
+
+** To access 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
+
+Then make a full archive deployment, as discussed above.  The symlink
+/var/www/packages points to the staging package directory under
+/home/elpa/.
+
+The Org mode dailies are also fetched and added by the script
+admin/org-synch.sh, run as a cron job.
 
 
 This file is part of GNU Emacs.
@@ -22,3 +108,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: