#+TITLE: melpazoid 🤖
#+OPTIONS: toc:3 author:t creator:nil num:nil
#+AUTHOR: Chris Rayner
#+EMAIL: dchrisrayner@gmail.com

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

/melpazoid/ is a bundle of scripts for testing Emacs packages, primarily
submissions to [[https://github.com/melpa/][MELPA]]. I've been using this to help check MELPA [[https://github.com/melpa/melpa/pulls][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 ([[https://github.com/riscy/melpazoid/search?q=TODO&unscoped_q=TODO][search for
TODO]]s, [[https://github.com/riscy/melpazoid/issues][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. [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Byte-Compilation.html#Byte-Compilation][byte-compile-file]]
2. [[https://www.emacswiki.org/emacs/CheckDoc][checkdoc]]
3. [[https://github.com/purcell/package-lint][package-lint]]
4. a license checker (in [[https://github.com/riscy/melpazoid/blob/master/melpazoid/melpazoid.py][melpazoid.py]])
5. some elisp checks (in [[https://github.com/riscy/melpazoid/blob/master/melpazoid/melpazoid.el][melpazoid.el]])

1--4 are on the [[https://github.com/melpa/melpa/blob/master/.github/PULL_REQUEST_TEMPLATE.md][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:
   #+begin_src bash
   mkdir -p .github/workflows
   curl -o .github/workflows/melpazoid.yml \
     https://raw.githubusercontent.com/riscy/melpazoid/master/.github/workflows/melpazoid.yml
   #+end_src
   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:
   #+begin_src yaml
   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
   #+end_src
   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:
    #+begin_src bash
    MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make
    #+end_src
*** Test a recipe
    #+begin_src bash
    RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' make
    #+end_src
    Note the apostrophes around the RECIPE. You can also test a specific branch:
    #+begin_src bash
    RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github :branch "develop")' make
    #+end_src
*** Test a recipe for a package on your machine
    #+begin_src bash
    RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' \
        LOCAL_REPO='~/my-emacs-packages/shx-for-emacs' make
    #+end_src
    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.
    #+begin_src bash
    make
    #+end_src