The Zanc Report

Forgejo, AGit, and Pull Request Templates

2026-02-21T00:00:00Z

I've raised a few PRs against the Guix Codeberg repository recently, and each time I've done so with Forgejo's AGit workflow. This workflow is pretty nice, and allows me to raise a PR entirely from within Emacs. To do that, I've been using this code in my Emacs config to add an extra option to the magit-push transient to use the AGit flow to push to the upstream branch:

(transient-define-suffix magit-push-current-agit (source target args)
  :if #'magit-get-current-branch
  :description (lambda () (concat (magit-push--upstream-description) " (agit)"))
  (interactive
   (let ((source (or (magit-get-current-branch)
                     (user-error "No branch is checked out"))))
     (list source
           (magit-get-upstream-branch source)
           (magit-push-arguments))))

  (magit-push-refspecs
   (magit-get "branch" source "remote")
   (concat source ":"
           ;; Forgejo uses /refs/for/{branch} to target. Locally,
           ;; setting the upstream branch sets the "merge" config item
           ;; to refs/heads/{branch}, so we can easily construct what we need
           (s-replace "/heads/" "/for/"
                      (magit-get "branch" (magit-get-current-branch) "merge"))
           "/" source)
   `(,@args
     ,@(if (or (member "--force" args)
               (member "--force-with-lease" args))
           '("-o" "force-push=true")
         '()))))

(transient-insert-suffix 'magit-push
  '(1 0)
  (list "a" #'magit-push-current-agit))

Once I've set an upstream branch, this makes it easy to push to Codeberg. Either P a to create a new PR, or P - f a to update an existing PR.

One downside to the AGit workflow is that I completely bypass the usual PR template that the Guix project has set up in .forgejo/pull_request_template.md. Instead, it just uses the commit message of the last commit that's being pushed. That's often fine, but I'd like to add at least some of my own commentary. With my existing Magit action I would usually have to go and open the PR to change the description to say what I wanted to say.

I've always been a bit uncomfortable about this, particularly because I think it's rude to just ignore the template.

My discomfort finally got strong enough that I solved this problem tonight, with this change to the final if in the above code snippet:

,@(if (or (member "--force" args)
          (member "--force-with-lease" args))
      '("-o" "force-push=true")
    (let ((info (cz/read-pull-request-from-buffer
                 (concat (magit-gitdir) "../.forgejo/pull_request_template.md"))))
      `("-o" ,(concat "title={base64}" (base64-encode-string (car info) t))
        "-o" ,(concat "description={base64}" (base64-encode-string (cdr info) t)))))

On a force push, we don't do anything (because we're just changing the commits on an existing PR). If we're not force pushing then we're creating a new PR, so we prompt for the title and description, base64 encode them, and send them through as options on the push.

The cz/read-pull-request-from-buffer function, and its associated mode, are not quite so easy. They read out the pull request template, then go into a recursive-edit in a markdown-mode buffer with the template's contents (after skipping the Forgejo header). Technically I'm not using the template correctly, because I should extract the title from the template and add it to the template, but I don't care.

At some point I might extract this out of my config and make a proper package for it. Let me know if that would be helpful to you - it might motivate me to actually do it!

The full relevant section of my config now looks like this:

(define-derived-mode cz/agit-pull-request-mode markdown-mode "AGit PR")

(defvar-local cz/agit-pull-request-title nil)
(defvar-local cz/agit-pull-request-description nil)

(defun cz/agit-pull-request-submit ()
  (interactive)
  (when (y-or-n-p "Are you sure you want to submit this pull request? ")
    (setq-local cz/agit-pull-request-title
                (save-excursion
                  (beginning-of-buffer)
                  (buffer-substring-no-properties
                   (+ (point) 2)
                   (line-end-position))))
    (setq-local cz/agit-pull-request-description
                (save-excursion
                  (beginning-of-buffer)
                  (next-line)
                  (buffer-substring-no-properties
                   (point)
                   (point-max))))
    (exit-recursive-edit)))

(keymap-set cz/agit-pull-request-mode-map "C-c C-c" #'cz/agit-pull-request-submit)

(defun cz/agit-pull-request-cancel ()
  (interactive)
  (abort-recursive-edit))

(keymap-set cz/agit-pull-request-mode-map "C-c C-k" #'cz/agit-pull-request-cancel)

(defun cz/read-pull-request-from-buffer (template-file)
  (if (get-buffer "*Pull Request*")
      (user-error "Other pull request already open - aborting this one.")
    (let ((buffer (get-buffer-create "*Pull Request*")))
      (with-current-buffer buffer
        (insert "# ")
        (save-excursion
          (insert "\n\n")
          (when (file-exists-p template-file)
            (let ((start (point)))
              (insert-file-contents-literally template-file)
              (beginning-of-buffer)
              (save-match-data
                (re-search-forward "^---")
                (re-search-forward "^---")
                (next-line)
                (beginning-of-line))
              (delete-region start (point)))))
        (cz/agit-pull-request-mode)
        (pop-to-buffer (current-buffer)
                       '(display-buffer-same-window)))
      (unwind-protect
          (progn
            (recursive-edit)
            (with-current-buffer buffer
              (if cz/agit-pull-request-title
                  (cons cz/agit-pull-request-title
                        cz/agit-pull-request-description)
                (user-error "No pull request information"))))
        (with-current-buffer buffer
          (if (get-buffer-window)
              (quit-window 'kill (get-buffer-window))
            (kill-buffer)))))))

;; Define a command for an AGit flow to upstream (this is suitable for
;; opening PRs on Codeberg)
(transient-define-suffix magit-push-current-agit (source target args)
  :if #'magit-get-current-branch
  :description (lambda () (concat (magit-push--upstream-description) " (agit)"))
  (interactive
   (let ((source (or (magit-get-current-branch)
                     (user-error "No branch is checked out"))))
     (list source
           (magit-get-upstream-branch source)
           (magit-push-arguments))))

  (magit-push-refspecs
   (magit-get "branch" source "remote")
   (concat source ":"
           ;; Forgejo uses /refs/for/{branch} to target. Locally,
           ;; setting the upstream branch sets the "merge" config item
           ;; to refs/heads/{branch}, so we can easily construct what we need
           (s-replace "/heads/" "/for/"
                      (magit-get "branch" (magit-get-current-branch) "merge"))
           "/" source)
   `(,@args
     ,@(if (or (member "--force" args)
               (member "--force-with-lease" args))
           '("-o" "force-push=true")
         (let ((info (cz/read-pull-request-from-buffer
                      (concat (magit-gitdir) "../.forgejo/pull_request_template.md"))))
           `("-o" ,(concat "title={base64}" (base64-encode-string (car info) t))
             "-o" ,(concat "description={base64}" (base64-encode-string (cdr info) t))))))))

(transient-insert-suffix 'magit-push
  '(1 0)
  (list "a" #'magit-push-current-agit))

I'm confident that this code can be improved, but I think it'll solve my problem for now.

Alternatives

After writing this post two alternatives have been mentioned:

agitjo, as a more fully-featured implementation of the AGit workflow, and
sarg's config, which is similar to the code above, but also stores the branch title/description in the Git branch description.

There's also a Magit discussion about having an AGit implementation upstream, which tarsius seems on board for.

Setting Up Cuirass Locally

2026-02-15T00:00:00Z

Recently I've been trying to get a PR merged with some fixes for Lua. I thought this would be a pretty straightforward thing to merge, but it turns out that modifying the Lua packages leads to 990 packages needing to be rebuilt. This is more than the 300 limit for a merge to master, so instead of merging my changes directly Andreas has kindly pushed them to a lua-team branch and queued it up behind go-team, gnome-team, and rust-team.

While I'm waiting for that, I have some more drastic changes that I'd like to try out (e.g. packaging Lua 5.5.0, and using it as the default Lua for building packages). In order to do that, I'd like to be able to test my changes before the lua-team branch gets to the front of the queue. I'm not a committer to Guix, so instead I figured I'd spin up Cuirass on my local machine to help me try things out.

Why Cuirass?

It's worth spending a moment on why I want to use Cuirass, rather than just doing the builds using Guix directly. guix refresh -l already gives you a list of the packages that you need to build to test your changes, why not just use that with guix build?

There are two reasons why I want to use Cuirass: live feedback, and tracking changes over time.

For live feedback, Cuirass gives me more information about what's going on that guix build does. Even though I'm only running on my local machine, seeing the list of scheduled/succeeded/failed builds, and in-progress builds, is helpful for me to keep track of where things are up to. It lets me get started investigating build failures right away, without interrupting the rest of the builds.

For tracking changes over time, Cuirass helps me by reporting not just whether a package has built or not, but whether that has changed since the last build. This tells me whether my changes are breaking things, or whether things were already broken before I started. I need to know this so I know where to spend effort trying to fix things.

Given Cuirass is now a sunk cost for me, we're going to proceed with the assumption that this was a good idea. 🙂

Initial Setup

Setting up Cuirass on a Guix system is shockingly easy. I just added these three services to my operating-system's services:

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    (name "lua-team")
                    (build '(manifests #$(local-file "lua-manifest.scm")))
                    (channels (list (channel
                                     (name 'guix) ; has to be called guix for pull to work
                                     (url "https://git.sr.ht/~czan/guix") ; my unlisted fork
                                     (branch "lua-team")))))))))
(service postgresql-service-type
         (postgresql-configuration
          (postgresql (specification->package "postgresql@16"))))

This sets up a local instance of the cuirass-service-type configured to poll the listed channels and build things locally whenever anything changes.

The manifest that I wrote looks for all the packages which (transitively) depend on one of the Lua version. I took inspiration for the code for guix refresh -l, and this is the result::

;; lua-manifest.scm
(use-modules (guix)
             (guix packages)
             (gnu packages)
             (guix profiles)
             (guix monads)
             (guix graph)
             (guix scripts graph)
             (ice-9 match)
             (gnu packages lua))

(define packages
  (list lua-5.4 lua lua-5.2 lua-5.1 luajit))

(packages->manifest
 (with-store store
   (run-with-store store
     (mlet %store-monad ((edges (node-back-edges %bag-node-type
                                                 (package-closure (all-packages)))))
       (return (node-transitive-edges packages edges))))))

Problem: not authenticated

The first problem I ran into was that Guix will fail a pull for the guix channel if it tries to authenticate the commits but can't. Since I'm not a committer, I can't authenticate my commits without doing some more work (setting up a key, adding to the keyring, signing a commit, setting up an introduction, ...). I didn't really want to do that, so I hunted through the Cuirass manual and found the authenticate-channels? property. Setting it to #f does an unauthenticated pull. Dangerous in some circumstances, but acceptable for what I'm doing.

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    ;; ... As above ...
                    ;; I'm not a committer, so we can't authenticate my commits
                    (properties `((authenticate-channels? . #f))))))))

Problem: evaluations failing

I got the pulls working, but then the evaluations kept failing. It turns out the path listed in the build option need to exist in the pulled channels. In my first attempt I passed a (local-file ...) call, but this did not work at all.

I had to commit my manifest into the repository and reference it in the build option:

(service cuirass-service-type
         (cuirass-configuration
          (specifications
           #~(list (specification
                    (name "lua-team")
                    (build '(manifests "etc/teams/lua/lua-manifest.scm"))
                    ;; ... As above ...
                    )))))

Problem: no builds running

The next problem I ran into was that this configuration didn't run any builds. It would poll the git repository, and successfully pull the changes and build Guix, but it would never get to building any packages. I couldn't see any reason for it not working, but the documentation for the local build mode also had this warning:

When Cuirass is used to build a large amount of jobs, the remote build mechanism described below should be preferred.

I figured I should try that. Again, configuring this in a Guix system to just use the local machine as a builder is easy. I just added the remote-server setting to my cuirass-configuration:

(service cuirass-service-type
         (cuirass-configuration
          (remote-server (cuirass-remote-server-configuration))
          (specifications
           ;; ... As above ...
           )))

and I added one more service to my list of services:

(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration))

With that, Cuirass started to build my packages locally. I saw my CPUs get busy, and all was well.

Problem: killed my machine

Unfortunately, the default configuration for the Cuirass remote worker is to run a single build, and to let it use all the cores for its build. My machine has an i7-8700 with 6 cores running 12 threads, and 32GiB of RAM. It turns out that building some Guix packages will cause that configuration to lock up (I assume it's swapping, but I didn't investigate at all).

I looked through the Cuirass manual to try to find some way to set the equivalent of --cores in the builds it runs, but I couldn't find anything. I had a look at the Cuirass source where the parameter is set, which itself comes from dividing the number of CPU cores by the number of workers. This assumes that the Cuirass workers can take up all the cores on the machine (which is not ideal for the computer that I use as my desktop), but it at least gives me enough control to avoid the builds locking up the whole machine.

Once again, the configuration for this is straightforward:

(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration
          (workers 6)))

Now I have six concurrent builds, with each using two threads. This has kept my memory usage under 50% thus far, and builds are continuing unimpeded.

Final configuration

The end result of my service configuration looks like this:

(service cuirass-service-type
         (cuirass-configuration
           (remote-server (cuirass-remote-server-configuration))
           (specifications
            #~(list (specification
                     (name "lua-team")
                     (build '(manifests "etc/teams/lua/lua-manifest.scm"))
                     (channels (list (channel
                                       (name 'guix)
                                       (url "https://git.sr.ht/~czan/guix")
                                       (branch "lua-team"))))
                     (properties `((authenticate-channels? . #f))))))))
(service postgresql-service-type
         (postgresql-configuration
           (postgresql (specification->package "postgresql@16"))))
(service cuirass-remote-worker-service-type
         (cuirass-remote-worker-configuration
          (workers 6)))

Want to help?

If you're interested in helping to maintain Lua packages in Guix (because I have no idea what I'm doing), get in touch on guix-devel in the thread I started. I'm particularly interested in getting a Guix committer on board, so I don't have to keep bothering Andreas. (Thanks Andreas!)

Ruby Development Using Guix

2026-02-08T00:00:00Z

Up until a few months ago, I was working on a Ruby on Rails monolith. In the four years that I worked on the project, we went through a few ways of building a local development environment:

directly using Bundler on our machine, then
using Bundler inside a Docker image, then
using Nix and Bundix, then
back to using Bundler inside a Docker image (not everyone liked Nix).

All of these options were fine, but my package manager of choice is Guix. I really wanted a way for me to work with my Ruby on Rails project alongside the rest of my team, but using Guix to build my development environment.

In 2015 David Thompson posted about using Guix for Ruby development which describes using Guix packages to build a Ruby development environment. Guix has a lot of Ruby packages, but it doesn't package all of RubyGems, nor does it package all the different versions of each Gem. This makes it difficult to use Guix to get precise dependencies that are needed for most real-world Ruby projects.

To make things easier for myself, I built Guix Ruby. A Guix channel that provides a guix ruby command which imports a Gemfile.lock and constructs Guix packages for all the listed dependencies.

To install it, just need to add this to your channels file (~/.config/guix/channels.scm):

(cons* (channel
        (name 'guix-ruby)
        (url "https://git.sr.ht/~czan/guix-ruby")
        (branch "main"))
       %default-channels)

Your next guix pull will add a new Guix command: guix ruby!

Basic Usage

Running guix ruby in the root of a Bundler project will read Gemfile and Gemfile.lock to produce a new file: Gemfile.lock.scm. It looks something like this:

(use-modules ...) ; imports
(lambda* (#:key (ruby ruby) (groups '(default)) (gem-transformers %default-gem-transformers))
  ...) ; gem definitions

You can then load this file in your manifest.scm or guix.scm file, and call the resulting function to get a list of Guix package objects which match your Bundler dependencies.

;; An example manifest.scm
(define bundler-packages (load "Gemfile.lock.scm"))
(packages->manifest
 (cons* ruby (bundler-packages #:groups '(default development test))))

Too easy.

When you're first setting up a project, you can ask guix ruby to create a manifest.scm file by passing the --init flag. It will be a bit more complicated than the example above, because it is more explicit about the Ruby version that it uses.

Adding New Dependencies

When it's time to add dependencies, you may find that using bundle install does not work due to a read-only file system. Instead, you can use bundle lock to update Gemfile.lock, then run guix ruby to update Gemfile.lock.scm.

You can also ask guix ruby to do this in one step with the --lock flag.

Updating Dependencies

At the moment, guix ruby doesn't have a shortcut to update dependencies, but bundle lock --update can still be used.

Git Dependencies

Sometimes it's useful to have Bundler clone dependencies directly from Git. This is supported by guix ruby, which will write an appropriate Guix package definition. However, when using bundle lock and bundle lock --update, you may run into issues. Bundler tries to clone the referenced repository in order to get some information about it. Unfortunately, the way Gemfile.lock.scm defines packages causes this to break (because it defines GEM_HOME pointing to a read-only directory).

Setting GEM_HOME to point to some readable directory should be enough to get it working, at the expense of an extra clone of the repos:

$ bundle lock --update # no good :(
...
There was an error accessing `/gnu/store/...`
The underlying system error is Errno::EROFS: Read-only file system @ dir_s_mkdir

$ GEM_HOME=/tmp/bundle-cache bundle lock --update # works :)
Fetching https://git.sr.ht/...
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Writing lockfile to /.../Gemfile.lock

Gem Transformers

You may have noticed the gem-transformers parameter defined in Gemfile.lock.scm. This provides a mechanism for you to provide "transformations" to the automatically generated packages, to do things like adding inputs that are needed to build extensions. A default set of transformers is built into Guix Ruby itself, but you can provide your own transformers if a Gem isn't already supported.

I'm keen to support as much as we can in Guix Ruby, though, so if you find you need to define a transformer then let me know on the mailing list and I can add it to the default set.

Try it out!

I've been using guix ruby for a while to manage the dependencies on my Ruby projects. I've managed to get a few complex projects working using it (including Rails!), and I'm finding it very convenient to use Guix for Ruby development. If you're looking to bring together Ruby and Guix, please try it out. If you run into any issues, let me know on the mailing list and I'll do my best to help you.

Gradual Typing

2026-02-06T00:00:00Z

I recently started a PhD at the Australian National University, doing research into gradually typed programming languages. Since I'm probably going to have to explain this a lot, I thought I'd write a quick explanation of what gradual typing is. In a future post I will then talk about what specifically I'm doing.

Static and Dynamic Types

In programming languages, there has long been a distinction between languages with static types, and those with dynamic types. Languages with static types want to know things about the program you're writing (e.g. x is a number, y is a Person record), and they'll refuse to run your code at all if it tries to do something that doesn't make sense (like adding a number to a Person). Languages with dynamic types, on the other hand, will happily run your program, but will fail part-way through if you do something invalid (like adding a number to a Person).

add a b = a + b
data Person = MakePerson
add MakePerson 10 -- Type checking fails, so this won't run at all

def add(a, b): return a + b
class Person:
  pass
add(Person(), 10) # Fails while the program is running, inside the add function

These each have their strengths, and their weaknesses.

Static typing is great for catching mistakes before you make them, but it forces particular structures on your programs. It's not enough to just write a correct program, you have to write a program that can be proven correct for all executions within the rules of the type system.

Dynamic typing is great for more exploratory programming, but there are a lot more ways to make mistakes. The flexibility of dynamic typing makes it possible to write programs without having to prove anything about them. During development this is particularly valuable, as it makes it easier to get rapid feedback without having to dot every "i" and cross every "t".

Gradual Types

At a high level, gradual type systems are an attempt to combine the benefits of both static and dynamic types. Systems with gradual types allow parts of your program to have static types, while other parts of your program can use dynamic types.

An example of a gradual type system is TypeScript, which has static types, but also includes an any type which behaves like a dynamic type.

const add = (a: any, b: any) => a + b // any type
class Person { }
add(new Person(), 10) // Passes the type check

const add = (a: number, b: number) => a + b // numbers now
class Person { }
add(new Person(), 10) // Type checking fails: a Person is not a number

These types are called "gradual" because these types allow you to start by using dynamic types during development, and then gradually add type annotations so the computer can help catch mistakes.

There are a few languages with gradual type systems at the moment (e.g. TypeScript; Python with mypy, pyright, or pyanalyze; Ruby with Sorbet; PHP; Dart).

In an academic setting, gradual typing is usually discussed in terms of the gradual guarantee, which I'll write about another time.

Syntax Highlighting in Haunt

2026-01-10T00:00:00Z

I wrote a post just under two years ago about setting up this blog, and then I didn't write anything else! Shame on me.

Part of the issue that got me stuck is that I wanted syntax highlighting. The "standard" option for Haunt is to use guile-syntax-highlight, but it has a pretty minimal set of supported languages. I wasn't satisfied with that.

In the past I've used Pygments, but I wasn't sure how to get that into Haunt.

Well, it's been two years: I think it's finally time to solve this problem!

I had some trouble finding a way to call an external process, passing something to its stdin and reading something from its stdout. In the end, I came up with something like this:

(define (syntax-highlight-strings strings language)
  (let* ((push (pipe))
         (pull (pipe))
         (pid (spawn "pygmentize" `("pygmentize" "-f" "html" ,language)
                     #:input (car push)
                     #:output (cdr pull))))
    ;; Write to the subprocess, then close the port
    (close-port (car push))
    (for-each (lambda (b) (display b (cdr push))) strings)
    (close-port (cdr push))

    ;; Read the result back in, then close the port.
    (close-port (cdr pull))
    (let ((result (get-string-all (car pull))))
      (close-port (car pull))
      (waitpid pid)
      result)))

This uses spawn to start a pygmentize process, writes a list of strings to it, then reads the result back.

We can then walk the whole tree to find the shape that the guile-commonmark reader emits for fenced code blocks with a language (which is <pre><code class="language-scheme">...</code></pre>).

(define (syntax-highlight sxml-tree)
  (define (language-from-attrs attrs)
    (let ((classname (assoc-ref attrs 'class)))
      (and classname
           (string-prefix? "language-" (car classname))
           (substring (car classname) 9))))

  (match sxml-tree
    (('pre ('code ('@ . attrs) . body))
     (match (html->shtml (syntax-highlight-strings body (language-from-attrs attrs)))
       (('*TOP* element "\n")
        `(div (@ ,@attrs) ,element))))
    ((tag ('@ . attrs) . bodies)
     (cons* tag (cons '@ attrs) (map syntax-highlight bodies)))
    ((tag . bodies)
     (cons* tag (map syntax-highlight bodies)))
    (_ sxml-tree)))

Then it's just a matter of calling syntax-highlight on the post-sxml in our theme's #:post-template function.

(define my-theme
  (theme #:name "My Made Up Theme"
         #:post-template (lambda (post)
                           `((h1 (,post-title post))
                             (div ,(syntax-highlight (post-sxml post)))))))

This sets up the HTML necessary for colours, but to get actual colours you'll need to generate a stylesheet with the colours you want. The pygmentize command can do this. This will print the styles to stdout:

pygmentize -S default -f html

You can include these styles in your page (either in a linked .css file, or inline) and colours should appear.

Hello, World!

2024-01-26T00:00:00Z

As this blog enters the world, let us begin in the customary way: "hello, world!"

This blog will be a place for me to write things. I'm not really trying to achieve anything with this, except to write more words, so keep your expectations low. 🙂

For some reason, I have decided on a slightly odd software stack for this blog: I am using the Haunt static site generator. It is pretty bare-bones, and requires some up-front setup. Haunt is not much more than a Guile Scheme library for parsing posts and constructing pages from them. It has a few helpers, and a way to define "themes", but not that much else.

I decided to define a fancy style that I saw in an Org mode exporter time, to put the name of a language on the top-right of a code block.

pre code:after {
    display: none;
    position: absolute;
    top: 0;
    right: 0;
    padding: 10px;
    outline: 1px solid black;
}
pre:hover code:after {
    display: block;
}

I need to make sure to define a new style for each language I use, though.

.language-scheme:after { content: "Scheme"; }
.language-css:after { content: "CSS"; }

But I should also add some sort of source highlighting, I guess. I have no idea how hard that is going to be.

Anyway, it's a start!