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: +

+ +

Are the Lisp files in some other directory than the root +directory of the repository?
Should we track some other branch than the default branch?
Do you have a separate file you use as a changelog?
Does your package provide a TeXinfo manual? The ELPA build can +both compile .texi files +and .org +files for you, so there is no need to track a .info file in +your repository.
Is it necessary to execute any special shell commands or Makefile +rules while building the package?
Is the main Lisp file of your project named something else +than after the name of your package (for a package FOO is +there a file FOO.el)?
Do you have any special preferences how we should generate the +package description for C-h P +(describe-package) and the website? By default we check +if there is a README.org file (including a new other +formats, but excluding Markdown). If none is found, or +if explicitly requested, we will use the contents of the ;;; +Commentary: section.

+ +

+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: +

+ +

Stefan Monnier <monnier [at] iro.umontreal.ca>
Philip Kaludercic <philipk [at] posteo.net>

+ +