-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.
\f
This file is part of GNU Emacs.
You should have received a copy of the GNU General Public License
along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
+
+\f
+Local variables:
+mode: outline
+paragraph-separate: "[ \f]*$"
+end: