Minimally useful Github workflow for Emacs packages

Melpa is one of the most popular and probably the most accessible emacs package repository to publish to. All you need to do is add a ‘recipe’ to the melpa git repository by following the instructions.

They also have a few requirements that you need to adhere to:

• Your functions and variables should have adequate documentation, as determined by checkdoc, an emacs built-in.

• Your files should follow some elisp programming conventions, which is checked using the package-lint package.

• Your package should not throw any errors/warnings when byte-compiled

Now you can check all of these manually, and the contribution guidelines show exactly how to do that, but there’s a better way: using github workflows!

In fact, the melpa repository uses a similar workflow to see if your package is up to snuff.

The setup

We have two parts, an init.el file which sets up melpa, and the ci.yaml, which installs emacs, package-lint, and our package.

Both of these files should be in /.github/workflows.

init.el

(progn
  (require 'package)
  (push '("melpa" . "https://melpa.org/packages/") package-archives)
  (package-initialize)
  (unless (seq-find (lambda (e) (string= "melpa" (package-desc-archive (cadr e)))) package-archive-contents)
    (package-refresh-contents)))

ci.yml

This is where the actual workflow is defined: what base image we use, installing emacs and package-lint, running package lint and byte-compilation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

name: CI

on:
  pull_request:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - emacs: 27.1
            ts: false
            lint: true
          - emacs: snapshot
            ts: true
            lint: true
    steps:
    - uses: purcell/setup-emacs@master
      with:
        version: ${ matrix.emacs
    - uses: actions/checkout@v4

    - name: Install package-lint
      run: emacs -Q -l .github/workflows/init.el -batch
                    --eval "(package-install 'package-lint)"

    - name: Lint flexoki-themes
      run: emacs -Q -l .github/workflows/init.el -batch
                    -f package-lint-batch-and-exit
                    flexoki-themes.el

    - name: Byte-compile
      run: emacs -Q -l .github/workflows/init.el -batch
                    -L .
                    --eval "(setq byte-compile-error-on-warn t)"
                    -f batch-byte-compile
                    *.el

In the jobs.build.strategy.matrix.include you can add other emacs versions you want to test on, I’ve seen people use 24 a lot.

Instead of flexoki-themes use your own package name, obviously.

What to expect

The tick indicates that the workflow is successful, and a red cross would indicate that the workflow failed. You can click on them to see the result of the workflow.

If the workflow succeeds, your package will probably be accepted by MELPA.