melpazoid 🤖

melpazoid is a bundle of scripts for testing Emacs packages, primarily submissions to MELPA. I’ve been using this to help check MELPA pull requests.

(Note: it is not necessary to use melpazoid to get your package on MELPA, but maybe it will help.)

The ambition is checks that run in a “clean” environment, either through CI or through a container on your local machine. Feedback and pull requests are welcome (search for TODOs, raise an issue)

The checks are a combination of:

1. byte-compile-file
2. checkdoc
3. package-lint
4. a license checker (in melpazoid.py)
5. some elisp checks (in melpazoid.el)

1–4 are on the MELPA checklist. Normally the build will exit with a failure if there is any byte-compile or package-lint error – leeway is given for any warning. The license checker (4) is currently very crude. The elisp checks (5) are not foolproof, sometimes opinionated, and may raise false positives.

Usage

You can add melpazoid to your CI and use it locally.

Add it to GitHub actions

The very easiest is if your package is hosted on GitHub. Just run the following from your project root:

mkdir -p .github/workflows
curl -o .github/workflows/melpazoid.yml \
  https://raw.githubusercontent.com/riscy/melpazoid/master/melpazoid.yml

then edit the file (.github/workflows/melpazoid.yml) and change the values of RECIPE and EXIST_OK to fit. Instructions are in the file.

Use it locally

You will need Python ≥ 3.6 and Docker. An image will be built with (hopefully) all of your requirements installed. By default, it will be run with no network access. The output scroll will report any discovered issues.

Test an open MELPA PR

If you’ve already opened a PR against MELPA, you can use the Makefile.

MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make

Test a recipe

If you just have a recipe, you can use the Makefile:

RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' make

Note the apostrophes around the RECIPE. You can also test a specific branch:

RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github :branch "develop")' make

Test a recipe for a package on your machine

Use the Makefile:

RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' \
    LOCAL_REPO='~/my-emacs-packages/shx-for-emacs' make

Instead of cloning from riscy/shx-for-emacs in this example, melpazoid will use the files in LOCAL_REPO.

Only test a package’s licenses

If you only wish to use melpazoid’s (very basic) license checks, refer to the following examples:

python3 melpazoid/melpazoid.py --license ../melpa/recipes/magit  # a recipe file
python3 melpazoid/melpazoid.py --license --recipe='(shx :repo "riscy/shx-for-emacs" :fetcher github)'

Run in an unending loop

Just run melpazoid.py directly, or use make by itself.