Make debbugs-newest-bugs more robust
[gnu-emacs-elpa] / README
1 Copyright (C) 2010-2011, 2014, 2015 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 auxiliary
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: (submission, submit)
38
39 Adding a basic package is very simple. There are thorough
40 instructions below, but the gist of it is that you:
41
42 1. Notify emacs-devel@gnu.org.
43 2. Place all files inside `packages/<pkg-name>/'.
44 3. `git add', `git commit' and `git push'.
45
46 If you don't have push access to the repository, someone will do steps
47 2 and 3 for you.
48
49 *** Notify emacs-devel@gnu.org
50
51 There is no approval process for GNU Elpa packages. Still,
52 you must send an email to emacs-devel for several reasons:
53
54 - Notifying other developers;
55 - Making sure the package doesn't break FSF rules;
56 - Checking if the package is not reinventing the wheel;
57 - Ensuring that first-time developers are doing it right.
58
59 Before doing anything, please ensure your package follows the
60 conventions described in the `** Format' section. Then, send an email
61 to the list with the subject:
62 [ELPA] New package: <pkg-name>
63
64 Start your message with an explanation about the package. A
65 copy-paste of the package's Summary and Commentary is perfectly fine
66 here, but you can write more or less than that if you'd like.
67
68 At the bottom of the message contents include the changes you're going
69 to make (the patch). For a single-file package this can be the
70 package file itself instead of the patch. If you prefer (and if you
71 have push access), you can push your changes to a branch called
72 `scratch/<pkg-name>', and mention the branch in your message.
73
74 After 48h, or once any issues have been addressed, someone will push
75 your changes for you. You should probably also subscribe to
76 emacs-devel@gnu.org, since that's where we discuss about GNU Elpa, and
77 to bug-gnu-emacs@gnu.org, since that's where people will report bugs
78 about your package.
79
80 *** Add a simple (1-file) package as packages/<pkg-name>/<pkg-name>.el.
81
82 The file needs to follow the usual coding conventions (most
83 importantly start with ";;; <file> --- <description>") and have a
84 "Version:" and "Maintainer:" pseudo-header (see the "Format"
85 subsection below).
86
87 For some examples, see
88 (info "(elisp) Simple Packages")
89
90 *** Add a multi-file package as a directory, packages/<pkg-name>.
91
92 It needs to have a file named packages/<pkg-name>/<pkg-name>.el which follows the
93 same rules as above.
94
95 It additionally follows the same guidelines described in
96 (info "(elisp) Multi-file Packages")
97 with the exception that it is not a tar package (it's a plain
98 directory) and it must not contain a "<pkg-name>-pkg.el" file (this
99 will be created for you).
100
101 *** Commit your changes the usual way ("git add", "git commit", etc).
102
103 Changes in the Git repository do not immediately propagate to the
104 user-facing archive (what users see when they do `M-x list-packages').
105 That is done by deploying the archive, which happens automatically
106 once a day, and the changes are only reflected when the "Version:"
107 header changes.
108
109 ** Format
110
111 Each package should follow the ELPA packaging conventions, but there are
112 some differences due to the way the deployment script creates the packages
113 and the web-pages from this source code:
114 - Multi-file packages put the package metadata in the main <pkg-name>.el file
115 in the format used for single-file packages: the <pkg-name>-pkg.el file is
116 auto-generated from it.
117 - Every package should have both a "Version:" *and* a "Maintainer:".
118 - the "URL:" header can be used to specify the home page
119 of the package, if it's maintained externally.
120 - A "News:" section (or "NEWS" file) can/should be used to list the
121 user-visible changes of each version.
122 - The "Package-Type:" header can be used to force the type of package
123 created (can be either `simple' for single-file packages or `multi' for
124 tarballs). By default the type is decided based on whether there are
125 several Elisp files in the source.
126 - If you want some files to not be included in the tarball, you can
127 put a `.elpaignore' file in the root of your package directory, where you
128 can list patterns of files to ignore (this file is passed to tar's -X).
129
130 ** External branches
131
132 The above instructions are enough to add regular packages, those that
133 are maintained primarily here in the repository. The instructions
134 below are for those maintainers who prefer to use a dedicated
135 repository or branch for the package.
136
137 There are two ways to do that: subtrees and externals.
138
139 Either way, such packages should always be listed in the
140 `externals-list' file.
141
142 In both cases, a copy of the code is kept in the `elpa' repository
143 (not necessarily in the master branch) and should be sync'd with the
144 upstream every once in a while. This copy may include local changes,
145 although these should be kept to a minimum.
146
147 If know you don't want a local package, but don't know which of these
148 two options you prefer, then use a subtree.
149
150 *** Subtrees
151
152 In the `subtree' case, the copy of the code is kept here in the master
153 branch, inside its corresponding `packages/<pkg-name>' directory just
154 as if it were a local package.
155
156 In fact, a subtree package is essentially indistinguishable from a
157 local package. The only difference is that, instead of developing it
158 here, you do it in some remote repository and pull in the changes.
159
160 Instead of manually creating the directory, you should be able to use:
161
162 git subtree add --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
163
164 Later, when you make some changes to the remote and want to publish
165 them here, simply do:
166
167 git subtree pull --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
168
169 On older git versions "git subtree" might not be available. You can
170 try "git merge -s subtree", or just update git.
171
172 - <remote-repo> is the remote's URL. If you've previously used "git
173 remote add", then this can be the remote's name.
174 - <remote-branch> is the branch you want to pull (probably "master").
175
176 If you want the local code to be slightly different from the remote,
177 simply commit further changes to it here. Of course, this may trigger
178 merge conflicts when you do a "subtree pull" in the future, so it's
179 best to avoid these local changes.
180
181 If someone makes changes to your package here on elpa.git and you want
182 to push them to your remote, it's easiest to just copy these changes
183 over to the remote repo. Trying to push a subtree with git is likely
184 to induce headache.
185
186 **** When you're adding and pulling, DO NOT --SQUASH!!
187
188 Don't worry about flooding elpa.git's commit log with your package's
189 commit messages. Your package is part of elpa.git. Squashing doesn't
190 help and only gets in the way.
191
192 *** Externals
193
194 In the `external' case, the copy of the code is not kept here but in the
195 `externals/<pkg-name>' branch in the `elpa' repository.
196
197 You can check out all the external packages into the `packages' directory
198 with the command:
199
200 make externals
201
202 You can check out a specific external PACKAGE into the `packages'
203 directory with these commands:
204
205 cd packages
206 git clone --reference .. --single-branch --branch externals/PACKAGE $(git config remote.origin.url) PACKAGE
207
208 If you already have a packages/PACKAGE directory with a previous
209 checkout, you can update it like this:
210
211 cd packages/PACKAGE
212 git pull
213
214 ** Public incubation
215
216 If you want to develop a package publicly prior to its first release (to
217 benefit from others' feedback, primarily), but not in an external repo,
218 you have 2 choices:
219 - you can simply put "Version: 0" to indicate that this should not be
220 released yet.
221 - or you can push to an "ephemeral" branch -- subject to rebase and eventual
222 removal upon finishing merge -- for the duration of the incubation.
223
224 * DEPLOYMENT
225
226 ** To install all the packages "in place":
227
228 make externals
229 make
230
231 This compiles and generates autoloads for all the packages in the
232 packages/ directory. You can then add that directory, e.g. with:
233
234 (eval-after-load 'package
235 '(add-to-list 'package-directory-list ".../elpa/packages"))
236
237 ** To deploy the package repository as a remotely-accessible archive:
238
239 git clone .../elpa
240 (cd elpa; git clone .../emacs) #If you want to generate :core packages.
241 mkdir build
242 cd build
243 (cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness
244 ln -s ../elpa/admin
245 ln -s ../elpa/GNUmakefile
246 admin/update-archive.sh
247
248 This deploys the packages to the staging/ directory (sibling of "build").
249 Unlike "make", this makes a full copy of the packages, tars up
250 multi-file packages, and doesn't byte-compile any files.
251
252 ** To access a deployed archive
253
254 To access the archive via HTTP, have a symlink (say) /var/www/packages
255 pointing to DEST/packages, and set up Emacs with
256
257 (setq package-archives '(("new-elpa" . "http://foo.com/packages")))
258
259 You can also access the archive via normal file access. Such "local
260 archives" are useful for debugging:
261
262 (setq package-archives '(("local-elpa" . ".../elpa/packages")))
263
264 ** Notes specific to elpa.gnu.org
265
266 The way things are set up on this machine, we refresh the archive by
267 a cron job. You can do it by hand by logging in (access set up by FSF
268 admins), and
269
270 su elpa
271 cd ~elpa/build
272 admin/update-archive.sh
273
274 Which makes a full archive deployment, as discussed above. The symlink
275 /var/www/packages points to the staging package directory under
276 /home/elpa/.
277
278 The Org mode dailies are also fetched and added by the script
279 admin/org-synch.sh, run as a cron job.
280
281 \f
282 This file is part of GNU Emacs.
283
284 GNU Emacs is free software: you can redistribute it and/or modify
285 it under the terms of the GNU General Public License as published by
286 the Free Software Foundation, either version 3 of the License, or
287 (at your option) any later version.
288
289 GNU Emacs is distributed in the hope that it will be useful,
290 but WITHOUT ANY WARRANTY; without even the implied warranty of
291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
292 GNU General Public License for more details.
293
294 You should have received a copy of the GNU General Public License
295 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
296
297 \f
298 Local variables:
299 mode: outline
300 paragraph-separate: "[ \f]*$"
301 end: