MELPA consists of recipes, each describing one package in a dedicated repository. This document describes how to propose a new package for inclusion into MELPA.
Three contributor roles are involved in the maintenance of MELPA :
- MELPA maintainers
- They are responsible for reviewing new recipes and associated packages as well as keeping the system working.
- Recipe authors
- They responsible for submitting good recipes and maintaining them when the package is changed (e.g., renamed or deprecated).
- Package author
- They are responsible for writing Emacs Lisp packages of good quality.
We advise package authors to also take the recipe author role when possible.
In the following, package and recipe authors will find guidelines to help them prepare a package and its recipe for inclusion into MELPA. Please follow the guidelines as closely as possible to speed up the inclusion process. Guidelines are not strict and evaluated on a case by case basis given proper justification.
New recipe submissions should adhere to the following guidelines:
- Expect feedback
- Part of the review process is having a MELPA maintainers look at your package to make sure it will work in MELPA and the Emacs package system. Maintainers may provide comments which may or may not be blockers for addition to MELPA.
- One recipe per pull request
- If you have several packages to submit, open several pull requests. If the packages are very closely related and maintained in the same repository (see below for why it might not be a good idea), you might open only one pull request for them all; in this case, keep adding one recipe per commit.
- Reasonably innovative package
- MELPA provides a curated set of Emacs Lisp packages, not an exhaustive list of every single Emacs Lisp file ever created. By default, MELPA maintainers will reject packages that duplicate functionality provided by existing packages. Please try to improve existing packages instead of creating new ones when possible.
- Software Configuration Management (SCM)
- Upstream source must be stored in an authoritative Git or Mercurial SCM repository. EmacsWiki recipes are no longer accepted.
- Official repository
- Packages should be built from the official package repository. Forks of the official repository will not be accepted except in extreme circumstances.
- Dedicated SCM repository
- Keep each package in its own SCM (e.g., git) repository. This makes it possible to have a different version number for each package as MELPA stable looks at the SCM’s tags to assign version numbers to recipes.
- Quality
- Because we care about the quality of packages that are part of MELPA, MELPA maintainers review every recipe and its associated package. Please read and follow the guidelines below.
- Contact package author
- If you are not the original author or maintainer of the package you are submitting, please notify the authors prior to submitting and include them in the pull request process.
- Reasonably active maintainer
- Packages submitted should have a reasonably committed and active maintainer (at least, at the time they are submitted). MELPA is not intended to be a place to “dump” code, even if it works well at the time. Users should be able to expect that a package’s maintainer will make reasonable efforts to maintain it in the future. (Of course, “life happens,” so this is not a guarantee, and sometimes packages are transferred to new maintainers.)
- Recipe maintenance
- If the package author moves the upstream repository, then update the recipe too. If the package author transfers ownership to someone else and both the old and new location are on Github, then the package author should better use Github’s repository transfer mechanism to move the repository. This makes it easier for MELPA maintainers to verify that the move is legit. Otherwise, the package author should update the README at the old location with a link to the new location.
- GPL compatible license
- The package is released under a
GPL-Compatible Free Software License, preferably the
GNU General Public License (GPL) version 3. The license
boilerplate should be applied above the
;;; Commentaryof each source file. The repository should contain a LICENSE or COPYING file, formatted so that it can be detected by common tooling.
MELPA maintainers control the quality of each recipe and associated package. Please spend time following guidelines below as not doing so will delay the process.
- Coding style and conventions
- The Emacs Lisp files should follow the Emacs Lisp conventions and the Emacs Lisp Style Guide.
- Package metadata
- Package descriptions should adhere to the
package.elformat as specified by(info "(elisp) Packaging")documentation. More information on this format is provided by the marmalade package manual. - Use quality-checking tools
- Use flycheck, package-lint and flycheck-package to help you identify common errors in your package metadata. Use checkdoc to make sure that your package follows the conventions for documentation strings.
- Avoid long functions
- The longer a function the harder it is for a MELPA maintainer to understand what is happening and to give feedback. It is also much harder to point to a specific portion of the code we believe could be improved. Please spend time decomposing your long functions into smaller, well-named and documented, ones.
- Avoid change logs and readmes
- Files like these would only end up in an obscure installation directory where a user would never know to look when searching for information. Possible exceptions to this policy are .info files since these are automatically added to Emacs’ info index and the presence of interactive commands that would display the files.
- (optional) Tag commits to release
- To have a stable version
generated for your package simply tag the SCM repository using a
naming compatible with the
version-to-listfunction. The repository’s state of this tag will be used to generate the stable package.
Packages submitted to MELPA regularly suffer from the same problems, which delay review by several days or even weeks. Please double check this list before submitting your package:
- Please run quality-checking tools specified above (really, do it!).
- Please enable lexical binding by adding
-*- lexical-binding: t; -*-at the end of the first line of each Emacs Lisp file. If you want to know more about why you should always do that, read Chris Wellons Emacs’ blog posts (this post for example). - Please avoid defining a face that both
:inheritanother face and also override their attributes (e.g. by making them bold, underlined or inverse-video). The result could be really bad depending on user customizations. The best approach here is to simply:inheritthe faces, and leave the user to customise the rest. - Prefix function names with #’ (i.e., the special form
function) instead of just ’ (i.e., the special formquote) to tell the compiler this is a function reference. E.g.,(seq-filter #'evenp list). - MELPA only looks at the main
.elfile (or-pkg.elfile, if provided, though we discourage that). If you have different optional parts of a large package, each of which has different dependencies, then these should really be published as separate packages.
To submit a pull request to MELPA, you first have to fork and clone the MELPA repository. Then, you need to create a recipe file and test your recipe.
Create a file under the directory specified by
package-build-recipes-dir (default: recipes/ directory where
package-build was loaded). If you prefer, the interactive command
package-build-create-recipe in package-build/package-build.el will
guide you through this process. The filename should match the name of
the package’s provided feature.
See the recipe format section of the README for more information on the content of a recipe file. The package name must be the same as the filename.
Recipes should try to minimize the size of the resulting package by specifying only files relevant to the package.
Please test that the package builds properly by following the steps below.
Let <NAME> denote the filename of the new recipe. Build the recipe
via make recipes/<name>, or through pressing C-c C-c in the recipe
file buffer. Be sure that the emacs binary on your PATH is at
least version 23, or set $EMACS_COMMAND to the location of a
suitable binary.
If the repository contains tags for releases, confirm that the correct
version is detected by running STABLE=t make recipes/<NAME>. The
version detection can be adjusted by specifying :version-regexp in
the recipe (see recipe format in the README).
Test that the package installs properly by running
package-install-file from within Emacs and specifying the newly
built package in the directory specified by
package-build-archive-dir (default: packages/ directory where
package-build was loaded). Entering “yes” when prompted after
pressing C-c C-c in the recipe buffer also works.
You can optionally run a sandboxed Emacs in which locally-built packages will be available for installation along with those already in MELPA:
EMACS_COMMAND=/path/to/emacs make sandbox INSTALL=<name>From within Emacs, install and test your package as appropriate. This is a useful way to discover missing dependencies.
Create a dedicated pull request branch in your clone of the MELPA repository and push this branch to your fork. Finally, go to the MELPA repository and open the pull request.
Include the following information in the pull request description:
- a brief summary of what the package does;
- a direct link to the package repository;
- your association with the package (e.g., are you the maintainer? have you contributed? do you just like the package a lot?);
- relevant communications with the upstream package maintainer (e.g.,
package.elcompatibility changes that you have submitted).
Consider the hub command-line utility by defunkt which helps simplify this process.
MELPA maintainers spend a lot of time reviewing proposed packages and also have quite a lot of other non-MELPA-related activities. Please be patient as it might take a week (sometimes several) before one starts having a look at your pull request.
If you were asked to make several changes, then you should explicitly mention everything that you have fixed, and possibly even link to the relevant commits. One way of doing that is to mention the MELPA pull request in every commit addressing one of the raised points: just write `melpa/melpa#N` in each commit message where `N` is the pull request number.
You can help MELPA maintainers take care of pull requests much faster by paying real attention to the quality of your package (see above for some quality checks and links). If you feel for it, you can also take another pull request and give feedback to the author.