CONTRIBUTING.org

Contributing a new recipe to MELPA

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 are 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.

What to know before opening a pull request

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 one of your packages is a dependency of the others, open the pull request for that one first. Avoid circular dependencies.

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 ;;; Commentary of each source file. The repository should contain a LICENSE or COPYING file, formatted so that it can be detected by common tooling.

Making your package ready for inclusion

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.el format 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, within reason.

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-list function. The repository’s state of this tag will be used to generate the stable package.

Fixing typical problems

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 :inherit another 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 :inherit the 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 form quote) to tell the compiler this is a function reference. E.g., (seq-filter #'evenp list).
• MELPA only looks at the main .el file (or -pkg.el file, 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.

Preparing a pull request to MELPA

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 recipe file

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.

Test your recipe

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 with C-c C-c (M-x package-build-current-recipe) in the recipe file buffer.

If the repository contains tags for releases, confirm that the correct version is detected by running MELPA_CHANNEL=stable 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:

make sandbox INSTALL=<NAME>

From within Emacs, install and test your package as appropriate. This is a useful way to discover missing dependencies.

Opening a pull request

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. The pull request description will contain a template to help guide you through any other details you must provide.

Consider the hub command-line utility by defunkt which helps simplify this process.

Waiting for reviews and taking feedback into account

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. Also be aware that the maintainers try to divide reviewing time fairly between authors; you can help them by limiting the number of pull requests you have open at once.

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.