1 Copyright (C) 2010-2011, 2014 Free Software Foundation, Inc.
2 See the end of the file for license conditions.
5 This branch contains the sources, deployment scripts, and auxiliary
6 files for the Emacs Lisp package archive (elpa.gnu.org).
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).
15 ** admin/ -- scripts for administering the package archive.
16 ** html/ -- HTML for the elpa.gnu.org website.
17 ** packages/ -- source code for the packages.
22 ** Contents of the packages/ directory:
23 This directory holds the package sources, with one subdirectory for
26 Each directory in here corresponds to a package, which can be
27 either a single-file package or a multifile package.
29 A nightly cron job refreshes the GNU ELPA archive from this repository.
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
39 *** Add a simple (1-file) package as packages/<pkg-name>/<pkg-name>.el.
41 The file needs to follow the usual coding conventions (most
42 importantly start with ";;; <file> --- <description>") and have a
43 "Version:" and "Maintainer:" pseudo-header (see the "Format"
46 For some examples, see
47 (info "(elisp) Simple Packages")
49 *** Add a multi-file package as a directory, packages/<pkg-name>.
51 It needs to have a file named packages/<pkg-name>/<pkg-name>.el which follows the
54 It additionally follows the same guidelines described in
55 (info "(elisp) Multi-file Packages")
56 with the exception that it is not a tar package (it's a plain
57 directory) and it must not contain a "<pkg-name>-pkg.el" file (this
58 will be created for you).
60 *** Commit your changes the usual way ("git add", "git commit", etc).
62 Changes in the Git repository do not immediately propagate to the
63 user-facing archive (what users see when they do `M-x list-packages').
64 That is done by deploying the archive, which happens automatically
65 once a day, and the changes are only reflected when the "Version:"
70 Each package should follow the ELPA packaging conventions, but there are
71 some differences due to the way the deployment script creates the packages
72 and the web-pages from this source code:
73 - Multi-file packages put the package metadata in the main <pkg-name>.el file
74 in the format used for single-file packages: the <pkg-name>-pkg.el file is
75 auto-generated from it.
76 - Every package should have both a "Version:" *and* a "Maintainer:".
77 - the "URL:" header can be used to specify the home page
78 of the package, if it's maintained externally.
79 - A "News:" section (or "NEWS" file) can/should be used to list the
80 user-visible changes of each version.
81 - The "Package-Type:" header can be used to force the type of package
82 created (can be either `simple' for single-file packages or `multi' for
83 tarballs). By default the type is decided based on whether there are
84 several Elisp files in the source.
85 - If you want some files to not be included in the tarball, you can
86 put a `.elpaignore' file in the root of your package directory, where you
87 can list patterns of files to ignore (this file is passed to tar's -X).
91 The easiest way to maintain and develop GNU Elpa packages is to just
92 edit them right here (in elpa.git). However, some maintainers may
93 prefer to use a dedicated repository or branch for the package. There
94 are two ways to do that: subtrees and externals.
96 Such packages should be listed in the `externals-list' file.
98 In both cases, a copy of the code is kept in the `elpa' repository
99 (not necessarily in the master branch) and should be sync'd with the
100 upstream every once in a while. This copy may include local changes,
101 although these should be kept to a minimum.
103 If know you don't want a local package, but don't know which of these
104 two options you prefere, then use a subtree.
108 In the `subtree' case, the copy of the code is kept here in the master
109 branch, inside its corresponding `packages/<pkg-name>' directory just
110 as if it were a local package.
112 In fact, a subtree package is essentially indistinguishable from a
113 local package. The only difference is that, instead of developing it
114 here, you do it in some remote repository and pull in the changes.
116 Instead of manually creating the directory, you should be able to use:
118 git subtree add --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
120 Later, when you make some changes to the remote and want to publish
121 them here, simply do:
123 git subtree pull --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
125 On older git versions "git subtree" might not be available. You can
126 try "git merge -s subtree", or just update git.
128 - <remote-repo> is the remote's url. If you've previously used "git
129 remote add", then this can be the remote's name.
130 - <remote-branch> is the branch you want to pull (probably "master").
132 If you want the local code to be slightly different from the remote,
133 simply commit further changes to it here. Of course, this may trigger
134 merge conflicts when you do a "subtree pull" in the future, so it's
135 best to avoid these local changes.
137 If someone makes changes to your package here on elpa.git and you want
138 to push them to your remote, it's easiest to just copy these changes
139 over to the remote repo. Trying to push a subtree with git is likely
142 **** When you're adding and pulling, DO NOT --SQUASH!!
144 Don't worry about flooding elpa.git's commit log with your package's
145 commit messages. Your package is part of elpa.git. Squashing doesn't
146 help and only gets in the way.
150 In the `external' case, the copy of the code is not kept here but in the
151 `externals/<pkg-name>' branch in the `elpa' repository.
153 You can check out all the external packages into the `packages' directory
158 You can check out a specific external PACKAGE into the `packages'
159 directory with these commands:
162 git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
164 If you already have a packages/PACKAGE directory with a previous
165 checkout, you can update it like this:
172 If you want to develop a package publicly prior to its first release (to
173 benefit from others' feedback, primarily), but not in an external repo,
175 - you can simply put "Version: 0" to indicate that this should not be
177 - or you can push to an "ephemeral" branch -- subject to rebase and eventual
178 removal upon finishing merge -- for the duration of the incubation.
182 ** To install all the packages "in place":
187 This compiles and generates autoloads for all the packages in the
188 packages/ directory. You can then add that directory, e.g. with:
190 (eval-after-load 'package
191 '(add-to-list 'package-directory-list ".../elpa/packages"))
193 ** To deploy the package repository as a remotely-accessible archive:
198 (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
200 ln -s ../elpa/GNUmakefile
201 admin/update-archive.sh
203 This deploys the packages to the staging/ directory (sibling of "build").
204 Unlike "make", this makes a full copy of the packages, tars up
205 multi-file packages, and doesn't byte-compile any files.
207 ** To access a deployed archive
209 To access the archive via HTTP, have a symlink (say) /var/www/packages
210 pointing to DEST/packages, and set up Emacs with
212 (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
214 You can also access the archive via normal file access. Such "local
215 archives" are useful for debugging:
217 (setq package-archives '(("local-elpa" . ".../elpa/packages")))
219 ** Notes specific to elpa.gnu.org
221 The way things are set up on this machine, we refresh the archive by
222 a cron job. You can do it by hand by logging in (access set up by FSF
227 admin/update-archive.sh
229 Which makes a full archive deployment, as discussed above. The symlink
230 /var/www/packages points to the staging package directory under
233 The Org mode dailies are also fetched and added by the script
234 admin/org-synch.sh, run as a cron job.
237 This file is part of GNU Emacs.
239 GNU Emacs is free software: you can redistribute it and/or modify
240 it under the terms of the GNU General Public License as published by
241 the Free Software Foundation, either version 3 of the License, or
242 (at your option) any later version.
244 GNU Emacs is distributed in the hope that it will be useful,
245 but WITHOUT ANY WARRANTY; without even the implied warranty of
246 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
247 GNU General Public License for more details.
249 You should have received a copy of the GNU General Public License
250 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
255 paragraph-separate: "[
\f]*$"