-Copyright (C) 2010-2011, 2014 Free Software Foundation, Inc.
+Copyright (C) 2010-2011, 2014, 2015 Free Software Foundation, Inc.
See the end of the file for license conditions.
-This branch contains the sources, deployment scripts, and auxilliary
+This branch contains the sources, deployment scripts, and auxiliary
files for the Emacs Lisp package archive (elpa.gnu.org).
This file explains the branch layout, how to add and edit packages,
code making it to GNU ELPA, and simply update the "version" when you want to
release the new code.
-** To add a package:
+** To add a package: (submission, submit)
-*** Add a simple (1-file) package as packages/NAME/NAME.el.
+Adding a basic package is very simple. There are thorough
+instructional, but the gist is that you:
-The file needs to follow the usual coding conventions (most importantly
-start with ";;; <file> --- <description>") and have a "Version:" and
-"Maintainer:" pseudo-header.
+1. Notify emacs-devel@gnu.org.
+2. Place all files inside `packages/<pkg-name>/'.
+3. `git add', `git commit' and `git push'.
-*** Add a multi-file package as a directory, packages/NAME.
+If you don't have push access to the repository, someone will do steps
+2 and 3 for you.
-It needs to have a file named packages/NAME/NAME.el which follows the same
-rules as above.
+*** Notify emacs-devel@gnu.org
+
+There is no approval process for GNU Elpa packages. Still,
+you must send an email to emacs-devel for several reasons:
+
+- Notifying other developers;
+- Making sure the package doesn't break FSF rules;
+- Checking if the package is not reinventing the wheel;
+- Ensuring that first-time developers are doing it right.
+
+Before doing anything, please ensure your package follows the
+conventions described in the `** Format' section. Then, send an email
+to the list with the subject:
+ [ELPA] New package: <pkg-name>
+
+Start your message with an explanation about the package. A
+copy-paste of the package's Summary and Commentary is perfectly fine
+here, but you can write more or less than that if you'd like.
+
+At the bottom of the message contents include the changes you're going
+to make (the patch). For a single-file package this can be the
+package file itself instead of the patch. If you prefer (and if you
+have push access), you can push your changes to a branch called
+`scratch/<pkg-name>', and mention the branch in your message.
+
+After 48h, or once any issues have been addressed, someone will push
+your changes for you. You should probably also subscribe to
+emacs-devel@gnu.org, since that's where we discuss about GNU Elpa, and
+to bug-gnu-emacs@gnu.org, since that's where people will report bugs
+about your package.
+
+*** Add a simple (1-file) package as packages/<pkg-name>/<pkg-name>.el.
+
+The file needs to follow the usual coding conventions (most
+importantly start with ";;; <file> --- <description>") and have a
+"Version:" and "Maintainer:" pseudo-header (see the "Format"
+subsection below).
+
+For some examples, see
+ (info "(elisp) Simple Packages")
+
+*** Add a multi-file package as a directory, packages/<pkg-name>.
+
+It needs to have a file named packages/<pkg-name>/<pkg-name>.el which follows the
+same rules as above.
+
+It additionally follows the same guidelines described in
+ (info "(elisp) Multi-file Packages")
+with the exception that it is not a tar package (it's a plain
+directory) and it must not contain a "<pkg-name>-pkg.el" file (this
+will be created for you).
*** Commit your changes the usual way ("git add", "git commit", etc).
Each package should follow the ELPA packaging conventions, but there are
some differences due to the way the deployment script creates the packages
and the web-pages from this source code:
-- Multi-file packages put the package metadata in the main <pkg>.el file
- in the format used for single-file packages: the <pkg>-pkg.el file is
+- Multi-file packages put the package metadata in the main <pkg-name>.el file
+ in the format used for single-file packages: the <pkg-name>-pkg.el file is
auto-generated from it.
- Every package should have both a "Version:" *and* a "Maintainer:".
- the "URL:" header can be used to specify the home page
** External branches
-Some packages are maintained in external branches. These should be
-appropriately listed in the `externals-list' file.
-There are two different cases: subtrees and externals.
+The above instructions are enough to add regular packages, those that
+are maintained primarily here in the repository. The instructions
+below are for those maintainers who prefer to use a dedicated
+repository or branch for the package.
+
+There are two ways to do that: subtrees and externals.
+
+Either way, such packages should always be listed in the
+`externals-list' file.
+
+In both cases, a copy of the code is kept in the `elpa' repository
+(not necessarily in the master branch) and should be sync'd with the
+upstream every once in a while. This copy may include local changes,
+although these should be kept to a minimum.
+
+If know you don't want a local package, but don't know which of these
+two options you prefer, then use a subtree.
+
+*** Subtrees
+
+In the `subtree' case, the copy of the code is kept here in the master
+branch, inside its corresponding `packages/<pkg-name>' directory just
+as if it were a local package.
+
+In fact, a subtree package is essentially indistinguishable from a
+local package. The only difference is that, instead of developing it
+here, you do it in some remote repository and pull in the changes.
+
+Instead of manually creating the directory, you should be able to use:
+
+ git subtree add --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
+
+Later, when you make some changes to the remote and want to publish
+them here, simply do:
+
+ git subtree pull --prefix=packages/<pkg-name> <remote-repo> <remote-branch>
+
+On older git versions "git subtree" might not be available. You can
+try "git merge -s subtree", or just update git.
+
+- <remote-repo> is the remote's URL. If you've previously used "git
+ remote add", then this can be the remote's name.
+- <remote-branch> is the branch you want to pull (probably "master").
+
+If you want the local code to be slightly different from the remote,
+simply commit further changes to it here. Of course, this may trigger
+merge conflicts when you do a "subtree pull" in the future, so it's
+best to avoid these local changes.
+
+If someone makes changes to your package here on elpa.git and you want
+to push them to your remote, it's easiest to just copy these changes
+over to the remote repo. Trying to push a subtree with git is likely
+to induce headache.
+
+**** When you're adding and pulling, DO NOT --SQUASH!!
-In both cases, a copy of the code is kept in the `elpa' repository and
-should be sync'd with the upstream every once in a while. This copy may
-include local changes, tho ideally these should be kept to a minimum.
+Don't worry about flooding elpa.git's commit log with your package's
+commit messages. Your package is part of elpa.git. Squashing doesn't
+help and only gets in the way.
-In the `subtree' case, the copy of the code is kept here in the
-corresponding `packages/<pkg>' directory. You should be able to "git
-merge -s subtree" from the upstream branch.
+*** Externals
In the `external' case, the copy of the code is not kept here but in the
-`externals/<pkg>' branch in the `elpa' repository.
+`externals/<pkg-name>' branch in the `elpa' repository.
You can check out all the external packages into the `packages' directory
with the command:
** To deploy the package repository as a remotely-accessible archive:
git clone .../elpa
+ (cd elpa; git clone .../emacs) #If you want to generate :core packages.
mkdir build
cd build
(cd ../elpa; git log --format=%H | tail -n 1) >.changelog-witness