melpazoid/README.org

#+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).

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 the Makefile.
    #+begin_src bash
    MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make
    #+end_src
*** Test a recipe
    If you just have a recipe, you can use the Makefile:
    #+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
    Use the Makefile:
    #+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~.
*** Only test a package's licenses
    If you only wish to use melpazoid's (very basic) license checks, refer to the
    following examples:

    #+begin_src bash
    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)'
    #+end
*** Run in an unending loop
    Just run melpazoid.py directly, or use ~make~ by itself.