melpazoid

melpazoid copied to clipboard

#+TITLE: melpazoid 🤖 #+OPTIONS: toc:3 author:t creator:nil num:nil #+AUTHOR: Chris Rayner #+EMAIL: [email protected]

[[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.