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
  96 You can check out all the external packages into the `packages' directory
  97 with the command:
  98
  99    make externals
 100
 101 You can check out a specific external PACKAGE into the `packages'
 102 directory with these commands:
 103
 104    cd packages
 105    git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
 106
 107 If you already have a packages/PACKAGE directory with a previous
 108 checkout, you can update it like this:
 109
 110    cd packages/PACKAGE
 111    git pull
 112
 113 ** Public incubation
 114
 115 If you want to develop a package publicly prior to its first release (to
 116 benefit from others' feedback, primarily), but not in an external repo,
 117 you have 2 choices:
 118 - you can simply put "Version: 0" to indicate that this should not be
 119   released yet.
 120 - or you can push to an "ephemeral" branch -- subject to rebase and eventual
 121   removal upon finishing merge -- for the duration of the incubation.
 122
 123 * DEPLOYMENT
 124
 125 ** To install all the packages "in place":
 126
 127    make externals
 128    make
 129
 130 This compiles and generates autoloads for all the packages in the
 131 packages/ directory.  You can then add that directory, e.g. with:
 132
 133 (eval-after-load 'package
 134   '(add-to-list 'package-directory-list ".../elpa/packages"))
 135
 136 ** To deploy the package repository as a remotely-accessible archive:
 137
 138    git clone .../elpa
 139    mkdir build
 140    cd build
 141    (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
 142    ln -s ../elpa/admin
 143    ln -s ../elpa/GNUmakefile
 144    admin/update-archive.sh
 145
 146 This deploys the packages to the staging/ directory (sibling of "build").
 147 Unlike "make", this makes a full copy of the packages, tars up
 148 multi-file packages, and doesn't byte-compile any files.
 149
 150 ** To access a deployed archive
 151
 152 To access the archive via HTTP, have a symlink (say) /var/www/packages
 153 pointing to DEST/packages, and set up Emacs with
 154
 155   (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
 156
 157 You can also access the archive via normal file access.  Such "local
 158 archives" are useful for debugging:
 159
 160   (setq package-archives '(("local-elpa" . ".../elpa/packages")))
 161
 162 ** Notes specific to elpa.gnu.org
 163
 164 The way things are set up on this machine, we refresh the archive by
 165 a cron job.  You can do it by hand by logging in (access set up by FSF
 166 admins), and
 167
 168    su elpa
 169    cd ~elpa/build
 170    admin/update-archive.sh
 171
 172 Which makes a full archive deployment, as discussed above.  The symlink
 173 /var/www/packages points to the staging package directory under
 174 /home/elpa/.
 175
 176 The Org mode dailies are also fetched and added by the script
 177 admin/org-synch.sh, run as a cron job.
 178
 179 \f
 180 This file is part of GNU Emacs.
 181
 182 GNU Emacs is free software: you can redistribute it and/or modify
 183 it under the terms of the GNU General Public License as published by
 184 the Free Software Foundation, either version 3 of the License, or
 185 (at your option) any later version.
 186
 187 GNU Emacs is distributed in the hope that it will be useful,
 188 but WITHOUT ANY WARRANTY; without even the implied warranty of
 189 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 190 GNU General Public License for more details.
 191
 192 You should have received a copy of the GNU General Public License
 193 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 194
 195 \f
 196 Local variables:
 197 mode: outline
 198 paragraph-separate: "[  \f]*$"
 199 end: