https://github.com/riscy/melpazoid

A bundle of CI scripts for testing Emacs packages, primarily submissions to MELPA.
https://github.com/riscy/melpazoid

Last synced: 5 days ago
JSON representation

A bundle of CI scripts for testing Emacs packages, primarily submissions to MELPA.

• Host: GitHub
• URL: https://github.com/riscy/melpazoid
• Owner: riscy
• License: gpl-3.0
• Created: 2020-02-22T18:05:24.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2024-01-28T18:24:50.000Z (9 months ago)
• Last Synced: 2024-02-01T10:07:20.458Z (9 months ago)
• Language: Python
• Homepage:
• Size: 299 KB
• Stars: 77
• Watchers: 8
• Forks: 15
• Open Issues: 7
• Metadata Files:
  • Readme: README.org
  • License: LICENSE

Awesome Lists containing this project

README

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