code.delx.au - gnu-emacs-elpa/blob - README

   1 Copyright (C) 2010-2011, 2014 Free Software Foundation, Inc.
   2 See the end of the file for license conditions.
   3
   4
   5 This branch contains the sources, deployment scripts, and auxilliary
   6 files for the Emacs Lisp package archive (elpa.gnu.org).
   7
   8 This file explains the branch layout, how to add and edit packages,
   9 and how to deploy the archive (either on elpa.gnu.org, or a local copy
  10 for testing purposes).
  11
  12
  13 * DIRECTORY LAYOUT
  14
  15 ** admin/    -- scripts for administering the package archive.
  16 ** html/     -- HTML for the elpa.gnu.org website.
  17 ** packages/ -- source code for the packages.
  18
  19
  20 * PACKAGES
  21
  22 ** Contents of the packages/ directory:
  23 This directory holds the package sources, with one subdirectory for
  24 each package.
  25
  26 Each directory in here corresponds to a package, which can be
  27 either a single-file package or a multifile package.
  28
  29 A nightly cron job refreshes the GNU ELPA archive from this repository.
  30
  31 This cron job only creates a new package when the "version" (as specified in
  32 the "Version:" header) of a package is modified.  This means that you can
  33 safely work on the next version here without worrying about the unstable
  34 code making it to GNU ELPA, and simply update the "version" when you want to
  35 release the new code.
  36
  37 ** To add a package:
  38
  39 *** Add a simple (1-file) package as packages/NAME/NAME.el.
  40
  41 The file needs to follow the usual coding conventions (most importantly
  42 start with ";;; <file> --- <description>") and have a "Version:" and
  43 "Maintainer:" pseudo-header.
  44
  45 *** Add a multi-file package as a directory, packages/NAME.
  46
  47 It needs to have a file named packages/NAME/NAME.el which follows the same
  48 rules as above.
  49
  50 *** Commit your changes the usual way ("git add", "git commit", etc).
  51
  52 Changes in the Git repository do not immediately propagate to the
  53 user-facing archive (what users see when they do `M-x list-packages').
  54 That is done by deploying the archive, which happens automatically
  55 once a day, and the changes are only reflected when the "Version:"
  56 header changes.
  57
  58 ** Format
  59
  60 Each package should follow the ELPA packaging conventions, but there are
  61 some differences due to the way the deployment script creates the packages
  62 and the web-pages from this source code:
  63 - Multi-file packages put the package metadata in the main <pkg>.el file
  64   in the format used for single-file packages: the <pkg>-pkg.el file is
  65   auto-generated from it.
  66 - Every package should have both a "Version:" *and* a "Maintainer:".
  67 - the "URL:" header can be used to specify the home page
  68   of the package, if it's maintained externally.
  69 - A "News:" section (or "NEWS" file) can/should be used to list the
  70   user-visible changes of each version.
  71 - The "Package-Type:" header can be used to force the type of package
  72   created (can be either `simple' for single-file packages or `multi' for
  73   tarballs).  By default the type is decided based on whether there are
  74   several Elisp files in the source.
  75 - If you want some files to not be included in the tarball, you can
  76   put a `.elpaignore' file in the root of your package directory, where you
  77   can list patterns of files to ignore (this file is passed to tar's -X).
  78
  79 ** External branches
  80
  81 Some packages are maintained in external branches.  These should be
  82 appropriately listed in the `externals-list' file.
  83 There are two different cases: subtrees and externals.
  84
  85 In both cases, a copy of the code is kept in the `elpa' repository and
  86 should be sync'd with the upstream every once in a while.  This copy may
  87 include local changes, tho ideally these should be kept to a minimum.
  88
  89 In the `subtree' case, the copy of the code is kept here in the
  90 corresponding `packages/<pkg>' directory.  You should be able to "git
  91 merge -s subtree" from the upstream branch.
  92
  93 In the `external' case, the copy of the code is not kept here but in the
  94 `externals/<pkg>' branch in the `elpa' repository.
  95 You can check out all the external packages into the `packages' directory
  96 with the command:
  97
  98    make externals
  99
 100 ** Public incubation
 101
 102 If you want to develop a package publicly prior to its first release (to
 103 benefit from others' feedback, primarily), but not in an external repo,
 104 you have 2 choices:
 105 - you can simply put "Version: -1" to indicate that this should not be
 106   released.
 107 - or you can push to an "ephemeral" branch -- subject to rebase and eventual
 108   removal upon finishing merge -- for the duration of the incubation.
 109
 110 * DEPLOYMENT
 111
 112 ** To install all the packages "in place":
 113
 114    make externals
 115    make
 116
 117 This compiles and generates autoloads for all the packages in the
 118 packages/ directory.  You can then add that directory, e.g. with:
 119
 120 (eval-after-load 'package
 121   '(add-to-list 'package-directory-list ".../elpa/packages"))
 122
 123 ** To deploy the package repository as a remotely-accessible archive:
 124
 125    git clone .../elpa
 126    mkdir build
 127    cd build
 128    (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
 129    ln -s ../elpa/admin
 130    ln -s ../elpa/GNUmakefile
 131    admin/update-archive.sh
 132
 133 This deploys the packages to the staging/ directory (sibling of "build").
 134 Unlike "make", this makes a full copy of the packages, tars up
 135 multi-file packages, and doesn't byte-compile any files.
 136
 137 ** To access a deployed archive
 138
 139 To access the archive via HTTP, have a symlink (say) /var/www/packages
 140 pointing to DEST/packages, and set up Emacs with
 141
 142   (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
 143
 144 You can also access the archive via normal file access.  Such "local
 145 archives" are useful for debugging:
 146
 147   (setq package-archives '(("local-elpa" . ".../elpa/packages")))
 148
 149 ** Notes specific to elpa.gnu.org
 150
 151 The way things are set up on this machine, we refresh the archive by
 152 a cron job.  You can do it by hand by logging in (access set up by FSF
 153 admins), and
 154
 155    su elpa
 156    cd ~elpa/build
 157    admin/update-archive.sh
 158
 159 Which makes a full archive deployment, as discussed above.  The symlink
 160 /var/www/packages points to the staging package directory under
 161 /home/elpa/.
 162
 163 The Org mode dailies are also fetched and added by the script
 164 admin/org-synch.sh, run as a cron job.
 165
 166 \f
 167 This file is part of GNU Emacs.
 168
 169 GNU Emacs is free software: you can redistribute it and/or modify
 170 it under the terms of the GNU General Public License as published by
 171 the Free Software Foundation, either version 3 of the License, or
 172 (at your option) any later version.
 173
 174 GNU Emacs is distributed in the hope that it will be useful,
 175 but WITHOUT ANY WARRANTY; without even the implied warranty of
 176 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 177 GNU General Public License for more details.
 178
 179 You should have received a copy of the GNU General Public License
 180 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 181
 182 \f
 183 Local variables:
 184 mode: outline
 185 paragraph-separate: "[  \f]*$"
 186 end: