ELPA

Contributing to ELPA

This page explains the process of how to contribute a package to GNU or NonGNU ELPA.

Preliminaries

GNU ELPA and NonGNU ELPA are the default, official package archives for GNU Emacs. The difference between the two archives is that for packages on GNU ELPA, all contributors to the package are required to sign the FSF copyright assignment. For that reason, packages on GNU ELPA are regarded to be part of Emacs, and are in a position that they could be included in Emacs at some point.

Packages have to be published under a GPL compatible license, ideally GPLv3+, just like Emacs itself.

Beyond this, there are no substantial differences between the two package archives. If possible, we always prefer if packages are submitted to GNU ELPA.

Conditions

While we are in principle open to all kinds of packages, there are some hard and soft criteria to consider.

The main criterion is that your package has to be fully functional on a system using only free software. This doesn't mean that you are not allowed to have support for nonfree systems, but that the core functionality of your package may not depend on non-essential proprietary components.

As a positive example, consider the built-in library browse-url, used to open a URL in a browser outside of Emacs. While the package does have support for nonfree operating systems and browsers, users on a fully free system are neither disadvantaged nor encouraged to use nonfree browsers.

Almost all packages should be able to satisfy this. The exceptions include packages that are explicitly created to interact with proprietary programs, for which there is no free software substitute.

Note that for very well known proprietary programs, exceptions can be made (for instance matlab-mode). Also keep in mind that network services aren't free or nonfree, which means that we won't reject a package because the server source code is not published under a free license (for instance excorporate). That being said, we are not interested in adding Service as a Software Substitute-type packages. In any case, this is decided on a case-by-case basis, so please reach out early on if you have concerns.

The other hard criterion for packages submitted to GNU ELPA specifically is that all significant past and present contributors have signed the FSF copyright assignment. If you or one of your contributors have not done so, you can send an email to emacs-devel@gnu.org or directly to the Emacs maintainers, to request a copyright form.

For the ELPA build server to be able to handle your package, it has to follow the packaging conventions, which include the specification of a version number, all dependencies, and an author/maintainer with an email address.

If your package satisfies these requirements, there is no objection, in principle, to adding the package to the archive. Nevertheless, the following soft criteria can influence whether submitting a package makes sense:

Is the code quality acceptable?
As Emacs is easily introspectable, packages frequently serve an educational purpose. Many users gather their first real-world experience with Emacs Lisp by reading and modifying the packages they use. For that reason it is important that the code quality can serve as an example. If you are concerned about this, do not worry, other contributors and maintainers are more than glad to help! Reading the Tips and Conventions chapter of the Elisp manual might also help.
Is a new package the right approach?
If you are extending the functionality of an existing package, have you contacted the maintainer of said package to hear if they think your contribution would be worth upstreaming? Perhaps adding the feature directly to Emacs can simplify the implementation?
Does the package constitute a significant contribution?
If your package only defines a single, small function of a few lines, it might not be worth the effort to package. Keep in mind that every package constitutes a security risk if the maintainer's access to the repository gets compromised.
Are the dependencies necessary?
If possible, it is nice if packages can avoid dependencies they can get by without. Just as before, dependencies are a latent security risk (that are especially attractive targets of supply chain compromises). They also make it more difficult for users who cannot access ELPA directly, as they have to download packages by hand, and install them using package-install-file. Furthermore, superficial extensions that only provide convenience for the maintainer introduce fragmentation that makes it more difficult for otherwise experienced Lisp hackers to read and modify your code. Package for GNU ELPA should avoid depending on packages from NonGNU ELPA, to avoid unnecessary difficulties if the package were to be added to Emacs itself.
Is the package a good citizen?
It is nice to try to respect user preferences by implementing existing interfaces and trying to avoid surprises in general. For instance, just installing the package shouldn't modify the global state beyond loading definitions and some basic initialization (e.g. a major mode might want to add an entry to auto-mode-alist), but a theme or a global minor mode should not enable itself right away!
Do you provide a good description?
Users can find out about a package before installing it using C-h P (describe-package). Next to package metadata, this includes a description of the package. You can provide a succinct description of the package via a README file or the ;;; Commentary: section of your main Lisp file. This description should provide a standalone explanation of what utility the package provides and what the entry points of the package are (major modes, minor modes, commands, user options, etc.). You do not have to explain how to install the package, as the package manager takes care of that.
Are you interested in maintaining the package long term?
If you are not certain about whether you want to take on the responsibility for taking care of a package, be it because your interest in Emacs is not that deep or because you do not have the day-to-day time to respond to issues and patches, you might want to think twice about submitting a package. Alternatively, you could try to find people willing to help you out with maintenance, or again look to contribute your changes to an existing project, that possibly has more than one maintainer.
Do you have a good package name?
Ideally, your package name should give the user a rough idea of what functionality your package provides: Is it a major or minor mode (ends with -mode) or does it extend some other well known package (begins with the same prefix)? At the same time a good name finds a balance between being too generic and being quirky. The first risks framing the package as authoritative and difficult to find on the WWW using search engines, while the latter can be confusing, difficult to pronounce or alienating (remember that not everyone shares the same sense of humor or cultural references).

If these soft criteria aren't satisfied, then this is not a reason to reject a package. We understand if the package maintainer hasn't had the time to address these yet/has strong reasons to decide otherwise, as long as our preferences are acknowledged. If you have any questions, don't hesitate to reach out to emacs-devel@gnu.org or any of the maintainers mentioned below.

Submission

To submit a package to GNU or NonGNU ELPA, all you have to do is to send an email to the emacs-devel@gnu.org mailing list. Your message should include a brief description of the package, a link to a public Git repository that you plan to use and an indication if you prefer to add your package to GNU ELPA or NonGNU ELPA. If you do not have a Git repository yet, please consider an ethical Git forge. If you are submitting the package to GNU ELPA, please mention if all contributors have signed the FSF copyright assignment. If you have any specific comments on the criteria mentioned above, feel free to mention them.

To avoid the delay of your email address having to be approved by an administrator, please sign up for the mailing list before you send your first message to the mailing list. You can disable mail delivery, if you do not wish to follow the discussions on the mailing list. During this process, as with any exchange on official GNU communication channels, please keep the GNU Kind Communications Guidelines and general netiquette in mind.

Furthermore, if any of the following applies to your package, please mention it in your message:

If you are interested in the technical details, you can find out more about how the ELPA build server works in the GNU ELPA repository. The package specification format described in the README file is a more general version of the package specifications used by package-vc.

Volunteers on the mailing list will take care of your request from this point on. In principle, everyone reading along might have suggestions or comments that you should take seriously, as they are offering their time to help you and your users.

As soon as all matters are settled, someone with access to the ELPA repositories can add your package to the archive. From this point on please refrain from force-pushing changes that change your Git history, as the ELPA build server will regularly mirror the default branch of your repository, and merge conflicts have to be resolved manually. If this is an issue for you, please contact the ELPA maintainers.

Distribution

Upon addition, the ELPA build server will determine the last release by determining the last commit that bumped the Version pseudo-header in the main file: 

;; Author: J. R. Hacker <jrh@example.com>
;; Author: Alyssa P. Hacker <alyssa@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
;; Keywords: multimedia, hypermedia
;; URL: https://example.com/superfrobnicate.git

ELPA regularly synchronizes the repository state, and will release new version of the package whenever a new commit is detected that modifies the same Version header. An exception here are pre-release versions, such as 1.5-pre or 5beta1, which suppress the server from building a new tarball. You can look up the list of non-numeric version identifiers in the variable version-regexp-alist.

Also note the Maintainer pseudo-header in the example above: Please use a functioning email address here, so that both the ELPA maintainers and your users can contact you.

The ELPA build server checks for the existence of a .elpaignore file in the root directory of your repository, that you can use to specify to exclude files you think shouldn't be distributed in the release tarball (build scripts, assets, etc.).

All packages on GNU ELPA and NonGNU ELPA get a homepage on elpa.gnu.org and elpa.nongnu.org respectively. That homepage includes the package description, a list of recent tarball releases, and — if configured — a preview of the changelog and a HTML rendered manual. The GNU ELPA-devel (or NonGNU ELPA-devel) archives re-build on each commit. You can use these to preview how the ELPA build server will process your package before releasing a package, without having to set up the build server locally on your machine.

The ELPA maintainers are looking forward to your contributions, and are happy to hear from you if you have any questions regarding ELPA or this website: