melpazoid/README.org

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

[[https://github.com/riscy/melpazoid/actions][https://github.com/riscy/melpazoid/workflows/test/badge.svg]]

/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]].

(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 ([[https://github.com/riscy/melpazoid/search?q=TODO&unscoped_q=TODO][search for TODO]]s, [[https://github.com/riscy/melpazoid/issues][raise an issue]])

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]]. 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:
   #+begin_src bash
   mkdir -p .github/workflows
   curl -o .github/workflows/melpazoid.yml \
     https://raw.githubusercontent.com/riscy/melpazoid/master/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.
** 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.
    #+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_src
*** Run in an unending loop
    Just run melpazoid.py directly, or use ~make~ by itself.