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). 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.py][melpazoid.py]])
5. some elisp checks (in [[https://github.com/riscy/melpazoid/blob/master/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.
The license checker is currently very crude. The elisp checks are not foolproof,
sometimes opinionated, and may raise false positives.

* Usage
  You can [[https://github.com/riscy/melpazoid#fork-it-and-let-ci-do-the-work][fork it and let CI do the work]], or [[https://github.com/riscy/melpazoid#use-it-locally][use it locally]].
** Fork it and let CI do the work
   If you don't want to install this software or its dependencies, you are
   encouraged to fork this repository and let CI do the work. Then enable
   [[https://travis-ci.org][Travis-CI]] on your fork, or just open a pull request against this repository
   (I won't merge it). The eventual build information will report any issues.

   Your fork will need to point to the Emacs package you want to build, which
   can be done by modifying the [[https://github.com/riscy/melpazoid/blob/master/.travis.yml#L6][.travis.yml]] file in one of the following ways.
*** Test a recipe before you even open a pull request to MELPA
    Modify the ~env~ field and specify your clone URL and your recipe:
    #+begin_src yaml
    env: >-
      CLONE_URL=https://github.com/me/my-package-repo
      RECIPE='(my-package :repo "me/my-package-repo" :fetcher github)'
    #+end_src
    Note the apostrophes ~'~ around the RECIPE.
*** Test a MELPA pull request you've already opened
    Modify the ~env~ field and specify your open MELPA PR:
    #+begin_src yaml
    env: >-
      MELPA_PR_URL=https://github.com/melpa/melpa/pull/6713
    #+end_src
** 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 a MELPA PR
    #+begin_src bash
    MELPA_PR_URL=https://github.com/melpa/melpa/pull/6718 make
    #+end_src
*** Test a remote package
    #+begin_src bash
    CLONE_URL=https://github.com/riscy/shx-for-emacs \
        RECIPE='(shx :repo "riscy/shx-for-emacs" :fetcher github)' \
        make
    #+end_src
    Note the apostrophes ~'~ around the RECIPE.
*** Test a local package (work in progress)
    #+begin_src bash
    PKG_PATH=/path/to/package \
        PKG_NAME=package-name \
        make
    #+end_src