melpazoid/README.org

melpazoid 🤖

• Usage
  • Add it to GitHub actions
  • Add it to a Travis build
  • Use it locally
    • Test an open MELPA PR
    • Test a recipe
    • Test a recipe for a package on your machine
    • Run in an unending loop

https://travis-ci.org/riscy/melpazoid.svg?branch=master

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. The ambition is checks that run in a "clean" environment, either through CI or through a container on your local machine.

This is a work in progress – feedback and pull requests are welcome (search for TODOs, raise an issue, whatever). Note my current aim is to make this code simpler before I make it any more complicated.

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, so you should always try to get those right. In normal circumstances 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

The best way to use melpazoid is to add it to your CI (GitHub actions, Travis, etc.), but you can also 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/.github/workflows/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.

Add it to a Travis build

If you use Travis, the following is an example .travis.yml that runs melpazoid on a recipe:

language: python
python: ['3.6']
install:
  - git clone https://github.com/riscy/melpazoid.git ~/melpazoid
  - pip install ~/melpazoid
env:
  # NOTE: set EXIST_OK to false if the package is not yet on MELPA:
  - RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' EXIST_OK=true
script:
  - make -C ~/melpazoid

remembering to modify RECIPE and EXIST_OK accordingly.

Use it locally

You will need Python ≥ 3.6 (and the requests package) 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:

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

Test a recipe

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

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.

Run in an unending loop

This currently only works in macOS; it monitors the clipboard for MELPA PR's, then automatically runs the checks.

make