DEV Community: Paul Cochrane 🇪🇺

Computational physics with Python: tool setup

Paul Cochrane 🇪🇺 — Wed, 22 Apr 2026 22:00:00 +0000

Imagine you want to learn computational physics and Python as an advanced high-school student or undergraduate. Where to start? Assuming no prior programming experience, a quick introduction to programming concepts won’t go amiss. To get to that point, though, you’ll need to prepare some tools first.

In this post, I describe how to install Python and Visual Studio Code, two tools we need before we can start programming and learning computational physics. I then describe how to configure VS Code to use Python, finishing up by writing a toy Python program and running it within VS Code.

A high school student that I tutor asked me a while ago if one can learn physics by programming in Python. I answered: “Of course!” Since then, I’ve had all kinds of ideas about how to introduce computational physics and numerical methods to advanced high-school or early-level university students.

This is the first post in a (long-term) series focusing on numerical methods and computational physics. The intent is to collect enough topics and examples to create a course in computational physics using Python.

A rough plan

My rough plan is to discuss concepts already taught at school, for which we know the analytical solution. This way, we focus on learning the numerical methods, secure in the knowledge that we have a firm understanding of the mathematics and physical concepts.

Then we implement the numerical solution in Python and compare it with the analytical one to see how well we did. This reduces cognitive load: we’re not introducing new physics and maths concepts. The only things that are new to us are programming and the relevant numerical methods.

One long-term goal is to build sufficient understanding of the numerical methods so that we can move out of our comfort zone and learn to solve physical problems where an analytical solution is either unknown or difficult to calculate.

Before we can really get going, we need to set up our working environment.

Getting started

To run Python programs, we need a working Python development environment. And to create Python programs, we need software in which we can write code. Thus, we need to do some boring administrative work before we can start doing interesting physics and programming stuff.

This post will focus on getting a Python environment up and running within Visual Studio Code. The following article will introduce some basic programming concepts and show a simple example of using the NumPy and Matplotlib libraries. This foundation will enable us to focus on computational physics topics later.

The installation guide described here assumes a Windows environment. I made this decision because I assume that most students either use Windows or have access to a Windows computer.

Some students will have macOS. Unfortunately, I don’t have access to a macOS system. Hence, I can’t describe the installation process in that environment.

Other students likely use Linux. From personal experience, Linux users are often in the minority. So, even though I would like to describe the process from a Linux perspective, I chose Windows because it is relevant to most students.¹

We now focus on installing Python and the Visual Studio Code integrated development environment (known simply as VS Code). As you will see below, there’s a lot of setup required before we can get to the fun stuff and start programming. Fortunately, we only have to do this setup once, so it’s worth taking our time to do it properly.

Installing Python

According to the Visual Studio Code tutorial on installing Python, it’s recommended to install Python first, so we’ll start there. This ensures that Python is available for VS Code to find when we install it later.

There is also good documentation on the VS Code website for writing and running Python programs. You can find more information under the “Python” link on that site.

Before installing Python, we have to download it. The best place to get it for Windows is from the Python website. Using a browser, navigate to the Python downloads page:

Now click on the “Download Python” button to download the most recent version of Python (note that the version number you see will be different to that shown in the screenshot above).²

After the download has completed, open your Downloads folder and search for the installer application. It’ll be called something like python-3.15.5-amd64.exe (where 3.15.5 is the version number and is likely different in your case). You should see an icon which looks like this:

Double-click on the installer icon. You should then see the Python for Windows installer startup dialog box:

This window has two unchecked options at the bottom. One mentions using admin privileges when installing Python (which we don’t need), and the other mentions adding python.exe to your PATH. Your PATH tells your computer where to look when it wants to find the program to run Python. It’s therefore a good idea to check this option.

Now we’re ready to install Python. Click on the “Install Now” option in the middle of the window. This will install Python and any supporting software it needs.

Once the installation has completed, you’ll see the “Setup was successful” dialog box appear.

Click on the “Close” button to continue.

Now that Python is installed, we’re ready to install Visual Studio Code.

Installing Visual Studio Code

One thing to note first: Visual Studio Code is not Visual Studio; they’re different things. Yes, Visual Studio is also an IDE.³ Yes, it’s a product from the same company. Yes, this is confusing. Sorry about that.

Go to the Visual Studio Code download page and choose an installer appropriate for your operating system.

Because we’re using Windows, click on the “Windows” button to download the installer application. This will download a file called VSCodeUserSetup-x64-1.101.2.exe (the 1.101.2 part is the version number; it’ll be different for you).

Open your Downloads folder and double-click on the .exe file’s icon:

This will start the VS Code installer:

To continue, we have to click on “I accept the agreement”. This way, the “Next” button becomes active.

Click on the “Next” button. You’ll see a window asking you to choose a destination location.

The default option should be good enough, so click on “Next” in this window. A dialog box will appear, asking you if you want a Start Menu folder entry for Visual Studio Code.

This is handy to have, so click on “Next” to continue.

The following dialog box asks which additional tasks the installer should perform.

One option you might want to select, which isn’t one of the default options, is to add a desktop icon. If you want that, go for it, and click on the “Create a desktop icon” checkbox. In this case, I chose not to do this and simply clicked on “Next”.

You’re now presented with an overview of what will be installed.

Click on “Install” to install Visual Studio Code. The installation will now start.

You should see that the installation completed successfully.

The dialog box has a checkbox to ask if you want to launch Visual Studio Code. This is a good idea, so click on “Finish” to complete the installation and start the IDE.³

The VS Code start page will then appear.

You could take the walkthrough setup of VS Code at this stage, if you want. We’ll skip that, though, and start installing the extensions we need to get Python up and running within VS Code.

Installing the Python VS Code extension

The next task is to install the Python VS Code extension. This allows us to develop and run Python programs within the VS Code IDE.

To see a list of available extensions, you could either click on the extensions icon from the toolbar on the left-hand side of the page:

or click on the settings icon (the cog symbol at the bottom left of the page) and select the Extensions menu option.

Either way, you’ll see a list of extensions populated in the left-hand frame in VS Code.

Fortunately for us, Python appears as one of the recommended extensions at the top of the list. If it weren’t, we could have searched for it in the search box above the list of extensions.

To install the Python extension, click on its “Install” button. If you look carefully, you’ll see that VS Code also installs the Pylance and Python Debugger extensions.

Once the Python extension has been installed, you’ll see a help page for getting started with Python development:

Now we’re ready to set up a project, which will contain the computational physics topics we’re going to investigate as part of this course.

Setting up the project folder

Our next goal is to write a simple Python program. Again, there’s some setup we have to do before we can do that. Such is life when starting at the very beginning. Don’t worry, we’ll soon have enough foundation that we won’t have to spend any time on setup.

In software development, which is part of what we’re doing here, one often collects related files together into a project. This is an organisational structure that keeps related things together; things that share a similar topic or theme. In theory, you could put all files from all projects into your user directory. And yes, I’ve seen people who work like that. However, you’ll find that over time, as you write more and more code, things get hard to find. Such chaos slows you down and makes your life harder. Hence, it’s a good idea to bundle code into projects and–as necessary–into subfolders to keep things organised.

The top-level organisational unit we have is the overarching topic of computational physics. Thus, we’ll create a project folder in VS Code for this topic. Subtopics live in their own folders within the main project folder. The main project folder will also contain the environment we need to run Python programs.

There are two ways to create a project folder. We can either click on the “File” menu and choose the “Open Folder…” option, or we can click on the “Open Project Folder” button from the “Get Started with Python Development” page. For example:

We’ll choose the second option, because it’s a single click. Clicking on the “Open Project Folder” button in the middle of the page will open the “Open Folder” system dialog.

The issue right now is that we don’t have a prior project folder we want to open: we’ve got to create a new one. To do this, click on the “New folder” button at the top left of the “Open Folder” dialog box.

This created a new folder in the current directory. You should see that the folder’s name (“New folder”) is highlighted and thus ready for us to rename. Let’s call this folder ComputationalPhysics.

Click on the “Select Folder” button at the bottom right to select it as our project folder for use in VS Code.

VS Code will now open the project folder. But first, it will ask you if you trust the authors of the files in this folder. Since you yourself are the author, you can click on the “Yes, I trust the authors” button. Assuming, of course, that you trust yourself. 😉

Creating a Python virtual environment

Theoretically, we’re ready to create a simple Python program and start playing. However, later we want to install some external Python libraries (i.e. libraries that aren’t distributed as part of Python itself) so that we can define and plot data. Thus, we need to set up a virtual environment which will contain these extra libraries.

Setting up a virtual environment is a good idea when writing Python programs. It allows you to keep the extra libraries you install separate from any other Python software you might have, thus avoiding conflicts between libraries with different versions.

Conflicts between different library versions can arise surprisingly easily. Hence, it’s useful to isolate software libraries within their own project context. Our computational physics project is one instance of such a context. Were we to install a library in a global context (i.e. where the library could be used across multiple projects), it’s possible for different projects to need different library versions.

For instance, let’s say program blah needs version 5.2 of a library called buzz, but program foo needs version 3.7 of that same library. It’s not possible to satisfy both requirements had we installed buzz at a global level. But using a virtual environment allows us to keep things isolated. Thus, if programs blah and foo each use their own virtual environment, we can install the appropriate buzz version for each program and avoid conflict.

There are a few ways to set up a virtual environment in VS Code.

One way to do this is to go to the “View” menu and select the “Command Palette…” option:

You will see a list of items in a drop-down menu at the top of the screen.

You can either type “Python: Create Environment” into the box at the top:

or scroll down the (very) long list of options until you see the “Python: Create Environment…” option. Either way, click on this option now to create your Python environment.

Another way to do this is to click in the box at the top middle of the screen containing a magnifying glass icon and the name of our project folder, ComputationalPhysics. Clicking here will bring up a menu including the option “Show and Run Commands”.

Assuming that the “Get Started with Python Development” window is still available, click on the “Select or create a Python environment” option and then click on the “Create Environment” button.

VS Code will ask us what type of environment we want to create.

Since we aren’t using Anaconda, we only want to use the standard Python virtual environment, so click on the “Venv” option. This will create a folder within our project folder with the name .venv.

VS Code now asks us which Python installation we want to use in our virtual environment. If you’ve installed multiple versions of Python, you’ll see several options in the drop-down list that now appears. In our case, we’ve only installed the one Python version, so we only see one version appear:

Selecting the Python installation will create the Python environment. You’ll see an info box in the bottom right-hand part of the window telling you about this.

Creating a new Python file

To make sure that everything works as expected, let’s create a simple Python file to check. Usually, you create new files by going to the “File” menu and selecting the “New Text File” option.

However, because we’re just getting started, we click on the “Create a Python file” step from the “Get Started with Python Development” window:

Doing so will open a Python file called Untitled-1 in a tab next to the “Welcome” tab containing the “Get Started with Python Development” stuff.

Note that if you open a new file via the “File” menu, you’ll only see the new file in a tab and the “Welcome” tab will be hidden.

A personal statistics program

We’re now going to create a small program which asks you some questions and prints back that information in a slightly different form. It’s not very interesting, but it allows us to see that the Python environment is working, and we can start some basic programming.

Click in the tab named Untitled-1 and enter the following text:

name = input("What's your name? ")
age = int(input("What's your age (in years)? "))
height = float(input("What's your height (in m)? "))

print(f"Hello {name}! You are {age} years old and {height} m tall.")

You need to save this file before you can run it. You save files by either selecting the “File” menu and then the “Save” option:

or you could use the key combination Ctrl+S. This means you press the control key (labelled Ctrl on your keyboard) together with the s key.

Either way, you’ll see a dialog box to save the file as a certain name.

In the “File name:” field at the bottom, where the text “Untitled-1” is highlighted, enter the name print-personal-stats.py. Then click on the “Save” button in the bottom right-hand corner.

Now we’re ready to run the file. At the top right of the VS Code tab with our Python code in it, there’s a small triangle which looks like the symbol for “Play”. If you hover your mouse over this triangle, you’ll see the text “Run Python File”.

Click on the triangle to run the file.

You will see a new window appear in VS Code. This is your terminal window where your program runs.

You’ll also notice that your program has started, and it’s already asking you a question. To enter text into the terminal, you have to click in its area at the bottom of your VS Code window to focus it. This will allow you to interact with your running program. A cursor (a small white rectangle) will appear where you can now start entering information.

As an example, enter the following information:

When asked for the name, enter: Alice
When asked for the age, enter: 42
When asked for the height, enter: 1.57

After typing each piece of information, press the “Enter” key to pass it to the program. You should see output like this:

Congratulations! You’ve run your first Python program in VS Code!

We’ve fulfilled a large number of the first steps listed in the “Get Started with Python Development” welcome tab, and we’re able to continue with confidence. We can close this tab and free up some room in the VS Code window.

Close the “Welcome” tab by clicking on the small “x” next to the word “Welcome”.

That gave us a lot more room to see our code. Nice!

More next time

That will do for this time. We’ve come quite far in getting everything we need up and running. Next time, we’ll discuss the Python code in detail, talking about programming concepts such as variables, assignment, and data types.

As a long-time Unix and Linux user, this does break my heart a bit. However, I have to realise that Windows is the most common environment for students in the wild and adapt to that. ↩
Note that you could go to the Python for Windows downloads page. But it turns out to be easier to click on the “Download Python” button on the main downloads page. If you’re on Windows, it will detect that and will provide you with a direct link to download Python. ↩
IDE stands for Integrated Development Environment. This is a term for a very powerful code editor packed with lots of functionality that makes editing and running code very easy. You could use something simpler, such as vim orEmacs, to write Python code, and many people do. IDEs such as VS Code are very prevalent in software development circles. ↩ ↩²

I think the bots don’t like me anymore

Paul Cochrane 🇪🇺 — Wed, 15 Apr 2026 22:00:00 +0000

After about five months of AI bots hungrily munching on my blog’s free training data, they seem to have abruptly stopped. It’s a good sign, but given they seem to be hammering most other sites on the web, it’s somewhat odd. Here, I have a quick look at the numbers to see what’s been happening.

Rising views

Although I removed analytics collection from my blog years ago, Hetzner (where my blog is hosted) generates basic statistics from their web server logs,¹ and sometimes I have a nosey to see if anything interesting is happening. Stats derived from these web server logs have limited information content, which is how I like it. This way, I get rough information about site visits while not tracking anyone.

Late last year, I noticed an upwards trend in the number of hits to my blog. I observed that there were many more hits than usual and that the number rose steadily over the following few months. At the end of the year, I wasn’t surprised to see names in the “Robots/Spiders” section from a well-known AI company. I thought to myself, “Oh ok, that’s just a horde of AI bots sucking data from my blog, much like they’re doing to everyone else”. In other words, “Move along. Nothing to see here. This is the new normal”. Not having the time to investigate further or take any mitigating measures, I carried on with my life.

A sudden drop

That was the situation until late March, when the numbers returned to “normal” levels. For my tiny site, it’s quite the drop-off. You can see numbers begin their decline from the 19th until the 24th of March:

I mean, say what? Don’t the bots like my yummy free training data anymore?

To be honest, I don’t have an explanation for the behaviour, but I thought it’d be fun to dig into the numbers a little and see what’s happening. I’m wondering if the trend will continue into April and the rest of the year.

Xmas lift-off

Anyway, the story begins in earnest in December last year, when I happened to notice a jump in the number of visits to my blog. To some degree, that can be a flattering indicator: people like my articles! Yay!

Look at the number of different visitors (“Unterschiedliche Besucher”) ramping up over the course of 2025:

Then, at the end of December,² the hits per day stats (“Anzahl der Besuche”) reached a high level³ (~1,700 hits per day),

eventually touching the 3,000 hits per day mark later, in March 2026.

Unfortunately, a quick look at other data from December 2025 showed lots of hits from bots:

That was somewhat deflating. Ok, my articles aren’t being read by humans and aren’t that useful to people. 😕 Instead, bots are gobbling them up and are (probably) dishing them up in a mangled form in someone’s search results. That’s quite the bummer.

Hitting the categories for no good reason

Digging into the stats a little more, it turned out that the daily bot-snacking began in roughly October 2025. Yet, definitive evidence only turned up in the “Robots/Spiders” stats later.

What gave their presence away? Well, the “categories” page was being downloaded so often that it appeared in the list of top 10 pages.

Now, the “categories” page is a pretty bloody boring page. It’s not something a human is going to look at much, and hence, this page shouldn’t appear in the top 10 list. I mean, it’s not often you want to know what categories some blogger uses on their page, right?

From October 2025 onwards, the numbers start to become very weird, at least if one expects the traffic to be coming from humans. To get a feel for what I mean, consider that in September 2025, the “categories” page didn’t appear in the top 10. In October, it suddenly appeared at the fourth position in the top 10 pages with 499 hits. That was the first sign that something odd was happening. In November, it was 700 hits. Then, in the following months, 17,538, 34,798, and 32,631 hits respectively, reaching 39,997 hits in March 2026.

Like, WTAF? Just why??? Why don’t they hit the other pages as well?

Maybe they are. But why hammer the categories page?

It’s difficult to know how many of the hits to the remaining pages are from actual human beings, if at all. After all, it’s nice to know if an article has been popular. This gives me an indication of the kinds of posts that are useful and/or interesting to people. If some topic resonates, then I can consider writing more along such lines in the future.

The stats for the top 10 countries tell a similar story. For instance, the United States had ~8,000 hits and ~700 MB, respectively, in September 2025. These stats jump to ~24,500 hits and 5.6 GB in December, achieving ~50,000 hits and 12 GB in March 2026. That’s pretty nuts for such a small site, and it washes out any useful signal that might be in the data.

Direct AI bot evidence

The first direct evidence of AI bots scraping the site appeared in the “Robots/Spiders” stats in November 2025, even if the site was already being regularly scraped before then.

That’s when the bot names ChatGPT-User (OpenAI) and OAI-SearchBot (OpenAI) appeared in the top 10 list. From January onwards, they were the top two, which was the same month that Google’s crawler got pushed off the top 10 list. I find it amazing that Google’s bot got shouldered out of the top 10. Did Google’s bots get more efficient and hence no longer need to access the site as often? No idea.

Building LaTeX documents on GitHub

Paul Cochrane 🇪🇺 — Wed, 08 Apr 2026 22:00:00 +0000

Do you have LaTeX projects on GitHub? Ever wondered how to get GitHub to build them automatically? Here’s how I do it.

A geeky workflow for LaTeX documents

I’m a geek. More precisely, I’m a physicist. So I’m probably even geekier than your standard geek.

Now, when physicists write documents, such as papers, letters, or slides for talks, they tend to use LaTeX. I’m no exception. After all, the layout is automatic, the mathematics looks great, and I get to write code to construct my documents. What’s there not to like?

When creating the slides for my talks, I use the beamer class. It’s become the standard these days when writing talks in LaTeX.¹ Of course, because LaTeX is code, I put my work into Git and push it to an online Git service such as GitLab or GitHub. When using GitHub, I build the document using a GitHub Actions workflow. This way, the document builds in a “pristine” environment, and helps me spot issues that might not be obvious when working only on my development system.

A version lag in Ubuntu’s TeXLive packages

In one recent project, I was building the slides on GitHub by installing the standard Ubuntu TeXLive LaTeX packages and then running latexmk. The problem here is that the Ubuntu LaTeX packages aren’t as up to date as one might like them to be. On GitHub, using for instance the ubuntu-22.04 Docker image,² one has access to a TeXLive version from 2021. That’s somewhat … old. I needed a recent TeXLive distribution.

But how best to get a recent TeXLive? Starting from a stock Ubuntu image and then installing TeXLive is a no-goer, as anyone who has installed a full TeXLive distribution will know. This process can potentially take hours only to download the individual TeXLive packages. That definitely won’t work in a GitHub-CI build: the process will time out before any document has been built. Also, getting feedback on broken builds would take forever, thus reducing the usefulness of building the project on GitHub.

Another possibility would be to use either the small or medium TeXLive distribution, installing any missing packages as necessary. This would be a lot of work trying to find out which packages are missing. I’d have to update the CI config, wait for a build to run (which involves a long installation step, so it takes a while), see if the build fails, read the log output to find the missing package, add it to the CI config, and try everything again. Future package additions to the document would also make the build fail if I’m not vigilant in keeping the CI config up to date. Not an optimal situation.

A LaTeX-specific GitHub action

Surely there’s a better way? Yes, there is. Introducing the latex-action GitHub action. It’s a

[…] GitHub Action that compiles LaTeX documents to PDF using a complete TeXLive environment.

That’s just what we’re after!

The action provides many TeXLive versions to choose from, from 2020 up to the latest version as of writing, 2025. You can also choose between Alpine or Debian Linux as the base image, giving you some flexibility about what other software you might want to install. There are other options available to handle paths, compilation settings, etc. Check out the action’s documentation for more details.

Sounds great! Let’s begin!

A worked example

Using a simple example for illustration, I’ll first describe how to build a LaTeX document within a GitHub workflow using the stock Ubuntu images. Then I’ll show how to migrate to a workflow using the latex-action action.

We’ll construct a short beamer document that’s got a couple of slides in it with just enough complexity to make it a bit interesting. For those who are interested, the document introduces the basics of the discrete Fourier transform.

Building the document locally

Imagine we have a local Git repository called discrete-fourier-transform with a file containing the following LaTeX code:³

\documentclass[t,aspectratio=169]{beamer}
\usetheme{metropolis}

\title{Briefly introducing the discrete Fourier transform}
\author{Dorotea Avra}

\begin{document}

\maketitle

\begin{frame}{Background}
    \begin{itemize}
        \item From Wikipedia:\footnote{\url{https://en.wikipedia.org/wiki/Discrete_Fourier_transform}}
    \end{itemize}
    \begin{quotation}
        the discrete Fourier transform is a discrete version of the Fourier
        transform that converts a finite sequence of equally-spaced samples of a
        function to a same-length sequence of equally spaced samples of the
        discrete-time Fourier transform [\ldots].
    \end{quotation}
\end{frame}

\begin{frame}{Background}
    \begin{itemize}
        \item If data sets contain periodic oscillations, one can analyse
            them with ``spectral methods'', a.k.a. ``Fourier transform
            methods''.
        \item Sometimes it is easier or more useful to analyse and process
            data in the frequency domain than it is in the time domain.
        \item The discrete Fourier transform is a numerical method to
            calculate the Fourier transform of a data set on a computer.
    \end{itemize}
\end{frame}

\begin{frame}{Discrete Fourier transformation definition}
    Consider a vector of $N$ evenly-spaced time series
    points,\footnote{Discussion based on Chapter 5.2 Spectral Analysis from
    \emph{Numerical Methods for Physics} by Alejandro L.\ Garcia, 1994.}

    \begin{equation}
        \mathbf{y} = [y_1, y_2, \ldots, y_N]
    \end{equation}

    The data are sampled every $\tau$ seconds, thus giving us a list of time
    points defined by:

    \begin{equation}
        t_i = \tau (i - 1)
    \end{equation}

    where $i$ is the 1-based index of the input vector.
\end{frame}

\begin{frame}{Discrete Fourier transformation definition}
    Given the vector of data points, $\mathbf{y}$, we can define its discrete
    Fourier transform, $\mathbf{Y}$, as a vector:

    \begin{equation}
        Y_{k+1} = \sum_{j=0}^{N-1} y_{j+1} e^{-2 \pi i j k / N}
    \end{equation}

    where $i = \sqrt{-1}$. Note that $j$ and $k$ start at zero, whereas the
    vector uses a 1-based index.
\end{frame}

\begin{frame}{Example}
    Following the discrete Fourier transform discussion in
    Garcia,\footnote{Chapter 5.2 Spectral Analysis from \emph{Numerical Methods for
    Physics} by Alejandro L.\ Garcia, 1994.} using a sampling interval of
    $\tau = 1$, $N = 50$ data points, a signal frequency of $f_s = 0.2$, and
    a phase of $\phi_s = 0$ we obtain the following graph:

    \centerline{
        \includegraphics[width=0.5\textwidth]{dft-sine-wave.png}
    }
\end{frame}

\end{document}

Assuming that you have LaTeX installed on your local machine, and that the code is saved in a file called discrete-fourier-transform.tex, you can build the document yourself by running latexmk in the discrete-fourier-transform directory. This will create a PDF file called discrete-fourier-transform.pdf.

Here’s the output I got for the title page:

That looks good. With this foundation in place, assume that we’ve also created a corresponding repository on GitHub and have pushed the code upstream. If you want to follow along at home, or simply don’t want to copy-and-paste the code from above, you can clone the repository I created.

Getting GitHub to build the document for us

With a GitHub repository on hand, we can get GitHub to build our slides for us. To do that, we need to create a YAML configuration file in the location that GitHub expects to find continuous integration tasks, namely, .gitlab/workflows. Let’s create the directory:

$ mkdir -p .github/workflows

Using your favourite editor, create a file called ci.yml within that directory, and fill it with these contents:

name: Build slides in CI

on:
  [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-22.04

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: sudo apt install texlive-latex-recommended texlive-latex-extra texlive-luatex latexmk

      - name: Build slides
        run: latexmk

In GitHub parlance, this file is called a workflow.

We denote the workflow’s name by the value of the name keyword given at the top level.

The on keyword specifies which events will trigger a workflow. In the case here, we’ve specified that the workflow should run on pushes to any branch or on any pull requests. It’s possible to make these settings more specific, but let’s keep things simple.

Next up is the jobs keyword, which defines the jobs to run within the workflow. There can be many jobs in a workflow, but in our case, we only need one.

The keyword in the level under jobs defines a block of job-related tasks as well as the job’s name. The single job we defined in the workflow above is called build.

We’ve configured the build job to run on a host using Ubuntu 22.04 as its base Docker image via the runs-on keyword. You might wonder why I didn’t use the other available Ubuntu version (24.04), a.k.a. ubuntu-latest. Well, I had repository lookup errors when trying to install the required LaTeX packages. Hence, I reverted to the older Ubuntu version where the installation worked as expected. Stability matters. Especially when presenting worked examples.

The next keyword is called steps and defines the individual steps that the job should run.

The first step checks out our repository into our build host with the actions/checkout@4 GitHub action. The steps thereafter run shell commands via the run keyword. You can also give each step a name, as we’ve done here, so that they are easier to find within the GitHub Actions tab.

Workflows appear in the Actions tab on the GitHub repository project page. I’m still a bit confused about how the naming works here. It seems that one combines actions into a workflow. However, the overarching term is GitHub Actions, under which one defines workflows. These then contain actions. It seems a bit circular to me, but I simply might not have understood the concept yet.

Anyway, the subsequent steps in this job install the relevant Ubuntu TeXLive packages and build the slides with latexmk.

To get GitHub to follow these instructions and thus build the document, we need to add it to our repository and commit that change:

$ git add .github/workflows/ci.yml
$ git commit
[main bc389e5] Build document using GitHub's CI system
 Date: Sun Feb 8 21:49:21 2026 +0100
 1 file changed, 17 insertions(+)
 create mode 100644 .github/workflows/ci.yml

We push this change upstream to get GitHub to build our document.

$ git push
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 663 bytes | 331.00 KiB/s, done.
Total 5 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:paultcochrane/discrete-fourier-transform.git
   315cf5a..bc389e5 main -> main

Opening the Actions tab in our GitHub discrete-fourier-transform project, we see a green tick next to the workflow run. This is a good sign: the workflow ran successfully. The workflow run’s title is the commit message’s subject.

Clicking on the workflow run’s title, we’re taken to a page with further details:

Within the grey box on this page, we see the name of the job we ran: build. Clicking on the smaller white box for the job, we’re taken to the details for the job:

Here we see the steps that the job took to build everything. If we click on the “Build slides” step, the section expands, and we see its build log. If you’re following along at home, you’ll see lots of LaTeX build information. Scrolling to the end, you’ll see output like this:

The important bits are at the end, in particular these lines:

Output written on discrete-fourier-transform.pdf (6 pages, 143709 bytes).
Transcript written on discrete-fourier-transform.log.
Latexmk: Log file says output to 'discrete-fourier-transform.pdf'
Latexmk: Examining 'discrete-fourier-transform.log'
=== TeX engine is 'LuaHBTeX'
Latexmk: All targets (discrete-fourier-transform.pdf) are up-to-date

where we find out that the document was written to a file called discrete-fourier-transform.pdf and that all targets are up to date. Awesome!

Archiving artefacts from the build

Ok, so the build looks good, but does the output of that build also look good? We can’t tell right now because we have no way of viewing it. GitHub built it, but deleted it as soon as the job finished.

That’s … suboptimal. We want to check the output as well. How to do that? For this task, we want to archive the build artefacts, which we can do with the actions/upload-artifact@v4 GitHub action.

To archive our GitHub-built PDF file, we append the following step to those defined in the build job in our ci.yml workflow file:

      - name: Archive built PDF document
        uses: actions/upload-artifact@v4
        with:
          name: dft-slides
          path: discrete-fourier-transform.pdf

Now commit this change and push it:

$ git commit .github/workflows/ci.yml
[main d5ec2be] Archive built PDF document as artefact
 Date: Mon Feb 9 14:04:58 2026 +0100
 1 file changed, 6 insertions(+)
$ git push
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 585 bytes | 585.00 KiB/s, done.
Total 5 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To github.com:paultcochrane/discrete-fourier-transform.git
   bc389e5..d5ec2be main -> main

Revisiting the details page for the build job:

we see a new step appear after “Build slides” called “Archive built PDF document”. Clicking on this step, we see its log output:

This part of the log output is interesting:

Artifact dft-slides.zip successfully finalized. Artifact ID 5432273684
Artifact dft-slides has been successfully uploaded! Final size is 137788 bytes. Artifact ID is 5432273684
Artifact download URL: https://github.com/paultcochrane/discrete-fourier-transform/actions/runs/21826316227/artifacts/5432273684

because it shows that the build artefact (called dft-slides.zip) was created successfully, and we see a link where we can download it.

Of course, you could click on this link to download the archived artefacts. However, a simpler way to access build artefacts is to look at the overview page for a given workflow run. There, you’ll see a new section, called “Artifacts”:⁴

From here, you can click on the little download button on the right-hand side. This will download the .zip file that the workflow run created.

If you download that file now and open it, you’ll find the document that GitHub built:

Now things are looking good!

Finding font failures

Not very surprisingly, this result looks much the same as our earlier result. I say much the same because the results are not identical. In particular, the fonts are different. It seems that some fonts have been replaced by default ones. A quick look at the “Build slides” log output reveals:

luaotfload | db : Reload initiated (formats: otf,ttf,ttc); reason: Font "Fira Sans Light" not found.
Package beamerthememetropolis Warning: Could not find Fira Sans fonts on
input line 95.

So, the Fira Sans font that the metropolis theme needs isn’t available. This is a secondary issue that we want to fix by using an up-to-date TeXLive distribution.

Migrating to `latex-action`

Ok, we’ve got a document built on GitHub, and it’s almost producing the PDF output we expect. Now we need to get around the issue of using an outdated TeXLive distribution. Instead of using a version from 2021, we want to use a version from at least 2025.

This is what we really came here for: to see the latex-action action in action.

To be honest, the change is very simple: remove the “Install dependencies” step and swap out the current “Build slides” step with this YAML code:

      - name: Build slides
        uses: xu-cheng/latex-action@v4
        with:
          root_file: discrete-fourier-transform.tex
          texlive_version: 2025
          latexmk_use_lualatex: true

The new step uses the same name as the step it replaced, but now we’re using a GitHub action via the uses keyword instead of running latexmk.

We’re also being careful to specify a version. Theoretically, it should be possible to do without the @v4 suffix, but specifying an explicit version is good practice. This way, we ensure builds are more reproducible. Were we to leave out the version suffix, there could be future changes to latex-action that break an otherwise functioning build. Of course, updating to a new version would be a good idea once it exists, but we need to check that it works as expected before committing to it.

We configure options to the latex-action GitHub action within the with keyword block. The root_file option specifies the main file that builds the entire document. The texlive_version option specifies the TeXLive version we want to use, i.e. 2025. We also want to use LuaLaTeX when running the latexmk command, so that we get the full power of a modern LaTeX engine. Hence, we set latexmk_use_lualatex to true.

What’s the effect of this change? Well, instead of pulling in an Ubuntu Docker image and then installing the Ubuntu TeXLive packages, we now grab a Docker image with TeXLive pre-installed and use that as our build host. This gives us a complete TeXLive environment from the get-go.

Let’s see how we get on. Doing our commit and push dance:

$ git commit .github/workflows/ci.yml
[main bbe6dba] Replace Ubuntu TeXLive with latex-action TeXLive
 Date: Mon Feb 9 14:55:41 2026 +0100
 1 file changed, 5 insertions(+), 4 deletions(-)
$ git push
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 562 bytes | 562.00 KiB/s, done.
Total 5 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To github.com:paultcochrane/discrete-fourier-transform.git
   d5ec2be..bbe6dba main -> main

and letting GitHub do its thing, we find that everything builds successfully:

That’s a good sign.

If we now download our archived artefacts from the workflow overview page (note that the file size is also smaller):

we see that the font issue has been corrected:

And now we’re using an up-to-date TeXLive version! Yay! 🎉

Where to from here?

And that’s it really. Of course, there are more things you could do to extend and customise the build process.

One thing you might like to try is to add the action-gh-release GitHub action. This action automates creating releases according to Git tags. Your Git project will then host any PDF documents you deem worthy of a versioned release (and hence a Git tag) on the repository’s project page. If you want to upload draft releases, that’s also possible. This way, you can show users current development-grade releases of your LaTeX documents.

The sky’s the limit! Have fun!

Addendum: metropolis and moloch woes

One other incentive I had to use the latex-action GitHub action was a desire to replace the metropolis beamer theme with moloch.

I like metropolis. It’s clean and minimalistic, and looks rather stylish. Sadly, it’s now unmaintained, and the last release to CTAN was from 2017. It’s been replaced by its fork, a project called moloch. Its internals are cleaner, it fixes some bugs in the metropolis theme, and it is less fragile to internal changes in beamer itself.

Unfortunately, moloch is only available in recent TeXLive versions (it was first released in 2024) and hence isn’t available in the Ubuntu TeXLive packages on GitHub. Hence, my wish to migrate to a GitHub action providing an up-to-date TeXLive version.

Implementing this change while maintaining the same look led down rather a deep rabbit hole. Regrettably, I wasn’t able to solve all the problems that appeared. Thus, I decided against introducing moloch as an additional change in the main part of this article.

One major blocking issue I had was with fonts. By default, metropolis uses the Fira Sans font; moloch doesn’t: it seems to use a mixture of the Computer Modern and Latin Modern fonts. Using Fira Sans with moloch is simple enough: it’s a configuration option added in the document preamble. However, this also changed the font used for mathematics, and I couldn’t get that to look right. For instance, bold mathematics were shown with a serif font, whereas metropolis used a sans-serif font without problems. Using either the Fira Math or firamath-otf packages bundled with TeXLive didn’t help, because they currently only provide the regular typeface. The lighter typefaces aren’t yet bundled with TeXLive, thus I’m hoping a future TeXLive update might help this situation.

Oh well. Ya can’t win every day! I’m going to stick to metropolis for the time being. It still does the job well and works (for my purposes) with the current TeXLive version.

Once I realised that this detail wasn’t necessary for what I wanted to introduce in the article, I decided to leave it out of the main text. I’m guessing no one missed it but me! 😄

Does anyone remember the prosper or foiltex classes? Wow, it seems like aeons ago that I was using them. I think I’m showing my age… ↩
I’m aware that the ubuntu-24.04 a.k.a ubuntu-latest Docker image is available. However, I got errors when fetching packages. Thus, for this article, and the sake of stability for anyone following along at home, I stuck with ubuntu-22.04, where I knew that everything worked. ↩
Dorotea Avra is not the name of a real person. I generated it using a random name generation site. ↩
Note that American English spells this word as “artifact”. Since I grew up with a British English-derived variant of the English language, I spell it “artefact”. Just so you know. ↩

Finding a fisherman’s fastest path from shore to boat

Paul Cochrane 🇪🇺 — Wed, 01 Apr 2026 22:00:00 +0000

When tutoring high-school students in maths and physics, I sometimes stumble across interesting problems. In this scenario, a fisherman seeks to determine the fastest route from his location on the shore to his boat out in the water. What I find interesting here is the change of perspective that makes solving the problem easier.

Problem

Consider the figure below. A fisherman stands on the shore of a lake some distance from his boat out in the water. The distance from the fisherman to the boat is 10 m; the distance from the edge of the shore to the boat is 6 m. Using Fermat's principle, determine the shortest time it will take the fisherman to reach the boat if the speed
of the fisherman's movement along the shore is 3 m/s, and in the water is three times less.

Solution

There are several ways that the fisherman could reach the boat. He could go directly to the boat through the water, travelling the shortest distance: 10 m. Or he could move along the shore until the distance in the water is shortest (6 m), going through the water the rest of the way. Neither of these options is optimal. In one case, he doesn't make any use of the speed advantage along the shore. In the other case, he moves too far along the shore and ends up travelling a much longer distance than necessary. The best path lies between these two extremes, and that's what we have to find.

At the start, collect what we know

Let's collect some information from the question and deduce what we can to solve the problem. We're told that the fisherman's speed along the shore is 3 m/s. Let's denote this speed by $v_s$ . The speed in the water we denote by $v_w$ . We're told that the speed in the water is three times less than the speed along the shore, hence $v_w$ is 1 m/s. From the geometry of the situation, we can see that the paths in the water and the path along the shore make a scaled 3-4-5 right-angled triangle. Doubling the side lengths of a 3-4-5 right-angled triangle gives a 6-8-10 right-angled triangle.¹ In other words, the path along the shore is 8 m, which is the only side length that we didn't yet know.

Having deduced most of the information we can from the diagram and the question, the task is to find the best path from the fisherman's position on the shore to the boat. Note that this is not the shortest path. It is, however, the path that takes the least time, which is where Fermat's principle comes in.

Look at the problem from the beginning and from the end

The problem involves movement at a given velocity in one medium (along the shore) and then movement at a different velocity in a different medium (the water). Changing our perspective, we can see that we're really looking at Snell's law in ray optics.

Turning the problem on its head will hopefully make this clearer. Consider the path a light ray would take from the boat to the fisherman's initial position. Why look at the problem from this perspective? It turns out that the time to travel along a given path is independent of direction: i.e. the path from the boat is the same as the path to the boat. Changing our perspective to be from the boat, we can see that a path from the boat to the shore at some angle, then continuing along the shore to the fisherman,
is the same situation as a light ray sent from the boat and then refracted at the water-shore boundary at the critical angle.² In other words, a calculation using Snell's law at the critical angle is equivalent to the fisherman moving along the shore and then travelling to the boat through the water. This is the problem we're trying to solve, and now we have a way to do that.

Construct a solution using Snell's law

Let's examine Snell's law from the perspective of a light ray travelling from the boat. Consider the following diagram:

The blue region represents the water; the white region represents the lake shore. We have a light ray travelling from the left-hand red point in the blue region towards the white region. Its path makes an angle $θw\theta_w$ to the normal at the boundary between the two regions (i.e. a line perpendicular to the boundary between the two regions). It is refracted at this boundary and travels along the boundary interface to the second red point on the right. The ray travels at an angle $θs\theta_s$ to the normal.

Using Snell's law, we have the following relationship:

\frac{\sin \theta_s}{\sin \theta_w} = \frac{v_s}{v_w}.

We know that $v_s$ is 3 m/s, $v_w$ is 1 m/s, and that $θs\theta_s$ is $90∘90^\circ$ (equivalently: $π/2\pi/2$ radians). Since $sin⁡(π/2)=1\sin(\pi/2) = 1$ , we can simplify the expression above to:

\frac{1}{\sin \theta_w} = \frac{3}{1}.

Rearranging this equation to be in terms of $sin⁡θw\sin \theta_w$ , we have:

\sin \theta_w = \frac{1}{3}.

Taking the inverse sine, we have an expression for $θw\theta_w$ :

\theta_w = \sin^{-1}\left( \frac{1}{3} \right).

This is the angle to the normal at the boundary that a light ray would take along the path of least time between the two red points.

We can now work out the distance travelled both in the water and along the shore. Once we have that information, we can use the velocities in each medium to work out the time taken along this path. Hence, we can calculate the time along the fisherman's fastest path from his position on the shore to the boat.

From geometry, we see that the angle between the vertical solid line and the ray in the blue region is equal to $θw\theta_w$ . Thus, we can calculate the length $d_w$ , which is the hypotenuse of the right-angled triangle with sides 6 m and $d_{s'}$ :³

d_w = \frac{6}{\cos \theta_w}.

From the diagram, we know that the length along the shore (i.e. along the boundary between the blue and white regions) is 8 m. Thus, the distance the ray travels along the shore, $d_s$ , plus the remaining distance along the shore, $d_{s'}$ , is equal to 8 m. This gives us the following relation:

d_s + d_{s'} = 8.

We thus have an expression for $d_s$ in terms of $d_{s'}$ :

d_s = 8 - d_{s'}.

Again, from geometry, we can work out what $d_{s'}$ is in terms of $θw\theta_w$ by using the tangent and the adjacent side ( $d_{s'}$ is the opposite side of the triangle):

d_{s'} = 6 \tan \theta_w.

Now we know how far the distance along the shore is in terms of the angle $θw\theta_w$ :

d_s = 8 - 6 \tan \theta_w.

We're now left with the task of finding out how long it takes to travel each of the two components of the path, $d_w$ and $d_s$ . Since the speed in each medium is constant, we can write the distances in terms of their velocities and times, i.e.:

d_w = v_w t_w,

d_s = v_s t_s,

where $t_w$ and $t_s$ are the times in the water and along the shore, respectively. We can write these times in terms of distance and velocity like so:

t_w = \frac{d_w}{v_w},

t_s = \frac{d_s}{v_s}.

The total time for the fastest path, $t$ , is the sum of these two
quantities:

t = t_s + t_w,

\frac{8 - 6 \tan \theta_w}{v_s} + \frac{6}{v_w \cos \theta_w},

\frac{8 - 6 \tan \theta_w}{3} + \frac{6}{\cos \theta_w},

where I've substituted the values of the speed along the shore and the speed through the water into the final expression.

We know that:

\theta_w = \sin^{-1} \left( \frac{1}{3} \right) \approx 0.3398.

Substituting this value into the equation for $t$ above, we get:

t_s + t_w \approx 1.9595\ \text{s} + 6.3640\ \text{s} \approx 8.3235\ \text{s}.

In other words, the fastest time for the fisherman to travel from his initial position to the boat is 8.3235 s.

Numerical calculations

Below is the SageMath code I used to calculate the numerical values of $t_s$ , $t_w$ , and hence $t$ in the section above.

theta_w = asin(1/3.)
ts = (8 - 6*tan(theta_w))/3.
tw = 6/cos(theta_w)
t = ts + tw
print(f"ts = {ts.n():0.5}; tw = {tw.n():0.5}; t = {t.n():0.5}")

The first line defines a variable called theta_w containing the value of $θw\theta_w$ we calculated using Snell's law from earlier. The next two lines define the variables ts and tw, which calculate the times along the shore and through the water, respectively. The fourth line calculates the total time for the fastest path. The final line of code prints the results nicely.

Running this code gives the following output:

ts = 1.9596; tw = 6.3640; t = 8.3235

Note that the value for ts shown here is rounded up to four decimal places, and is hence different from the value I mentioned in the text. If you add the rounded ts and tw values together, you'll get a slightly different result from using the unrounded values. This is why the value for t looks like it should be 8.3236 when the correct value is really 8.3235.

Extension

Now, because I'm me, I can't simply solve something in one way and be done with it. Thus, I decided to plot the total time for paths corresponding to different $θw\theta_w$ angles, ranging from 0 (the fisherman goes 8 m along the shore and then 6 m in the water) to $θmax=cos⁡−1(3/5)\theta_{\mathrm{max}} = \cos^{-1}(3/5)$ (the fisherman follows the most direct path: 10 m through the water). I wanted to see this plot because it gives an intuitive feel for how the time is a minimum between the two extremes.

I used SageMath, an open source mathematics software system, to set up the variables and plot the graph. SageMath uses a Python-based language, hence it's fairly easy to use.

In the code below, I define a symbolic variable theta_w, corresponding to $θw\theta_w$ from above. I then define the time along the shore, ts, and the time in the water, tw, in terms of theta_w. This allows me to write the total time, t, which is then a function of theta_w. I also calculate the maximum value theta_w can have given the problem's geometry, which I've called theta_max. This way, I know the maximum value of theta_w to plot. The theta_max value corresponds to the direct path from the fisherman through the water to the boat. The minimum value for theta_w is zero, corresponding to a path perpendicular to the shore. Lastly, I plot t as a function of theta_w running from 0 up to theta_max.

theta_w = var('theta_w')
ts = (8 - 6*tan(theta_w))/3
tw = 6/cos(theta_w)
t = ts + tw
theta_max = acos(3/5)

plot(t, (theta_w, 0, theta_max), axes_labels=['$\\theta_w$','$t$'])

Here's what the plot looks like:

The graph shows the total path time for values of theta_w ranging from zero up to theta_max.

When theta_w is equal to zero, this is the same as travelling 8 m at 3 m/s and then 6 m at 1 m/s. In other words:

\frac{8}{3}\ \text{s} + 6\ \text{s} \approx 8.667\ \text{s}.

This is the value where the curve intersects the $y$ -axis, which we can see matches the plot above.

At the largest angle, theta_max, the time taken is 10 s because this is the time taken to move a distance of 10 m travelling at 1 m/s, i.e. the direct path from the fisherman to the boat.

Reading the graph, we can approximate the shortest time to be at a theta_w value of roughly 0.35, which is approximately 8.3 s. These values correspond to those we got for $θw\theta_w$ and $t$ in the solution section above.

We've effectively verified the result we got in the previous section. Yay!

Wrapping up

And that's it. Hopefully, the explanation helped you understand the problem and its solution!

It intrigues me how sometimes a maths or physics problem becomes more
tractable just by looking at it from a different point of view. If at first you find a problem difficult, try changing your perspective. 🙂

You can verify that this is still a right-angled triangle because $6^2 + 8^2 = 10^2$ . ↩
This angle is the smallest angle that would keep a light ray within the given medium. ↩
The length $d_{s'}$ is the remaining distance along the shore after the fisherman has travelled the distance $d_s$ . ↩

German Perl/Raku Workshop 2026 (Berlin): a report

Paul Cochrane 🇪🇺 — Wed, 25 Mar 2026 23:00:00 +0000

Last week, the 28th edition of the German Perl/Raku Workshop took place in Berlin. It was great to see some familiar faces (as well as some new ones!) to discuss computing, our favourite Swiss army chainsaw, and much more.

This report contains rough notes of the talks that I attended.

Getting to Berlin

Because I’m a bit crazy, and because I wanted to collect up-to-date and relevant data before my talk, I rode my bike from Hannover to Berlin. The trip was roughly 300 km long and took two days. The weather was pretty good, and I only had a nasty headwind for part of the first day. The second day went quite quickly, and once in Berlin, I decided to be a bit of a tourist for a little while and rode to the Brandenburg Gate.

Since there were several demonstrations in Berlin on that day, the Straße des 17. Juni (the road leading from the victory column to the Brandenburg Gate) was completely closed to traffic. This meant that people were walking and riding their bikes along what is usually three lanes of traffic in each direction. That was an opportunity I was glad to take! Like, when am I going to get that kind of opportunity again? Needless to say, I thoroughly enjoyed the freedom and space of riding along such a famous street.

The next day (Sunday), I happened to meet Geoffrey and Theo as they were on their way to breakfast. I didn’t expect to stumble across anyone from the workshop so soon, and it was nice to have a chat and hear how they were and what they were up to. They went off to do touristy stuff, but I decided that, after two days on the bike, spending some time at a cafe with my laptop was the more relaxing option.

Pre-workshop meetup

The pre-workshop event took place in a Bavarian-style pub a few blocks’ walk from the workshop venue. I found it amusing that we were in a Bavarian pub when we were in Berlin. However, there’s probably no such thing as a Berlin-style pub; it’s probably just a pub. The workshop took place in Munich last year, so in some sense the pre-workshop meetup venue made a connection to last year’s workshop. Given that we were the last people to leave (the staff had to be rather insistent to get us to pay and leave; they were very nice about it, though), I’d say that the conversation was at its usual excellent level.

Day 1

Last year’s workshop had a very relaxed schedule, and this year was no different. I far prefer this style to the stress of heaps of talks jammed in between 8 am and 6 pm. It’s much more laid-back and gives more time for discussions. One also has more time to process the information presented in the talks. Many thanks to the organisers for putting this together so well!

Max Maischein (Corion) - Using Coding Assistants with Perl

Although Max doesn’t use much Perl or AI in his job, he’d looked into it anyway, basically because it’s the current hype and he wanted to see how and where coding assistants can be useful. A coding assistant is built from a coding harness and a large language model. A harness is then a command execution and loop environment. Currently, common harnesses include Claude, OpenCode and Codex, whereas the models that one can use with these harnesses include Claude AI (which costs currently ~20€/month), z.ai (72€/year) or Deepseek (which is self-hosted).

There are yet others, such as OpenClaw, which act as both a harness and a model. The big deal here is that OpenClaw also has access to your email, bank account, messenger services and identity, thus it’s supposed to be able to help people organise their lives. However, the security and financial implications of letting a statistical inference engine say things for you and make transactions on your behalf, shall we say, are fraught with difficulties. Max mentioned the lethal trifecta: access to private data, ability to externally communicate, and exposure to untrusted content. It’s not a good idea to give automated services so much access, as things can go wrong in very bad ways. To avoid potential issues, Max mentioned some advice:

“Don’t YOLO outside of a container”
When giving an agent commit access to a repository, let it work on a copy of the repo, not the main repository itself
Don’t give the agent any credentials
Run agents within a VM/container

Although there are issues with using agents wantonly, they can still be useful. One can use them to generate code, run that code, check the output (e.g. via tests), and work from lists. The quality depends upon the size of the task, the quality of the surrounding code and the quality of the prompt given to the agent.

Max found that LLMs know Perl rather well, yet the style is from around Perl 5.12. They know about the need for use strict; use warnings;, which took years to bang into the heads of humans and can cope with function signatures, possibly because these are common in other languages. The coding agents mimic pre-existing code well. If one has good prompts (there exist examples on, e.g. GitHub) that provide a walkthrough of good software development, then the agent is reminiscent of an enthusiastic junior developer.

He then discussed some example projects for which he’d used coding agents and the pluses and minuses he’d discovered. Sometimes things were hard-coded when they shouldn’t have been. There was extra code added for testing, but it wasn’t used in the actual code. He found that he needed to provide the agent with good API examples, good implementation ideas, and general program structure to get acceptable output. It’s possible to give agents templates of the desired coding style so that the output matches the way one wants code to look.

Max also discussed some of the social, economic and other consequences of using coding agents.

From a social perspective, the threshold for implementing a tool is massively reduced; it’s now much easier to implement an idea. Due to the low quality of code output, they’re ok for throwaway debugging tools, but not so much for senior-dev level production code. There is also the issue of money flows and their concentration in a few select companies. The point was also made about “pulling the ladder up”, meaning that junior developers aren’t really involved in programming anymore because so much is handled by the coding agent. The level of structured thought required for programming is not really there; one describes feature lists instead. Also, one doesn’t get the opportunity to make errors and learn from them in the same way. Debugging code becomes more difficult since it’s easier to debug code one has written oneself, and the skill itself atrophies somewhat because junior devs are less likely to want to do this.

One long-term economic consequence was based on the subscription model that most hosters use. They want the service to be useful enough to you that you spend lots of money on tokens, but not so much that you want to cancel your subscription. From what I understand, many of the companies aren’t even covering their costs from the subscription income, so it’s hard to see how this model will continue to work long-term.

The talk was an informative and thought-provoking introduction to the workshop’s overall theme: Agentic Perl.

Abigail - Sharding a database, twice

Abigail has recently retired after having spent most of his working life at Booking.com. One of the experiences he had of working there was of sharding the enormous database behind Booking’s site to solve performance and size problems.

The talk wasn’t about how to shard a database–this has been described elsewhere–it gave more of the background information as to why one would want to shard a database and some of the technical challenges in doing this. A “shard” is a horizontal partition of data in a database. By sharding a database, one can reduce the disk, memory and network requirements for access to the database, especially if the database is exceedingly large.

The database at booking.com stores hotel inventory and contains ~1000 tables spanning 14 years of data. There are roughly 10^11 rows, with 10^10 to 10^11 row reads per day and 10^9 to 10^10 row updates per day. The processing was split across many read-only slave instances, yet there was only a single master and in 2013, the disks were filling up, and there was a lot of replication delay. Any downtime causes millions of Euros in lost income.

After much discussion, the booking people decided to shard the database, with the requirements that there be: no downtime, no big switch to the new system, it needed to be reversible, all data for a single hotel should be in the same shard, a shard could not influence others, it needed to be easy to reshard, and the code changes needed to be minimal.

In the end, they decided to split the database into four parts. This required updates to over 100 Perl files. They included fallbacks so that code still using legacy interfaces would still work while the new code that understood the sharding also did its job properly. They moved the data in batches, initially starting small and proceeding to larger chunks of data as they gained confidence that everything was working properly. For instance, they moved a single hotel at a time, starting with test hotels, then new hotels, then small countries and large countries and later ran everything in parallel. Once everything was moved, they removed the legacy DB handling code. The whole process from the initial meeting to all data having been moved took about 6 months.

In 2024, the database was hitting its limits again: disk space was running out, there were deadlocks and wait timeouts, as well as various I/O limits being hit. They decided to double the number of shards and used a similar process to what they used back in 2013. This time, there was a bug in the code, which caused duplicate data to appear in queries, which meant that the site showed twice the number of rooms available in hotels. Oops! Fortunately, the bug was only in one location, and they were able to fix the problem quickly, which in the end only took 30 seconds. Afterwards, they could clean up the duplicated data. This required every row in the database to be inspected twice and then for the tables to be rebuilt to reclaim space. This process took roughly 2 months to complete.

In the end, everything worked out, and the site is still chugging along well. I was left wondering if it will be another ten years before Booking needs to shard its databases again…

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Der Datentyp und die Datenbank

It turns out that it’s rather difficult to handle and store complex data types in an SQL database. It is, however, possible to get close, but it’s a lot of work. This talk explained some of the details of how to achieve that.

One can combine the available types in SQL with Boolean AND and OR to create more complex types via the UNION keyword. It would be a lot easier to do such things if database creators added native support to the databases, but it seems that this won’t happen, as SQL isn’t intended as a general-purpose programming language (something which would have the ability to create complex types from more basic types).

One example presented of representing a complex data type in a database was that of a payment type. This could be, e.g. cash, online or via credit card. The overall type is a payment, but then one can have more specific types and store these sensibly within the database. Lars showed how to do this, but it wasn’t simple, and one had to be careful about how one ordered the construction of the types and tables in SQL so that everything worked.

Flavio S. Glock - PerlOnJava: A Perl Distribution for the JVM Part 1

This was one of the most impressive talks at the workshop. The sheer amount of work, spread over many projects and many years, in order for this to work, was mind-blowing. Put very simply, Flavio has managed to get the Perl compiler and runtime working within the JVM. This is not an interpreter wrapping a Perl binary; this is Perl code compiled to native JVM bytecode, hence it can be used alongside Java, Kotlin or Scala code. His system requires Java 21+ and targets Perl 5.42+. This first talk was a high-level overview of the PerlOnJava project and some of its results.

Using the JVM makes sense in many ways because the JVM has 30 years of optimisations, meaning that its JIT ability is now very good. Also, there are 500k+ libraries that one now has access to. The JVM is also container-aware and has support for Docker/Kubernetes. And Perl can run alongside other languages which already run on the JVM, of which there are now many.

He’s managed to get Perl scripts to run unchanged on the JVM. It’s also possible to embed Perl in Java applications. The PerlOnJava application is a single jar file and has no external dependencies. It’s possible to run programs via java -jar ... or via a wrapper ./jperl script.pl.

The PerlOnJava project is derived from many earlier attempts to get Perl to run on Java and is most directly derived from the perlito project. There are 200,000 tests in the test suite and 400 Java files. Everything is JIT-optimised.

It’s possible to run pure Perl CPAN modules as-is, and there are XS modules which can use the Java equivalents. The standard Perl test suites also work as-is in this environment. Because of the large amount of optimisation in the JVM, some code runs 5x faster than a pure Perl environment. However, for string operations, Perl is 2x faster than PerlOnJava. Flavio was able to compile and run Image::ExifTool, which is a very large distribution. This is so large that it was too big for the JVM’s 64KB method size limit, yet he managed to get this to work.

Flavio S. Glock - PerlOnJava: A Perl Distribution for the JVM Part 2

The second part of this talk was the technical deep dive into PerlOnJava.

Unicode was a problem because Java handles this differently from how Perl does it, but this now works as expected.

Flavio needed to handle Perl’s special blocks, such as BEGIN, END, INIT, and CHECK, mapping them to equivalents in the JVM world.

It’s sometimes possible for large Perl subs to exceed the JVM’s 64KB method size limit. The way to solve this was to have PerlOnJava fall back to an internal VM for oversized methods. The second backend was also necessary due to CPU cache pressure: sparse JVM bytecode overflows the instruction caches, hence one needs to fall back to another backend. Also, things like eval STRING need to be handled in the internal VM because using eval like this doesn’t meet the JVM’s security measures, and if one had left it as-is, then the JVM would be running the same code each time, making things much slower. The second backend helps with getting this kind of code to run with better performance.

Flavio also handled scalars, arrays, hashes, subs/methods, and globs specially so that they translate nicely to their JVM equivalents. He described LOTS of detail about how to get Perl to work within the JVM, and there was a lot of stuff to cover to get Perl code to run as-is within the JVM. One comment he made summed this up nicely: “Perl was never designed for the JVM - but careful engineering makes it work”.

There were some limitations, because not everything maps 100% from Perl to the JVM: fork isn’t available on the JVM, and there didn’t seem to be a solution to that just yet. Also, DESTROY can’t work because of the nondeterministic nature of the JVM’s garbage collection.

Nevertheless, this was impressive work! Wow!

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Aus dem Nähkästchen

In this talk, Lars showed technical things that help him personally and at work.

For instance, he shares his dotfiles in a repo on GitHub.

There are some tools available to get better diffs in git than the defaults. E.g. delta, difft and the --color-words option to the standard diff command.

Some tools were replacements for existing and common Unix tools, which also enhance the standard behaviour. For example: eza is a replacement for ls, zoxide is a replacement for cd, and xh is a replacement for curl.

He also mentioned mise, which is a version manager for programming languages and tools. Instead of using perlbrew, rustup, and so on, one only needs the single tool.

Handy to know!

Thomas Klausner (domm) - Using class

In this talk, domm introduced us to the class keyword that has been available since Perl 5.38. Perl also has the field and method keywords, which make it possible to write modern OOP code in core Perl. field is like has in Moose. The Object::Pad project is being used as a test bed for new OOP features in core Perl, and slowly, the stable features from that distribution are making their way into the core language. Paul Evans has been doing a huge amount of work to get this going.

domm showed how he used the new Perl OOP features to handle conversion from one bibliographic format to another (MAB2 -> MARC21).

MAB2 (Maschinelle Austauschformat für Bibliotheken) is from 1973, and MARC21 is originally from the 1960s and was updated in 1999 and is now XML-based.

domm wrote a set of classes to handle conversion from one format to the other.

Some notes about Perl’s new OOP features:

The :reader keyword automatically creates an accessor from a field.
The :param keyword allows the field to be set at instantiation.
The ADJUST keyword allows code to be called during object construction.
method uses function signatures directly; automatically provides $self, thus it’s no longer necessary to do my $self = shift; anymore.

It was nice to see the new OOP features being used in a real-world project rather than the standard Point class or something similar. Real-world code tends to bump up against the sharp edges of reality more, and hence, one can better see if the new features are applicable in other less-than-pure situations.

Lee Johnson - I Bought A Scanner (No, Really This Time)

In a previous talk, Lee had discussed a scanner that he’d been thinking of buying, but it turned out to be waaaay too expensive and much too outdated to use. Its quality was second-to-none, though, hence why he’d considered the purchase in the first place. This would have been one way for him to get scans of photos from his various multi-year photographic projects that would have good quality. This new talk described the scanner he ended up getting.

One thing I didn’t know is that the new security scanners at airports destroy photographic film. I guess there just aren’t that many people going through airports with old-fashioned film anymore. This makes things rather difficult for people who travel with old-style cameras, and hence Lee travels with a film-based camera much less frequently now.

The scanner he’d originally considered, which would allow him to scan large prints in good quality, required proprietary software, was last updated in 2012 and required a 32-bit architecture to run. Thus, he needed an old Mac running a very old version of MacOSX for things to work at all. Thus, the system can’t ever be updated, and it’s difficult to know if the hardware and software will continue working in the future. Also, the connector used FireWire, which was dodgy, breaking down and having connection issues, so that made things even harder. The scanner itself was EOL, and the physical ports were dying.

One alternative that he considered was to use a high-resolution camera to take digital photos of the film. This did seem a bit odd because one is taking a photo of a photo just so that one can get a digital rendition of the original. I can totally see the point, though, as in essence that’s what a scanner is doing, albeit in much better quality. One issue with using a digital camera is keeping the film flat, because even a small amount of curvature in the film creates a large change in the scan.

The scanner he found and bought was cheaper than the previous scanner he was looking at, and is basically an older model of what he’d been looking at. One positive aspect was that it used SCSI, which is more robust than FireWire. Although using a digital camera to scan film can come close to the quality of what the scanner created, it wasn’t good enough. The scanner scanned the images well within specifications (Lee used a special reference to check).

The main downside is that the scanner only works with a MacG4, and it won’t last forever. Effectively, the scanner will stop working due to the “upgrade treadmill”, which Lee then discussed in depth. He mentioned many instances and issues with trying to keep old hardware and software running just to use what is, in reality, still good equipment. He mentioned that the upgrade treadmill seems to be getting faster or is becoming steeper; some people at work are effectively employed to just keep updating dependencies for the main software systems. This seems like a crazy situation to be in; however, I’ve experienced it myself at previous jobs. Keeping up with the updates of dependencies, or swapping out dependencies if they go EOL and one has to find a replacement, took up a lot of time from what could have been spent on actual software development.

Lee has now been able to get high-quality scans of many of the photos from his various projects, so that part of the story had a happy end.

Day 2

Richard Jelinek (TheWhip) - Perl mit AI

This talk was split into two parts: the first part described the trials and tribulations he’d faced in installing and setting up controlling and monitoring systems in houses for friends and family. The second part presented his implementation of a JIT-ed and parallel Perl.

When constructing the various houses, he wanted to use a Perl-based solution for the controlling and monitoring system. However, one system, MisterHouse, was dead, and another, FHEM, was difficult to use. In the end, he wrote his own and, to a certain degree, created his own hardware for the monitoring solution. A lot of this was guided by AI to get all of the various parameters within the desired specifications and to get the code written.

Richard had wished for a Perl that ran in parallel for a long time and mentioned his wish-list for such functionality. He then implemented a system of his own with the help of AI and showed a demonstration of using his parallel and JIT-ed Perl to render the Mandelbrot set.

Alexander Thurow (Alex) - Thoughts on (Modern?) Software Development - Beobachtungen von einer 21-jährigen Reise

Alex shared lots of advice and anecdotes from many years of programming and helping teams do software development. He’s now a freelancer doing software development, mentoring, communication, and software development culture; the slides from his talk are available on https://onmoderndev.de.

He discussed diverse “soft” topics in software development and the interactions between people when doing software development. He noted that continual learning is the key to mastery in every field. It’s difficult to deal with differing requirements in projects, e.g. quality versus time/budget, maintainability versus time-to-market, etc. He mentioned that communication is one of the most difficult things we can do as humans. And because code is communication, it’s important to realise that if you think that code is completely stupid, then it’s a sign that one doesn’t know what the pressures were that created the code. In other words, context is very important when reading old code from someone else.

He also mentioned that in IT, we seem to work in cycles; topics, themes, frameworks, and ideas keep repeating. Thus, if one is aware of the basic patterns, then one can adapt to the latest trends and frameworks.

He also discussed several challenges at the micro and macro-level of software development and their effect, e.g. at a societal level.

He recommended many books, talks, and blog posts, for example:

Book: “The mythical man-month” by Fred Brooks
Book: “Pragmatic thinking and learning: refactor your wetware” by Andy Hunt
Talk: Fantastic biases and where to find them in software development (Michael Kutz and João Proença)
Blog series about refactoring: https://www.digdeeproots.com/articles/on/naming-process/

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Hierarchien in SQL

Lars showed how to describe graph-like hierarchies in SQL. It wasn’t 100% clear to me where the impetus came to do this, but it was impressive that it’s possible.

Sören Laird Sörries - Digitale Souveränität und Made in Europe

These days, we rely more and more on digital services and many of the big players that we rely on most are based in the US. This is sort of like having a single point of failure in a software system. Thus, there is a movement to migrate one’s online services to equivalent ones in the EU. It seems that it’s possible to migrate to “100% made in Europe” for software services; however, it seems practically impossible in the case of hardware. One other reason for such a movement is to reduce the fallout from enshittification coming from large tech companies.

Sören then discussed various categories of services and mentioned providers that one could use in the EU. Services include: Payments, Cloud, Email, Chat, Office suites, Maps/Navigation, Search, Social media, Music, Video conferencing, and Translation. It turns out that there is a wealth of available services in the EU to choose from that have the same functionality as the large tech companies. The alternatives often seem to be based in Germany, France, the Netherlands or Scandinavia.

Salve J. Nilsen (sjn) - What might a CPAN Steward organization look like?

The EU’s Cyber Resilience Act has far-reaching consequences for manufacturers and their products. Basically, that means that any product bearing the CE label requires the manufacturer to be liable for the security of their products, including any open source components in the dependency tree. The documentation has to be up to date and correct, and the metadata has to be complete and not misleading. They also need to be able to respond to risk assessments and maintain compliance.

Some products can have tens of thousands of dependencies, most of which are open source, and hence manufacturers have to show that they have done due diligence in ensuring their products and the software that their products depend on are secure and standards-compliant. This is a huge task, hence Salve has come up with the idea of a community-owned non-profit steward cooperative. The idea being that projects can come under this umbrella, and manufacturers can pay for a kind of time-limited certificate showing compliance for the Perl-based software that they’re using. This takes a lot of the work off the shoulders of manufacturers to show that their software is compliant and could potentially funnel a lot of money into the open source Perl community, which could then be used to give maintainers a living wage, fund conferences and meetups such as the Perl Toolchain Summit. The steward is there to support projects and try to sustain them over time.

It’s definitely an interesting idea and would be great if something like that could work. If one considers the amount of money some companies make from software that they can use for free, then funnelling even a small part of their profits back to the open source maintainers would be awesome.

Day 3

Harald Jörg (haj) - Talking to PipeWire

Following on from Harald’s talk from last year’s workshop (Sound from Scratch) in which he generated sound directly from Perl, he wanted to detect things such as when a microphone is plugged in or when a sound was played by an external program. For this task, he used PipeWire, which

provides a low-latency, graph-based processing engine on top of audio and video devices that can be used to support the use cases currently handled by both PulseAudio and JACK.

Of course, he wanted to be able to use PipeWire from Perl, hence he needed to interact with the C-based library somehow. He tried out the API tutorial, then Inline::C, then h2xs, but found that it wasn’t very easy and eventually landed on FFI:Platypus as the method which worked best in order for Perl to communicate with PipeWire.

Because XS isn’t so easy to use, and because Dave Mitchell wants to rewrite the XS tutorial, Harald wanted to wait until Dave has finished with the tutorial before trying out XS again.

With FFI::Platypus, one can build C interfaces without XS. It’s possible to use this module to make a connection to PipeWire, but some C code was necessary to get everything to go properly. Harald found that some functions were defined as static, which meant that FFI couldn’t find them automatically. It turns out that there’s a workaround for this issue, which lets everything work. Thus, one can make static functions and macros available to Perl via self-written wrappers. However, if there are lots of structs, then there is a lot of manual translation of C declarations necessary in order for everything to work, and it turns out that there are several constructs in PipeWire which can’t be mapped to FFI::Platypus.

To work around these issues, Harald used Convert::Binary::C, which operates on C header files and sources (ironically, not on binaries). CBC gave insight into the C constructs, which then helped create Perl classes equivalent to the C structs and might also help with creating XS typemaps.

He ran into a bug when trying to play sound with threaded Perl, which caused a segfault. It turns out that the issue doesn’t arise when using non-threaded Perl. Since most Linux distributions provide a threaded Perl, it’s necessary to build Perl yourself (which itself builds a non-threaded Perl by default) to work around the problem.

Harald managed to get a lot of what he wanted to achieve to work, but he won’t be able to get much further with his initial goals. To get as far as he did, it was necessary to use a current, stable Linux version, a non-threaded Perl and a recent GCC version to get everything to compile. The CBC config is rather fragile and difficult to get just right.

He found that FFI::Platypus was easy to learn, and it works with libraries from various languages. However, it needs declarations for every function call and every data type, which is a lot of work. It didn’t work out of the box with the libraries he tried so far, yet there are workarounds, but they are tedious. He also found Convert::Binary::C to be a good companion to FFI::Platypus or XS, but it was not a replacement. CBC allows introspection and code generation, which one can then use with FFI or XS wrappers. Unfortunately, it doesn’t support GCC extensions, which some libraries use extensively. Also, its configuration can be tedious and brittle.

I liked Harald’s overview of what’s possible with XS and FFI::Platypus for getting Perl to work with libraries from other projects. I have only really played with XS, and it’s interesting to see what other options are available and what the plus and minus points of each are.

Herbert Breunung (lichtkind) - Raku Grammars

Herbert started his talk by explaining a bit of the background of the Raku language, its community and ecosystem. Then he spent some time showing examples of Perl and Raku code and contrasting the differences in behaviour. This was presented as a kind of quiz to see how well-known things from Perl work in Raku. Then he started to introduce grammars in Raku and showed that it’s very easy to generate a parser for a given grammar definition. Unfortunately, due to time constraints, he wasn’t able to finish discussing all the things he’d planned to discuss.

Raja Renga Bashyam - Perl’s T20 to Test Match Moments of Fibenis: Adaptive system evolving on Natural Lang. Principles

Raja travelled all the way from India to give a talk at the workshop. I found that very impressive! The workshop has become much more international, with participants coming from England, the Netherlands, Austria, Switzerland, the US, as well as, of course, Germany. But wow, to have a visitor from so far away made an impression.

Raja works at the company Webstars Codegram Informatics, which creates the Fibenis tool. His talk contrasted various aspects of Perl with the game of cricket. As someone originally from a Commonwealth country, I could completely relate to the idea. Interestingly enough, I left the Commonwealth before the T20 variant of the game became popular; I’m much more familiar with the 1-day and test match (5-day) cricket variants.

One can compare some roles in cricket with roles that Perl takes. For instance:

Bowling: the delivery maps to shell and automation
Batting: the score maps to text and regex
Fielding: the defence maps DB abstraction
Keeping: the catch maps to debug and pre-compiling

However, some players in cricket can perform many roles. These are called “allrounders”, and Raja presented the case that Perl is an allrounder.

In cricket, there are three main variations on the game: T20, which is fast-paced and lasts only three hours; one-day matches, which have 50 overs for each side, and take roughly one day to play (actually about 7 hours); lastly, there are test matches, which take 5 days of roughly 7-8 hours each to play. When comparing cricket to Perl, we can make the association that T20 is like one-liners: short and fast. Then one-day matches are like mini tools and utilities. And finally, test matches are like large-scale applications. Thus, Perl is an all-format all-rounder, i.e. can play any game variation and can fulfil many roles.

Raja then spent the rest of the talk describing how his company uses ideas and patterns from Perl to create flexible web-based applications for their customer’s needs. Interestingly enough, the example code that he showed was in PHP. I asked him about this afterwards, and he said that yes, some of the code had moved to PHP, but the basic ideas that had been taken from Perl were still there. He also mentioned that his company plans to open-source its software in the future.

Paul Cochrane (ptc) - Getting FIT in Perl

Next came my talk, where I described the Geo::FIT module, which one can use to parse Garmin FIT files. I discussed examples of what data is available in such files and what one could (potentially) do with that data. There were a couple of questions at the end of the talk, so I get the feeling that it went down ok. One thing that probably didn’t come across in the demo at the end of the talk was that the file I analysed and displayed data from was taken on one of the stages of my trip from Hannover to Berlin. The bike trip was thus in a way a requirement for the talk so that I had fresh data to play with.

The slides of my talk are available on my talks page.

Julien Fiegehenn (simbabque) - Turning humans into SysAdmins (without having to be one first)

Many of Julien’s recent talks have been about how to turn young developers into Perl programmers (or software developers in general). Because he’s been through the German apprenticeship system and now lives and works in the UK, he’s made a modified version of that system for his company so that it works within the British context.

This time, Julien was presented with a difficult problem: how to create a similar career development and progression program for sysadmins? This is especially challenging as a trainer if one isn’t a sysadmin oneself. Since none of the sysadmins at work had the time or desire to train newcomers, it fell on him as a trainer to come up with a solution. His strategy involved a mix of human and AI information to come up with such a training program. He interviewed the sysadmins at work to find out what their day-to-day work involved. Then he fed the transcripts of the interviews as well as the structure of the German software developer apprenticeship program into Google Gemini to iteratively create teaching materials for new sysadmins. With lots of iteration and plenty of review by actual humans (that was an important part of the process), he was able to create teaching materials, sysadmin guidelines, as well as a clear training progression path for new sysadmins. It was necessary to go through everything page by page and chapter by chapter to really understand everything, not only at a high level. In the end, he wrote most of it himself, yet the AI was useful in getting the initial structure and content in place. The documents were then taken to the sysadmin team and discussed with them so that they could give feedback and improve everything. In the end, it seemed like the project was a success, so hopefully, Julien will be turning humans into sysadmins in the near future.

Thomas Klausner (domm) - Deploying Perl apps using Podman, make & gitlab

domm had given talks in the past about deploying Perl apps using Docker, GitLab and Kubernetes, as well as using Podman and Ansible for Perl app deployment. This talk was another variation on this theme.

Building and deploying applications takes place in the CI pipelines within GitLab. He’d developed this particular pattern in the context of his company, Validad, where he has lots of Perl backends running in containers. Using Podman simplifies deployment because it’s much like Docker, and one can use podman-compose, which is like docker-compose to build and run container-based applications. Also, since all his backends are small and run in one stage on one node, there’s no need for fancy autoscaling, hence one can avoid, e.g. Kubernetes. He uses systemd to start and stop services, uses gopass for secrets management, and most of the processes are coordinated via Makefiles, which call Ansible playbooks to do the actual deployment.

Using containers simplifies application development, and he gave some advice on how to use containers well, e.g.:

One should use multi-stage builds to reduce image size.
There should be one service per container.
There’s no need for local::lib or perlbrew inside a container.
One can use well-known paths within containers instead of setting them dynamically in a configuration file.
One can use volume mounts to get files from a node to the container and then share these between containers.
One should pass the environment config to the container via environment vars, or as an env file.

I found his presentation of Podman interesting because I’ve only ever used Docker myself, and finding out about this alternative was good information to learn. Podman calls itself “the best free and open source container tools”. Some of the advantages of Podman are that it can run rootless, doesn’t need a daemon (which Docker does), and one can run a container as a given user (Docker usually runs the container as root, which can be a security issue). The docker-compose equivalent isn’t as good as what’s available in Docker, and it uses a Containerfile instead of a Dockerfile, but it sounds to be much the same as what’s in Docker. Podman can create a pod, which is a collection of containers, all sharing a network.

As mentioned above, domm uses systemd to run user-specific services and finds that it works well together with Podman.

Application deployment is triggered with a special git tag with a specific deployment name. Thus, not each push gets built, tested, and its container deployed. This saves on resources, and the devs have direct control of when an application is deployed. Deployment is then handled by special make targets.

In the Makefiles, there’s a lot of intelligence built into the make targets to create the relevant deployment tags and push new code. One can use, e.g. make release stage=beta to deploy an application to the staging environment (the testing environment is called alpha, however, prod is still called production).

Lots of work has also gone into configuring GitLab-CI so that it works the way he wants. He makes use of child pipelines for various subtasks and avoids putting all steps within a CI pipeline; all steps are wrapped behind appropriate make targets, thus running things in CI is often as simple as running make. With the setup used here, he’s also able to run the deployment locally by using the same make commands and hence without needing GitLab-CI. This turns out to be very handy for testing deployment process changes.

One thing about this whole setup is that I’ve created similar processes at my previous job and in other projects, so it’s interesting to see familiar patterns appear in someone else’s workflow. As they say: great minds think alike!

Getting home

And with that, the conference was over. I went back to the hotel and did a lot of packing, unfortunately, not being able to squash everything back into my bags as compactly as I did on the way here. I had good fortune in that it didn’t rain on the way home!

That evening, a few of us met up at an Italian restaurant, which was very helpful for me, because I needed to carbo-load for the following two days. After a yummy meal, and more interesting discussions with familiar faces, I headed back to the hotel to try to get some sleep before setting off early the next morning.

The following two days went well; there wasn’t much wind, and on the second day, it came a little bit from behind me, which was nice. After many muesli bars and packets of nuts and raisins, I arrived home safely. Next year, I also plan to ride my bike to the workshop, but it won’t be as far as this year.

Many thanks to the organisers, sponsors and participants for a fun workshop!

GPW2027

Talking about next year’s workshop, Julien and I put ourselves forward to organise the workshop in Hannover in 2027. We’d been throwing the idea around for about the last 9 months and decided to take the plunge.

See you next year in Hannover!

Avoiding empty strings in non-nullable Django string-based model fields

Paul Cochrane 🇪🇺 — Wed, 11 Mar 2026 23:00:00 +0000

Trying to save a null value to a non-nullable field in Django will raise an IntegrityError, right? Well, not always. It turns out that Django saves string-based model fields as the empty string into the database instead. Usually, this is ok. For those times that it isn’t, you’ll need to add a constraint. Here, I explain how the situation arises and how to avoid it, if you want to.

Stumbling over unexpected (to me) behaviour

Last year, while working on a web application for a client,¹ I stumbled over a small detail in Django that I’d not been aware of. The detail was that Django saves non-nullable string-based model fields into the database as the empty string. I expected that trying to save a non-nullable field (i.e. one where null=False) would raise an IntegrityError, protecting me from doing anything silly. After all, that’s how most of the model fields behave. Unfortunately, not for string-based fields. So, the issue–if it is one for you–won’t manifest itself until you’re debugging some unexpected behaviour or happen to notice that a test passes when you expect it not to.

To be clear: in most cases, this is not a problem. This, I think, at least partly, is why this is the expected behaviour.

Let me explain. When you build a standard three-tier web application in Django, your form and Django’s default model field settings will protect you when users enter empty values into fields that shouldn’t be empty. The subtlety arises when you have code that saves data by manipulating model objects. Say you’re importing pre-existing data from CSV files; you’re not going to enter everything through an HTML form. You’ll write Python code to automate the process. But if the input data is missing a required string-based field, then you’ll pass None (unwittingly or otherwise) as that field’s value. Django will convert the None value into an empty string and save that value to the database. It does this even though every other kind of model field in Django would raise an IntegrityError in the same situation. This is what surprised me.

Fortunately, I wasn’t the first person to spot this issue. Clifford Gama noticed this, mentioned the issue in the Django forum, and submitted a pull request to the Django documentation (now merged) to clarify the situation. Yay Open Source Software development! He also described how to make Django enforce a non-null constraint on string-based fields, should you want to ensure their data integrity.

Since this subtlety in behaviour tripped me up, I thought I’d show how it can appear and present the solution that Clifford described.

Working with wibbly wobbly widgets

Imagine a Django application called “Wibbly wobbly widgets”.² If we make a model with a string-based field, we can observe its default behaviour. Later, we can constrain that behaviour to avoid saving null data.

Building a basic backend application

Putting the project setup on overdrive, you can imagine doing something like this to get up and running:

# create base directory; would also be Git repo base
$ poetry new wibbly-wobbly-widgets
$ cd wibbly-wobbly-widgets/

# add dependencies
$ poetry add django@^4 # install Django; implicity creates .venv
$ poetry add pytest-django@^3 # a pytest that plays with Django
# pytest needs six as a dependency, but didn't install it ... weird
$ poetry add six

# activate the environment
$ source .venv/bin/activate

# create the Django project; config dir contains settings.py
$ django-admin startproject config wibbly_wobbly_widgets

# change into the project directory
$ cd wibbly_wobbly_widgets

# create the Django app
$ python manage.py startapp wwwidgets

# run initial migrations
$ python manage.py migrate

With the basic project and app structure in place, we can add a model to models.py:

from django.db import models

class WobblyWidget(models.Model):
    name = models.CharField(unique=True, max_length=32)
    wobble_factor = models.FloatField(default=1.0)

Now we can name our wobbly widgets and specify how much they wobble. Because we’ve not specified a default value, the name field should be required. If we don’t specify the wobble_factor, then they get a default value.

We can test the model’s behaviour by putting these tests into tests.py:

from django.test import TestCase

from wwwidgets.models import WobblyWidget

class TestWobblyWidget(TestCase):
    def test_saving_widget_sets_all_fields(self):
        bungo = WobblyWidget.objects.create(
            name="Bungo",
            wobble_factor=2.3,
        )

        self.assertEqual(bungo.name, "Bungo")
        self.assertEqual(bungo.wobble_factor, 2.3)

    def test_saving_widget_without_wobble_sets_default_value(self):
        bungo = WobblyWidget.objects.create(name="Bungo")

        self.assertEqual(bungo.wobble_factor, 1.0)

Ensuring that we’ve added the app to the INSTALLED_APPS configuration in config/settings.py:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'wwwidgets',
]

we can make our migrations and run them to wire up the first stage of the application:

$ python ./manage.py makemigrations
$ python ./manage.py migrate

Running the tests, we see that the basic setup works:

$ DJANGO_SETTINGS_MODULE=config.settings pytest wwwidgets/tests.py
================================ test session starts ================================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0
django: settings: config.settings (from env)
rootdir: /home/cochrane/tmp/wibbly-wobbly-widgets
configfile: pyproject.toml
plugins: django-3.10.0
collected 2 items

wwwidgets/tests.py .. [100%]

================================= 2 passed in 0.41s =================================

All green!³ Yay!

Tacking on a frontend

But we don’t really have a full Django app yet. This is only the backend; we need a frontend as well. Time to add a view and a form.

Add this code to views.py:

from django.views.generic.edit import CreateView

from .models import WobblyWidget

class NewWobblyWidgetView(CreateView):
    model = WobblyWidget
    fields = " __all__"

With this view, Django can make a form for us to create new wobbly widgets. In this case, we’ve told Django to use all fields in the form. We’ll call the view from urls.py in a moment.

Now create a templates directory within the Django project directory (i.e. where manage.py lives):

$ mkdir templates

and create a template file therein called wobbly_widget_create_form.html. Fill this file with the following content:

<html lang="en-NZ">
  <head>
    <meta charset="UTF-8"/>

    <title>New Wobbly Widget</title>
  </head>

  <body>
    <h1>Create a new Wobbly Widget</h1>

    <form method="post">
      {% csrf_token %}
      {{ form.as_p }}
      <input id="save-button" type="submit" value="Save">
    </form>
  </body>
</html>

This is just enough HTML and Django template code to make a basic web form where we can enter data into the fields that the NewWobblyWidgetView creates for us automatically.

For Django to find this template, we need to add the templates path to the DIRS option of the TEMPLATES configuration in settings.py:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ["templates"],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

We’re not quite there yet. The last step is to wire up the view with its URL path and its associated template in urls.py:

from django.contrib import admin
from django.urls import path

from wwwidgets.views import NewWobblyWidgetView

urlpatterns = [
    path('admin/', admin.site.urls),
    path(
        "",
        NewWobblyWidgetView.as_view(
            template_name="wobbly_widget_create_form.html"
        ),
    ),
]

With that done, we can start the local development HTTP server:

$ python manage.py runserver

and feast our eyes on our creation by opening http://localhost:8000 in a browser:

It’s alive!

Saving empty form fields is a no-no

With a complete, albeit toy, application running, we can try saving the form data without entering a value into the Name field. Django will tell you you can’t do that:

Great! That’s the behaviour we want. After all, the default settings for Django model fields are null=False and blank=False. In other words, these two lines of code are equivalent:

# implicit
name = models.CharField(unique=True, max_length=32)
# explicit
name = models.CharField(unique=True, max_length=32, null=False, blank=False)

HOWEVER…

That’s me in the corner. That’s me with my ORM, losing my integrity

Let’s extend the tests to check that saving a WobblyWidget without setting the name field raises an IntegrityError, i.e., that saving null data to the database is disallowed:

    def test_saving_widget_without_input_barfs(self):
        with self.assertRaises(IntegrityError):
            WobblyWidget.objects.create()

Running the tests, you’ll see that this test fails:

$ DJANGO_SETTINGS_MODULE=config.settings pytest wwwidgets/tests.py
================================ test session starts ================================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0
django: settings: config.settings (from env)
rootdir: /home/cochrane/tmp/wibbly-wobbly-widgets
configfile: pyproject.toml
plugins: django-3.10.0
collected 3 items

wwwidgets/tests.py .F. [100%]

===================================== FAILURES ======================================
______________TestWobblyWidget.test_saving_widget_without_input_barfs______________

self = <wibbly_wobbly_widgets.wwwidgets.tests.TestWobblyWidget testMethod=test_saving_widget_without_input_barfs>

    def test_saving_widget_without_input_barfs(self):
        with self.assertRaises(IntegrityError):
> WobblyWidget.objects.create()
E AssertionError: IntegrityError not raised

wwwidgets/tests.py:26: AssertionError
============================== short test summary info ==============================
FAILED wwwidgets/tests.py::TestWobblyWidget::test_saving_widget_without_input_barfs - AssertionError: IntegrityError not raised
============================ 1 failed, 2 passed in 0.52s ============================

Hang on, what? That should barf, shouldn’t it? After all, we set (either implicitly or explicitly) null=False on the model field. Aye, there’s the rub: this is actually expected behaviour:

Avoid using null on string-based fields such as CharField and TextField. The Django convention is to use an empty string, not NULL, as the “no data” state for string-based fields. If a string-based field has null=False, empty strings can still be saved for “no data”. If a string-based field has null=True, that means it has two possible values for “no data”: NULL, and the empty string. In most cases, it’s redundant to have two possible values for “no data”. One exception is when a CharField has both unique=True and blank=True set. In this situation, null=True is required to avoid unique constraint violations when saving multiple objects with blank values.

This is the important part of that quote:

The Django convention is to use an empty string, not NULL, as the “no data” state for string-based fields. If a string-based field has null=False, empty strings can still be saved for “no data”.

Time for me to update my mental model of how Django’s model fields work.

Diving deep into Django’s database dealings

Let’s have a look at this in detail.⁴ We’ll use a combination of the sqlite3 command line and the Django interactive shell.

Opening the database and having a quick look inside, we see the available tables:

$ sqlite3 db.sqlite3
SQLite version 3.34.1 2021-01-20 14:10:07
Enter ".help" for usage hints.
sqlite> .tables
auth_group django_admin_log
auth_group_permissions django_content_type
auth_permission django_migrations
auth_user django_session
auth_user_groups wwwidgets_wobblywidget
auth_user_user_permissions

Looking in the wwwidgets_wobblywidget table, we see that it’s initially empty:

sqlite> select count(*) from wwwidgets_wobblywidget ;
0

So far, so good. This is what we expect since we’ve not added any objects to the database yet.

In a separate terminal session, start the Django interactive shell, import the WobblyWidget class, and create an object with all attributes set:

$ ./manage.py shell
Python 3.9.2 (default, Jan 25 2026, 13:37:52)
[GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from wwwidgets.models import WobblyWidget
>>> WobblyWidget.objects.create(name="Tobermory", wobble_factor=7.9)
<WobblyWidget: WobblyWidget object (1)>

Checking the database table in sqlite directly (i.e. not through the Django ORM), we see a new row in the table:

sqlite> select count(*) from wwwidgets_wobblywidget ;
1
sqlite> select * from wwwidgets_wobblywidget ;
1|7.9|Tobermory

This is what we expect: we have one object, and it has its name and wobble_factor fields set. All good.

Now return to the Django shell. Create an object without a name:

>>> WobblyWidget.objects.create()
<WobblyWidget: WobblyWidget object (2)>

… which feels weird, because my gut feeling says that “shouldn’t” work. But anyway.

What does the database say?

sqlite> select * from wwwidgets_wobblywidget ;
1|7.9|Tobermory
2|1.0|

Ok, there’s a second entry there. The wobble_factor field has the default value of 1.0, as it should. And there’s “nothing” in the name field. But what’s really in that field? Let’s put quotes around the value to see:

sqlite> select printf('"%s"', name) from wwwidgets_wobblywidget where id=2;
""

Yup, that’s definitely the empty string.

What did this achieve? Well, we verified the documented behaviour. This is a Good Thing™. It also helps reinforce our new mental model of how this actually works.

Note that for other model fields, setting the attribute to None will raise an IntegrityError as per normal.

For example, we can try setting wobble_factor=None when creating a WobblyWidget object within the Django shell:

>>> WobblyWidget.objects.create(wobble_factor=None)
Traceback (most recent call last):
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/utils.py", line 89, in _execute
    return self.cursor.execute(sql, params)
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/sqlite3/base.py", line 328, in execute
    return super().execute(query, params)
sqlite3.IntegrityError: NOT NULL constraint failed: wwwidgets_wobblywidget.wobble_factor

and this fails with an IntegrityError.

This is also good. It’s also the expected, documented behaviour.

Sticking shackles on strings

But Paul, what if we want to raise an IntegrityError when saving None to non-nullable string-based fields? Django gives us the flexibility to do this. And Clifford described exactly how: we need to add a constraint to the model.

Opening up models.py again, we add a Meta class inside the WobblyWidget class, and define the non-null constraint there:

    class Meta:
        constraints = [
            models.CheckConstraint(
                check=~models.Q(name=""),
                name="name_field_non_empty",
            ),
        ]

The argument to the CheckConstraint’s check option, ~models.Q(name=""), means: “check that the name field is not the empty string”. The ~ character is the Boolean NOT operator, which is the negation of the Q object’s query. Django shows the value of the name option in error messages when the constraint is violated. Using a descriptive name for the constraint can save much pain when debugging an error in the future.

With that in place, we need to remove our erroneous database table entry before we can migrate this change. Delete the entry within sqlite like so:

sqlite> delete from wwwidgets_wobblywidget where id=2;

Is it gone?

sqlite> select * from wwwidgets_wobblywidget ;
1|7.9|Tobermory

Yup. All good.

(Note: if you don’t remove this entry, then running the database migration that adds the constraint will fail.)

Making the migration and running it:

$ python ./manage.py makemigrations
$ python ./manage.py migrate

means that when we run the tests again:

$ DJANGO_SETTINGS_MODULE=config.settings pytest wwwidgets/tests.py
================================ test session starts ================================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0
django: settings: config.settings (from env)
rootdir: /home/cochrane/tmp/wibbly-wobbly-widgets
configfile: pyproject.toml
plugins: django-3.10.0
collected 3 items

wwwidgets/tests.py ... [100%]

================================= 3 passed in 0.39s =================================

… they pass! 🎉

Returning to the Django shell, we’ll see that adding a WobblyWidget without a name now fails as desired:

>>> WobblyWidget.objects.create()
Traceback (most recent call last):
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/utils.py", line 89, in _execute
    return self.cursor.execute(sql, params)
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/sqlite3/base.py", line 328, in execute
    return super().execute(query, params)
sqlite3.IntegrityError: CHECK constraint failed: name_field_non_empty

By the way: passing the empty string to the name field will do the same thing:

>>> WobblyWidget.objects.create(name='')
Traceback (most recent call last):
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/utils.py", line 89, in _execute
    return self.cursor.execute(sql, params)
  File "/home/cochrane/tmp/wibbly-wobbly-widgets/.venv/lib/python3.9/site-packages/django/db/backends/sqlite3/base.py", line 328, in execute
    return super().execute(query, params)
sqlite3.IntegrityError: CHECK constraint failed: name_field_non_empty

We can even add a test for this case, to really nail down the specified behaviour:

    def test_saving_widget_barfs_when_name_is_empty_string(self):
        with self.assertRaises(IntegrityError):
            WobblyWidget.objects.create(name="")

Running the tests again:

$ DJANGO_SETTINGS_MODULE=config.settings pytest wwwidgets/tests.py
================================ test session starts ================================
platform linux -- Python 3.9.2, pytest-8.4.2, pluggy-1.6.0
django: settings: config.settings (from env)
rootdir: /home/cochrane/tmp/wibbly-wobbly-widgets
configfile: pyproject.toml
plugins: django-3.10.0
collected 4 items

wwwidgets/tests.py .... [100%]

================================= 4 passed in 0.41s =================================

we see them all pass!

Nice! I love it when a test suite comes together.

Wrapping up

So what did we learn?

First up: string-based fields in Django can accept None values and will save these as the empty string into the database. This is expected and documented behaviour, and something to keep in mind.

Next, we learned that we can override this behaviour if we want to.

Lastly, the Open Source Software model worked very well. Someone spotted the issue, wrote up a workaround, and extended the docs to clarify things so that others aren’t tripped up in the future. Many thanks to Clifford Gama for his contributions!

Addendum: Remember to use `pytest-django`, not plain `pytest`

Note: if you’ve installed pytest, and have set everything up as per normal for a Django project, but get an error when running the tests that apps aren’t loaded yet, i.e.:

E django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet.

Then make sure that you’ve installed pytest-django. Installing pytest alone isn’t enough.

One symptom of this situation is that running the tests with the standard Django test runner works, but using pytest doesn’t. In other words, running:

$ python manage.py test

works as you would expect, but

$ DJANGO_SETTINGS_MODULE=config.settings pytest <path-to>/tests.py

fails with the error noted above.

So, if you see the Django test runner working, but pytest tells you the apps aren’t yet loaded, make sure you’ve installed pytest-django.

Do you need a software developer who is persistent, flexible, and thorough? One who integrates well with existing teams, has broad experience, and thrives on legacy systems? If so, give me a yell! I’m available for freelance Python/Perl backend development and maintenance work. Contact me at paul@peateasea.de and let’s discuss how I can help solve your business’s hairiest problems. ↩
I really don’t know where I got that idea from. I must have been half asleep or something. ↩
You’ll have to imagine the last couple of lines being green in the terminal output. This is the colour that pytest uses for passing tests. ↩
I love details. That’s where you end up learning why something is the way it is. ↩

StreetComplete: Pokémon Go for map geeks

Paul Cochrane 🇪🇺 — Wed, 04 Mar 2026 23:00:00 +0000

A few years ago, while recuperating from our at that time “favourite” dreaded lurgy,¹ I stumbled across StreetComplete, an Android app to update OpenStreetMap data in a fun and easy way. It’s reminiscent of games such as Pokémon Go. But instead of tracking down Pikachu, you update the world’s largest open mapping system, thus contributing to the wider community.

This story is about how I discovered StreetComplete and my impressions of the app and its potential. Give it a go! I’m sure you’ll enjoy it. 🙂

Nudged into active recovery

Most of January 2023 was pretty much screwed for me because of Covid. While recovering, I did a lot of reading and in the process stumbled across a blog post by Terence Eden, in which he became “the #1 mapper in New Zealand”. As a New Zealander myself (and as a geek), this piqued my interest. He achieved this feat by being the most active user in New Zealand within a seven-day period.² To do this, he used StreetComplete, an app which gamifies the process of updating OpenStreetMap metadata.

After having read Terence Eden’s post, I thought that sounded interesting. It also gave me the impetus to get outside and moving again. I was definitely in need of some fresh air! It turned out to be a lot of fun and rather addictive. I highly recommend it!

Like Pokémon Go, but more useful

You use the app like how you play Pokémon Go: by walking around outside in the real world (😱) and solving quests. The StreetComplete website sums this up well:

This app finds missing map data in your vicinity and displays it on a map as quests. Solve each quest by visiting the location on-site and answering a simple question to update the map.

Community contributions

Playing StreetComplete is great because you make a direct contribution to your local community. The quests you solve update OpenStreetMap, which contains a wealth of metadata about our physical environment. And it’s completely open. Sure, Google Maps shows me where the roads are, what the name of a business is and what that business’s opening hours are. But OpenStreetMap is so much more. For instance, OpenStreetMap contains data about pedestrian crossings that use audible tones or have tactile paving, allowing visually impaired people to navigate their surroundings. Apps have been built on this data so that people with visual impairments can navigate their city more safely and easily. How cool is that?

Inclusive applications

What I find most appealing about OpenStreetMap is that it is inclusive. It’s not only for data or geography geeks to have fun, nor is it only for people who want to drive their cars down to the shops. All members of a community can benefit. Importantly, through applications built on OpenStreetMap data, people with physical, visual, or mobility impairments can be more independent.

Think of someone in a wheelchair, an elderly person using a walker to get around, or even a parent pushing a large pram. Each person needs to cross the street easily. And if you know where the street crossings are best, you can save energy and effort. That’s why OpenStreetMap contains detailed data about the properties of street crossings. And with StreetComplete, you help keep this information up to date. Are the crossings on the same level as the street? Or is there a slight bump to get from the street onto the footpath? Such information forms, for instance, the basis for navigation apps for people in wheelchairs. Now you can plan your route to the shops without having to stress about finding a good place to cross the road.

These are the kinds of applications that benefit everyone in a community, not only able-bodied people sitting in cars. That’s brilliant! And OpenStreetMap data is freely available; you’re not being tracked for the “new oil” that is your personal data.

Making map updates fun

To be honest, I can’t rave about StreetComplete enough. The developers have managed to gamify the (potentially very dry) process of updating the world’s largest open mapping system and make it a hell of a lot of fun.

There’s a low barrier to entry to use the app. Simply download from Google Play or F-Droid and off you go. Currently, StreetComplete is only available on Android. However, there is a plan to create an iOS version.

It’s intuitive and easy to use. When you start the app, it’s clear what quests there are to solve, and they’re often rather simple questions. For instance:

What kind of surface does this pathway have?
Does this set of steps have a handrail?
Does this bike stand have a roof (i.e. is it protected from the rain)?
Does this bench have a backrest?
Are the postal collection times still up to date?
Does this bus stop have a seat?

There are almost two hundred such questions in total, including standard questions about business opening hours, road names, and house numbers.

Maybe we do need badges?

StreetComplete can be quite addictive. You get badges for achieving various milestones, which is cool and gives a bit of a dopamine kick. Also, you get the feedback that you’ve made a small, positive contribution to society.

There are many badges one can receive. To give an idea of the kinds of achievements available, I’ve listed below some of the badges I collected back when I first started playing StreetComplete.³

Here’s the badge I received after having solved 60 building-related quests:

This one is after solving 150 quests that help cyclists:

and for solving quests that help people in spaces in nature:

Then there’s the badge for solving 100 quests that help wheelchair users to find their way around:

… and the one I got after solving 60 quests relevant to visually impaired people:

In a city, there are several badges one can get, especially since cities are criss-crossed with streets:

and thus there are some quests relevant to pedestrians:

or to citizens in general:

If you continue long enough, you also get general badges, such as the “surveyor” badge. This achievement also unlocked the OpenStreetMap Haiku app for me, as shown in the image below.

As you can see, there are many ways you can contribute valuable information to OpenStreetMap by playing StreetComplete.

As shown above, some of the badges unlock links to various OpenStreetMap applications. Many are serious. For instance, a map for cyclists, a map to find barrier-free access to buildings and places, or an app which shows maps for the interior of shopping centres and train stations, etc.

Yet, some are also fun, such as the app that uses OpenStreetMap data to generate a haiku. Using this “unlock” mechanism highlighted to me just how many applications have been built around the massive amount of information stored in OpenStreetMap. There seems to be this flourishing community of volunteers imagining and creating clever ways to use map data to make other people’s lives easier. That’s way cool.

Positive benefits of open data

There are many positive side effects of playing StreetComplete beyond simply having fun. It’s a great way to discover a city you are visiting or even the city you’ve lived in for years. When I’m on holiday somewhere, I’ll play a bit of StreetComplete, and before long, I’m more aware of what’s where and hence navigating without an app becomes easier. I’ll know that there’s a bakery down that street, that the supermarket is up that way, and there’s a thousand-year-old tree up on the hill over there. I end up spotting details I’d have likely overlooked otherwise. Things like the funky little model car shop tucked away on a side street, the proliferation of hairdressers in one small area of a city, or water fountains disguised as sculptures. It’s fascinating.

I’ve also started to get an appreciation of the barriers existing in daily life that, at first glance, aren’t obvious. Things like a path separated from a road by a high curb. This means that wheelchair users have to travel an extra distance just to cross the road. Or the lack of acoustic signals or tactile paving at pedestrian crossings that help visually impaired people. You often find tactile paving at train stations and bus stops, but it’s still amazing how little there sometimes is. Even whether a public transport stop has seating is good information to have. This is especially true for people who can’t stand for long when waiting, say, for a bus.

A city or regional council wanting to improve infrastructure and make the physical environment more barrier-free and inclusive, need only look up the information in OpenStreetMap to find where more effort is needed. Local and regional councils are usually cash-strapped, so it’s a boon for them if they can use crowdsourced, open data.

Similarly, having well-updated data about the surface and width of bike paths and footpaths can give local authorities the information they need to improve and interconnect such infrastructure. The potential benefits of well-used open data are enormous.

Tip: avoid automatic uploads

There’s one tip I’ll give for anyone starting out with StreetComplete: it’s a good idea to turn off automatic synchronisation of solved quests. This option is on by default, and there will be times when you want to undo a recent change because it wasn’t correct. If automatic synchronisation is on, then you’ll have to fix the change later within OpenStreetMap itself. Thus, it can be a lot more work to correct a well-intentioned mistake. Since it’s easy to upload completed quests manually, it makes sense to switch off automatic uploads.

Go lose yourself in your surroundings!

So what are you waiting for? Get the app and go and get lost! 😉 It’s heaps of fun!

Yes, I mean Covid. Yes, I’m being ironic about it being “favourite”. ↩
Terence Eden isn’t a Kiwi; he’s from England and achieved his high score while on holiday in NZ. A year later, I was also on holiday there and briefly achieved the number one spot for the seven-day window. It wasn’t that hard; there don’t seem to be that many people in NZ playing StreetComplete. In Germany, however, if you want to get a number one spot, it’s a full-time job! ↩
Note that I use German on my phone, hence the language shown in the badge text. ↩

Forwarding a Vagrant-based Jekyll dev server to its host

Paul Cochrane 🇪🇺 — Wed, 25 Feb 2026 23:00:00 +0000

Forwarding port 80 or 22 from Vagrant virtual machines to their host system is fairly simple. Piping non-privileged ports outside the VM–from, say, a development HTTP server–requires not much extra work. Yet, it’s not always obvious how to do this. In this post, I explain how a Jekyll development HTTP server running within a Vagrant VM can allow connections from its host and why the configuration works.

I was recently testing how to set up and build a Jekyll-based static site by running everything in a Vagrant VM. Since this was a test, I didn’t want to set up nginx, Apache, or reverse proxies; I only needed to connect to the development HTTP server. By default, Jekyll’s built-in HTTP server listens on port 4000. Thus, to connect to that port from a browser running on the VM’s host system, I only needed to forward port 4000 in my Vagrant config, right? Well, that’s part of the story, yes, but it’s not the full story.

Building background knowledge

Let’s build up some knowledge before wiring everything together.

Find the port number

After setting up a Jekyll site, one of the first things you want to do is verify that it works. Thus, you want to start the dev HTTP server and point your browser at http://127.0.0.1:4000/. This is something that running jekyll serve tells you:

$ jekyll serve
Configuration file: /home/cochrane/hello-jekyll/_config.yml
            Source: /home/cochrane/hello-jekyll
       Destination: /home/cochrane/hello-jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 1.392 seconds.
 Auto-regeneration: enabled for '/home/cochrane/hello-jekyll'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

That’s the first bit of knowledge to collect: the server runs on port 4000.

Forward the port to the host

The thing is, this server is running on localhost within the virtual machine. Trying to connect to this address from the VM’s host won’t work. This is because the connection would access localhost on the host, which is different. We solve this problem by forwarding the port from the guest system to the host system.

Forwarding ports in Vagrant is simple enough: add the forwarded_port identifier to the VM’s network settings. The canonical example, e.g. from the Vagrant docs, forwards port 80 from the guest to port 8080 on the host. In other words, you set something like this in the relevant part of your Vagrantfile:

    config.vm.network "forwarded_port", guest: 80, host: 8080

That’s the next bit of knowledge: add the forwarded_port option to the network setting in the Vagrantfile, and point the guest port to an unprivileged port number¹ on the host.

How do we set this up for our Jekyll example? We need to pipe port 4000 to another number. Let’s use 4400 here so that it doesn’t clash with a separate Jekyll service which might be running on port 4000 on the host. Thus, we add this line to our Vagrantfile:

    config.vm.network "forwarded_port", guest: 4000, host: 4400, id: "jekyll"

Note that I’ve added an ID to the configuration so that it’s more obvious to a human what service should run on this port.

Learning to listen

So far, so good. Starting (or restarting) the Vagrant VM and running jekyll serve within it, we should be able to see the site in a browser at http://localhost:4400, i.e. on the port we opened up on the host.

But you’ll find that this won’t work. A browser will tell you that the connection was reset. Using curl from the host system gives similar output:

$ curl -v http://localhost:4400/
* Trying 127.0.0.1:4400...
* Connected to localhost (127.0.0.1) port 4400 (#0)
> GET / HTTP/1.1
> Host: localhost:4400
> User-Agent: curl/7.88.1
> Accept: */*
>
* Recv failure: Connection reset by peer
* Closing connection 0
curl: (56) Recv failure: Connection reset by peer

What’s going wrong?

To work that out, we need to do some debugging. Let’s check that the port is being forwarded correctly. Having a look for it on the host with netstat reveals:

$ netstat -tulpen | grep 4400
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
tcp 0 0 0.0.0.0:4400 0.0.0.0:* LISTEN 1000 7916524 -

Ok, the port’s there, and it looks like we should be able to access it.

Checking the ports inside the guest hints at the problem’s cause:

$ netstat -tulpen
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address Foreign Address State User Inode PID/Program name
tcp 0 0 127.0.0.1:4000 0.0.0.0:* LISTEN 1001 16842 -
tcp 0 0 0.0.0.0:22 0.0.0.0:* LISTEN 0 1985 -
tcp6 0 0 :::22 :::* LISTEN 0 1987 -
<snip>

Note how port 22 has been configured, and that it is different to port 4000’s configuration. Namely, the local address is 0.0.0.0 for port 22, but it’s set to 127.0.0.1 for port 4000. Does that cause the connection reset failure? Put very simply, yes.

The local addresses shown here are the addresses that the operating system will allow connections on. There’s also a subtlety that’s not obvious: 0.0.0.0 is not an IP address. This is a shorthand, telling the operating system to listen for connections on any IPv4 address with the given port number. Thus, while we see the virtual machine listening for connections on port 22 from any address, it’s only listening for connections to port 4000 on 127.0.0.1. This is a specific address, and it’s not the one the host is trying to connect to via the forwarded port.

Furthermore, 127.0.0.1 is a loopback address.² This is completely internal,³ and hence there is no outside network connection. No traffic to this address will leave the computer. So, a service listening on 127.0.0.1 will only answer to connection requests from the computer running the service. No wonder we couldn’t access it from the host! There was never the possibility of being able to connect to it from the outside. That’s why the connection was reset when accessing http://127.0.0.1:4000.

How do we fix this problem? The solution is to bind the HTTP server to 0.0.0.0, thus making it listen for connections from any address.

That’s the last bit of knowledge we need: bind the service to 0.0.0.0.⁴

There are more subtleties to this topic. For a lot more detail and excellent explanations, have a look at the article 127.0.0.1 vs 0.0.0.0: What They Mean, When to Use Each, and How to Debug Binding Bugs.

Host binding

So, how do we get Jekyll to bind to 0.0.0.0? The answer is to pass the bind address to jekyll serve via the --host option:

$ jekyll serve --host 0.0.0.0
Configuration file: /home/cochrane/hello-jekyll/_config.yml
            Source: /home/cochrane/hello-jekyll
       Destination: /home/cochrane/hello-jekyll/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
       Jekyll Feed: Generating feed for posts
                    done in 1.46 seconds.
 Auto-regeneration: enabled for '/home/cochrane/hello-jekyll'
    Server address: http://0.0.0.0:4000/
  Server running... press ctrl-c to stop.

Note that the log message Server address: http://0.0.0.0:4000/ shown above is, technically, incorrect. This is not an address, hence you should not point your browser at it. It might work, but don’t count on it.

With the service bound to 0.0.0.0, you’ll now find that the service is listening on all addresses on port 4000 within the VM:

$ netstat -tulpen
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address Foreign Address State User Inode PID/Program name
tcp 0 0 0.0.0.0:4000 0.0.0.0:* LISTEN 1001 15737 -

<snip>

and that a connection via the forwarded port to this service is now possible:

$ curl -v http://127.0.0.1:4400
* Trying 127.0.0.1:4400...
* Connected to 127.0.0.1 (127.0.0.1) port 4400 (#0)
> GET / HTTP/1.1
> Host: 127.0.0.1:4400
> User-Agent: curl/7.88.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Etag: 4065fa-1295-69849bfa
< Content-Type: text/html; charset=utf-8
< Content-Length: 4757
< Last-Modified: Thu, 05 Feb 2026 13:32:42 GMT
< Cache-Control: private, max-age=0, proxy-revalidate, no-store, no-cache, must-revalidate
< Server: WEBrick/1.9.2 (Ruby/3.4.8/2025-12-17)
< Date: Thu, 05 Feb 2026 13:36:56 GMT
< Connection: Keep-Alive

<snip lots of HTML>

* Connection #0 to host 127.0.0.1 left intact

Thus, pointing a browser on the host at the address http://localhost:4400 will display the development Jekyll site that we wanted to see. Great!

A general situation

Note that this is not specific to Jekyll, nor to Vagrant. Other virtualisation technologies and HTTP servers providing a service on localhost by default behave this way. For instance, it could be that you’re trying to connect to a development Django web server running inside a Docker container. Again, the dev HTTP server must be bound to 0.0.0.0 so that the host system can connect to any forwarded ports.

Another thing learned!

I hope this helps someone confronted with such a situation in the future! For me, it was nice to learn the differences between 127.0.0.1, localhost and 0.0.0.0: my previous conceptual model dumped them all into the same pot, which was incorrect. Now I understand their meaning better, and how and where to use them.

What I mean by an unprivileged port number is one whose use or configuration does not require superuser privileges. These are sometimes also called unrestricted ports or registered ports. ↩
Note that the address 127.0.0.1 is the loopback address on IPv4. On IPv6, the loopback address is ::1. The name localhost could be both. For instance, if you try to connect to http://localhost in a browser, it will likely try ::1 first before possibly falling back to 127.0.0.1. This is not behaviour one can rely on. ↩
In this case, to the VM. ↩
The IPv6 equivalent of this shorthand is ::. ↩

Changing a hostname in Debian seems harder than necessary

Paul Cochrane 🇪🇺 — Wed, 18 Feb 2026 23:00:00 +0000

Changing a host’s name in Debian¹ is a two-step process, and there doesn’t appear to be a more direct method. This seems odd to me, somehow. Because I stumbled upon this issue and a confusing error while relying solely on sudo, I thought I’d write up how I worked around it.

It feels like I missed something obvious here. I mean, changing the hostname should be a one-liner, right? Perhaps someone knows of a better solution.

System setup stumbling-block

Ok, so here’s the situation: I wanted to create a new Vagrant VM and run some basic provisioning steps. Since the use case wasn’t very involved, I didn’t want to use something like Ansible: a simple set of bash commands was sufficient.

One step changes the hostname from the default to something more descriptive. Sounds simple, right? Technically, it is simple. The thing is, two steps are required, which I found strange. And if you’re using sudo, you’ll likely be surprised by a name resolution error:

sudo: unable to resolve host <new-hostname>: Temporary failure in name resolution

What gives?

The name resolution failure appears because the new hostname doesn’t match the entry in /etc/hosts. Thus, any sudo call thereafter is unable to find the host it’s running on. The hostname lookup within sudo times out, and we get the name resolution failure message I mentioned above.

I must admit, this tripped me up. I don’t remember having had this stumbling block previously. I ended up wondering how I’d done this before. Wasn’t this a single command in the past? And what’s with name resolution being needed as part of sudo?² Once upon a time, I’d have opened a root session and hence wouldn’t have run into this problem, but those days are long over. I now almost exclusively use sudo for admin tasks.

More recently, I use Ansible when provisioning new hosts, and hence haven’t spotted this issue.³ At least, not for a while. Maybe I’ve just forgotten? Dunno.

Anyhow, back to the story. The problem manifests itself if you run these commands:

# either use the "old" way to set a hostname
$ sudo hostname <new-hostname>
# ... or use the new-fangled, strangely repetitive way to set a hostname
$ sudo hostnamectl set-hostname <new-hostname>
# now open /etc/hosts to fix hostname entry in there
$ sudo vim /etc/hosts
# ... wait until the name resolution times out ...
# get the name resolution error message
sudo: unable to resolve host <new-hostname>: Temporary failure in name resolution
# now vim will open /etc/hosts

All online resources I looked at–such as nixCraft, which is usually a good source of info–recommend this two-step process. And to do it within a root session.

But what if you don’t want to do that as root directly? What if you want to script this and are restricted to using sudo? That’s the issue I was trying to solve, and here’s my solution.

Wonky workflow workaround

The approach first adds the new hostname to /etc/hosts. That way, the name is able to be resolved after changing the hostname. Then I change the hostname in the usual way. Afterwards, I delete the old /etc/hosts entry to remove unnecessary cruft.

Putting this all together as a shell script in a Vagrantfile provisioning step, we get (by way of example):⁴

    bookworm_new.vm.provision "shell", privileged: false, inline: <<-SHELL
      sudo DEBIAN_FRONTEND=noninteractive apt update
      sudo DEBIAN_FRONTEND=noninteractive apt -y upgrade
      sudo DEBIAN_FRONTEND=noninteractive apt install -y vim
      # add new hostname to /etc/hosts; keep old one for now
      # avoids `sudo: unable to resolve host <hostname>: Temporary failure in name resolution`
      # errors when running `sudo` after changing the hostname
      sudo sed -i 's/bookworm/bookworm bookworm-new/g' /etc/hosts
      sudo hostnamectl set-hostname bookworm-new
      # remove the old hostname
      sudo sed -i 's/bookworm //g' /etc/hosts
    SHELL

The provisioning commands appear in a here doc called SHELL.⁵ The first few lines are standard update commands I use when setting up a new VM. I find it’s a good idea to ensure everything’s up to date before proceeding, even if the base image is recent. You’ll note that I install vim as well. Basically, my muscle memory won’t think of another editor, and this saves friction for me when modifying config files or viewing logs.

The lines after that are the important ones for the hostname updating process:

# add new hostname; keep old one temporarily
# avoids `sudo: unable to resolve host <hostname>: Temporary failure in name resolution`
# errors when running `sudo` after changing the hostname
sudo sed -i 's/bookworm/bookworm bookworm-new/g' /etc/hosts
sudo hostnamectl set-hostname bookworm-new
# remove the old hostname
sudo sed -i 's/bookworm //g' /etc/hosts

The first non-comment line uses sed to edit /etc/hosts in-place (hence the -i option). The example system used here is Debian bookworm, hence the default hostname is set to bookworm. I want to set the new hostname to be (unimaginatively) bookworm-new, so the sed command replaces bookworm with the text bookworm bookworm-new. Now the new hostname is available, and the old hostname is still there, but with a space after it, which will come in handy when removing that entry later.

Next, I use hostnamectl to set the hostname. The old-fashioned hostname command still works, but hostnamectl seems to be what all the cool kids use.

Now it’s just a matter of removing the old hostname from /etc/hosts. Here I use sed with the -i option again, and replace the string 'bookworm ' (note the space after the name)⁶ with the empty string, thus removing the old hostname from /etc/hosts.

Now the change is complete, and there aren’t any “Temporary failure in name resolution” errors. Yay! 🎉

Wrapping up

For some reason, I still expect the hostname and /etc/hosts changes to be coupled so that they occur as part of a single command. Oh well. Ya get that, I guess.

Anyway, if you run across the Temporary failure in name resolution error when running sudo in the future, now you know why and can work around it. Enjoy!

… and probably Linux in general, but I didn’t check. ↩
The reason sudo looks up the host’s name is that /etc/sudoers is designed to be distributed across multiple servers. Hence, sudo needs to know which host it’s on to apply any host-specific rules. ↩
Although, to be honest, the ansible.builtin.hostname module docs do mention that the module doesn’t update /etc/hosts and that one has to do this it oneself. Perhaps I haven’t done this in a while and have forgotten the full story. ↩
I have a suspicion that my woes could be solved by using privileged: true and removing sudo from the script. However, I realised this after having written everything up, and yet still found my explanation useful. ↩
Of course, one could extract the script code into a file and run that via sudo. But where’s the fun in that? ↩
Yes, I could have used a better regex here, e.g. something like bookworm\s\+, but then I’d need to use extended regular expressions and, well, this did the job. ↩

It’s not DNS; it was DNS

Paul Cochrane 🇪🇺 — Wed, 11 Feb 2026 23:00:00 +0000

Logging in to a VPN shouldn’t cause DNS to stop working, right? Well, you’d like to think that, wouldn’t ya? And the problem wasn’t PEBKAC this time, either. Finding the right setting to fix the problem did take some time, but I got there in the end.

A computer by any other name

While doing some work for a customer¹ recently, I needed to log in to their VPN to check on some stuff. I’d not used their VPN for about a year, so I expected some hiccups along the way. I mean, there’s always something, right? Network settings are changed, systems get updated, and the slow plod of time always causes some problem or other. But I wasn’t expecting DNS not to work when connected to their VPN.

Here was the situation. I was happily using the internet (as you do) and needed to access one of the customer’s services that is only available within their network. Thus, I needed to log in to their VPN. I entered my login details into their VPN client and voila! I was in their network. All as expected, right? Wrong. Any address I entered into my web browser gave me the same error: server not found. And yes, I was using the correct address. This situation made it rather difficult to access the services I needed to use.

Bring out the machine that goes ping

One of my first instincts when confronted with such a situation is to try to ping something. A habit (and probably a bad one at that) is to ping www.heise.de because, well, it’s always up. That resulted in this error:

$ ping -4 www.heise.de
ping: www.heise.de: Name or service not known

Ok, not good. How about an address closer to home? For instance, the customer’s main website? It turned out that pinging that address also wouldn’t resolve a name. Crikey! What to do now?

The hard part here was debugging the problem as an outside user. What else could I check? The IP address that the VPN client software had given me looked ok:

$ ip addr
<snip>
10: cscotun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1390 qdisc
pfifo_fast state UNKNOWN group default qlen 500
    link/none
    inet x.x.x.x/22 brd x.x.x.255 scope global cscotun0
       valid_lft forever preferred_lft forever
    inet6 fe80:<la-la-la>/126 scope link noprefixroute
       valid_lft forever preferred_lft forever

The list of routes also looked good:

$ ip route list
default via 192.168.2.1 dev wlp2s0 proto dhcp metric 600
x.x.x.x dev cscotun0 proto unspec scope link
<snip>

Logging out of the VPN, I contacted the IT staff at the customer’s site and told them of my sorrows. Unfortunately, as far as the network engineers on the other side could tell, everything looked good. Nothing in their DNS had changed. After all, the DNS servers were still the same as they’d always been. These servers also appeared in my route list. Hrm.

Persistence pays off

Some time passed, and after some more discussion, we (the IT staff and I) still weren’t any closer to resolving the issue. Thus, I decided to dig a bit further on my side to see if there was anything I could do to fix things. After all, it wouldn’t be the first time that I’d set some configuration value on my laptop and then forgotten that I’d set it, and it ended up provoking some weird problem a long time later. Lots of digging ensued, but there wasn’t anything obvious that seemed to be causing the issue. Through stubborn perseverance, I eventually honed in on the NetworkManager service’s configuration as a possible origin of my woes.

One thing with DNS on a Linux box is that (historically) this is configured in /etc/resolv.conf. Having a look at this file with the VPN off showed something like this:

$ cat /etc/resolv.conf
# Generated by NetworkManager
search internet-provider.com
nameserver 192.168.2.1
nameserver fe80::1%wlp2s0

Then, when logged in to the VPN, NetworkManager changed this file’s contents to:

$ cat /etc/resolv.conf
# Generated by NetworkManager
search internet-provider.com customer.com
nameserver 192.168.2.1
nameserver fe80::1%wlp2s0

Ok, so the only change is to add the customer’s domain to the resolver’s search settings. This shouldn’t affect name resolution. In fact, I would expect it to help with name resolution.

Using a bit of old-fashioned prompt-engineering (i.e. googling), I stumbled upon NetworkManager’s dns configuration parameter. It controls the DNS processing mode and is set in the [main] configuration section of the /etc/NetworkManager/NetworkManager.conf file.

The comment in /etc/resolv.conf:

# Generated by NetworkManager

somehow gave me the idea that maybe NetworkManager didn’t need to update this file after all. And that maybe some other software component, which was also trying to update /etc/resolv.conf, would get the chance to set things properly. Thus, I tried setting dns=none to stop NetworkManager modifying resolv.conf.

I.e., I changed /etc/NetworkManager/NetworkManager.conf to look like this in the [main] section:

[main]
... other settings
dns=none

Restarting the service to re-read the config,

$ sudo service NetworkManager restart

and sure enough, something was changing /etc/resolv.conf when in the VPN and was changing it back after leaving the VPN. My guess, retrospectively, is that this was the VPN client software. Since, in the default configuration, NetworkManager thinks that it should have full control over this file, it kept changing /etc/resolv.conf back to what it thought was the right config, which then screwed up DNS for me.

Here’s what /etc/resolv.conf looked like for me now after connecting to the VPN:

$ cat /etc/resolv.conf
domain customer.com
nameserver <dns-ip-1>
nameserver <dns-ip-2>
search customer.com internet-provider.com

Something about this change told me I was onto something. Especially the new nameserver values signalled an improvement.

Importantly, I could now ping www.heise.de while in the VPN:

$ ping -4 www.heise.de
PING (193.99.144.85) 56(84) bytes of data.
64 bytes from www.heise.de (193.99.144.85): icmp_seq=1 ttl=249 time=9.13 ms
64 bytes from www.heise.de (193.99.144.85): icmp_seq=2 ttl=249 time=10.1 ms
^C
--- ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1002ms
rtt min/avg/max/mdev = 9.134/9.607/10.080/0.473 ms

Brilliant!

Now I could access the services I needed to use and continued merrily on my way.

Everything works until it doesn’t

… until …

Time did that thing again that it always does: change stuff. sigh

For other network-related reasons, I needed to update some packages on my (admittedly very outdated) dev system. While watching the progress of an apt upgrade command whiz past, a package name caught my attention: resolvconf. Oh dear.

Guess what? DNS no longer worked. It even turned out that when I wasn’t connected to the VPN that dns=none needed to be removed for name resolution to work. But dns=none needed to be set (and NetworkManager restarted) for DNS to work inside the VPN. Bugger.

Man, this was so not a solution. I can’t be changing the NetworkManager config and restarting it each time I change a network connection!

Read the fine manual

Thus, lots more reading ensued, including more of the NetworkManager.conf man page. One of the big hints in the section about the dns option is the comment that:

If the key is unspecified, default is used, unless /etc/resolv.conf is a symlink to /run/systemd/resolve/stub-resolv.conf, /run/systemd/resolve/resolv.conf, /lib/systemd/resolv.conf or /usr/lib/systemd/resolv.conf. In that case, systemd-resolved is chosen automatically.

An idea formed in my mind. What if I used systemd-resolved? Let’s give it a go! YOLO and all that jazz.

It turned out that the systemd-resolved package wasn’t installed on my laptop. No worries, that’s easily fixed:

$ sudo apt install systemd-resolved

Next, I changed the dns setting in NetworkManager.conf to use systemd-resolved:

[main]
... other settings ...
dns=systemd-resolved

After restarting NetworkManager:

$ sudo service NetworkManager restart

… everything worked! By that I mean I could change the network I was using (i.e. to the VPN and back again) and still have name resolution. Phew!

So, it turned out that it was a local setting causing problems. It wasn’t, however, a setting that I’d mucked about with before all these problems appeared, so I couldn’t blame myself (at least, not completely), as is often the case.

The solution turned out not to be to set dns=none and let the VPN software (or whatever) work out what to do with DNS resolution and whatnot in /etc/resolv.conf. The better, more sustainable solution turned out to be to use systemd-resolved to handle things for me. Great! Now I can get back to work!

It’s not DNS

As it turns out, “it’s not DNS” is a meme, at least among sysadmins. There are even t-shirts and haikus and stuff!

It’s not DNS

There’s no way it’s DNS

It was DNS

Things ya learn!

Persistence still pays off

So what did we learn? Computers are hard. Networks are also hard. The fact that the internet, with so many computers connected to it, functions at all is something short of a miracle. It’s also a PITA when things that usually “just work”–like DNS–don’t. But, stubbornness, persistence, and liberal use of RTFM saved the day in the end.

If you need a software developer who is stubborn, persistent, and thorough, give me a yell! I’m available for freelance Python/Perl backend development and maintenance work. Contact me at paul@peateasea.de and let’s discuss how I can help solve your business’s hairiest problems. ↩

My (current) blog article writing process

Paul Cochrane 🇪🇺 — Wed, 04 Feb 2026 23:00:00 +0000

As with my work, when I write articles on my blog, I have a focus on quality. Here I describe my current writing process, primarily to document things for my future self.

I have ideas. Lots of ideas. Unfortunately, too many to chase all at once. When I follow the thread of a particular idea, I stumble across many interesting problems to solve. This can be as part of my work or simply when I’m trying to get stuff done.

These ideas and and their solutions provide the inspiration to tell a story about what happened, why, and how to resolve the situation. Often, the impetus to write this stuff up comes from a compulsion to help others: someone else might have had the same problem and is searching for a solution. It’s cool to have a worked solution already written up that can be used directly. Sometimes this “other person” is myself. More than once, I’ve googled for a solution to a problem only to find said solution written up on my blog. After all, as Damian Conway once said: documentation is a love letter that you write to your future self.

This article describes my current writing process, how I find things to write about, how they turn into articles, and how I polish the text to focus on quality. The process is very much in flux, and I’m still on a learning curve, so I expect things will change in time.

To be honest, I never liked writing stories at school. This is one reason why I became a scientist, so I didn’t have to keep writing silly stories.¹ It turns out that that’s part and parcel of being a scientist. Bummer!

It also turns out that a well-written explanation can be very helpful. And–after many years of trying to avoid such tasks–I finally realised that writing isn’t so bad after all. It’s a hell of a lot of work, but then that’s the case with many worthwhile things.

Obstacles are story germination sites

A lot of what I write about stems from some task I was trying to solve or some kind of (usually technical) obstacle I was trying to overcome. Once at the end, I sometimes think “Hrm, this might be useful to someone else”. Thus, a story forms, explaining how the problem arose and how I managed to solve it.

Solving a technical problem is a lot like puzzle solving. When I solve such puzzles, I make copious notes so that I can explain what happened and why. The reason for my note-taking stems from a desire to write good commit messages and have thorough documentation of the problem. Since this is usually some kind of software-related issue, I dump all that I’ve learned into the project’s issue tracker. This way, others can see what did and didn’t work, transferring knowledge and ensuring anyone following in my footsteps has an easier time in the future.

My commit messages have come back to haunt me in both positive and negative ways. The negative ones are usually a message like “Fix obkus leak in frobniator”. Gah! Tell me how you fixed it and why! The positive ones, on the other hand, contain enough detail and explanation for my future self to work out what was going on and how to fix things again, should this be necessary. When I stumble across a good explanation from my past self, I’m frequently stunned at how useful the text is and how much pain and stress it relieves. Damian’s quote rings very true: these really are love letters to your future self.

Reworking a solution

The notes themselves, either in commit messages or in issue trackers, aren’t always useful in the form that I initially wrote them. They contain lots of dead ends, extraneous details, failed experiments, and wild goose chases. They lack a “red thread” from problem to solution. This is why I write up an article about some problem and its solution; I work through the puzzle again (sometimes a couple of times) so that the path is clearer and more direct. My thinking here is that someone reading such an article doesn’t want to go down the same dead ends as I did. Dead ends can be useful, but only if someone puts a signpost in front of them to say, “I tried this out. It didn’t work. Don’t try this at home.” Re-working a solution also helps me shed unnecessary detail and sometimes shows me an even better way to solve the problem. My hope is also that the article’s text flows more logically and that the steps from beginning to end make more sense. Either way, it’s a necessary step to redo things and see that, yes, this was a good way to solve a particular issue.

In working through the problem again, I start writing the first draft. Often, each step only requires a few words to tie things together. Install that, edit this file, use that setting, restart that service, and Bob’s your aunty’s live-in lover. In such cases, the article “writes itself” from the initial notes and the example run-through. However, I find that only the basic structure takes shape at this stage. The real hard work starts later, in the editing process.

A draft article also needs a bit of explanation up front about what the issue is and why it was so important to solve. It also needs most of the details in the examples to be in place, along with any links to relevant documentation or online resources.

Furthermore, there needs to be some kind of conclusion. I like to round things off by recapping what happened and mentioning any outlook for the future, as necessary. I’ve noticed that some technical book writers tend to avoid a concluding chapter altogether, and the book ends abruptly. This always felt like driving off a cliff to me. As a reader, one has momentum and thinks, “Ok, let’s see what the next thing is the writer wants to tell me”, only to have the book suddenly stop. It’s like Wile E. Coyote standing in mid-air, looking confused and wondering how he got there. Since I don’t like that, I try to round things off, even if the text does seem a bit redundant. It’s like saying “Goodbye” at the end of a phone call. Maybe it’s not technically necessary, but it’d be weird just to hang up.

Let it simmer for a while

After I’ve written the first draft, it needs to sit for a while so that my subconscious can do its thing. I can’t start editing straight away, because I find that I get sort of “blind” to what I’m saying. If I’ve left a text on its own for a few days and read it again, I see all the holes that I need to plug and much of the fluff I need to remove. This isn’t the first time an article needs to sit and “simmer” for a while. Often, after a manual edit cycle, I leave a text alone once more before returning to it with fresh eyes.

Leaning on tools

Editing is hard. Add to that a lack of writing experience, and it gets even harder. That’s why I lean on a couple of tools to support me in this process.

Hemingway

After the first edit,² I use the Hemingway program to check for certain kinds of style issues and for complex sentences. As my school teachers told me back in the day, I waffle a lot. Waffling makes for complex sentence structures, and Hemingway helpfully flags such things. Using a tool like this allows me to reflect and ask myself, “What is it that I’m trying to say here?” Simply having that extra resistance triggers a rethink. Most of the time, I can see a better formulation, which is shorter and clearer.

Sometimes I have to ignore some of the suggestions that Hemingway provides. I found that adhering too much to the tool makes the text stilted and wooden. Somehow, my style of explaining things disappears under a layer of bland standardness. It’s been a learning experience working out where Hemingway can help me and where it can’t. And I’m still learning!

Using Hemingway has helped me to more regularly identify long sentences that need splitting up. I couldn’t see such issues before. Now I spot more of them in the initial edit phase, which is a good thing. It definitely helped me spot when I overuse words like “just”. I’ve found that this can be frequently rewritten as “only”, showing me that I really meant to say something else. Also, it spots things like passive voice, which I try to avoid.

Importantly, the tool notices words that I can omit, reducing the waffle. Mr Rorholt, my economics teacher at high school, would often write the word “waffle!” in red in the margin of my essays, highlighting my poor, problematic–and probably purple–prose. That experience certainly left its mark, reducing, but not eliminating, my waffliness.

Hemingway (the program) does seem to harp on about “simpler phrases” and “unnecessary” adjectives. Sometimes these suggestions have to be ignored. A text without variety and different complexity in phrasing ends up plain boring. Also, it’s not like one can avoid adjectives completely. One needs to get a feeling for when it’s a good idea to follow the advice and when it’s a good idea to ignore it.

A good side-effect of Hemingway highlighting which sentences are complex is that I get an opportunity to cogitate on what it was I was trying to say. The tool isn’t arbitrarily trying to hold me back: it’s providing me with advice. It’s an opportunity to slow down and rethink. Rewriting a sentence or paragraph two or three times can undo any knotted sentence structure that Hemingway spotted. Sometimes, I can remove a sentence completely! After all, deleted code is the easiest to maintain. 😉

Grammarly

While I find Hemingway to be useful as an initial automated check, I find Grammarly gives a text much more polish. The tool has four areas of focus: Correctness, Clarity, Engagement, and Delivery. For me, the biggest help is the Correctness area. It spots typos and spelling errors. It sees forgotten articles before nouns. It detects where I’ve placed commas incorrectly or have missed them completely. It also highlights redundancy, tenses, prepositions, and hyphenation issues. The best help, I find, is the comma fixes. Usually, I re-read the text and realise that, yes, I did intend the pacing to be different and that a comma was necessary to make a pause that I’d not included.

The Clarity suggestions are also great. Often, the simple fact that the text his highlighted makes me look at it in a different light, and I can see an improvement directly. I don’t always need to use Grammarly’s suggestion; the fix is obvious. That’s one great thing about using such tools: they help relieve the blindness one gets by reading a text several times. That’s why putting a text aside for a day or two can be so useful. One sees it with fresh eyes, and a tool can help in achieving that “fresh eye” state.

The suggestions from Grammarly Clarity show how something can be rephrased. This is a great learning opportunity for me. I regularly look at the results and think “Oh wow, yeah, that’s a nice way to say that”. If I see a certain style of suggestion frequently enough, then something eventually gets through my thick skull, and I stop making such convoluted constructions in the first place.

Getting by without a little help from my friends

Support from tools allows me to grow and improve on my own without needing to annoy friends or family by asking for feedback on a text. My two theses relied a lot on help from others. Such tools simply didn’t exist back in the day. Thus, my Master’s and PhD theses were not the work of a single person; they were very much a team effort. I can’t imagine the burden I’d put on everyone if I had them review all my blog posts now as well!

Let it be

Once I’ve completed the initial human and tool-supported edits, I let the text sit again for a day or two so that I can come back to it with fresh eyes. I then go over the text once more and try to spot any issues that might be left over. Sometimes I spot logical problems, sentences that aren’t clear, and phrases that can be deleted. Occasionally, I discover new ways in which something could be better structured.

This is also the time for me to pull out Inkscape and make a cover image. I try to make something relevant to the post’s topic, and I use Creative Commons images and/or the appropriate attribution where possible.

Generally speaking, once a text has gotten to this stage, I’m pretty sick of looking at it, so this is the final edit. I’m rather pleased to move it into my _posts folder and consider it completed. There will probably still be leftover issues or vagueness in the text, but I’ll have to live with that!

Push to publish

And that’s the last step: moving a post from the _drafts folder into the _posts folder. Pushing to my upstream Git repository is then the publishing process. There’s a CI job that runs on GitLab, which handles all the hard work, so I don’t have to do that on my local machine. It’s nice to go git push and think “Ah, that’s finished!”. 🙂

All done

And that’s it. That’s my blog post creation process. Mainly, this was for my future self to look back on my previous self and maybe realise how far I’ve developed. Or perhaps he just wants to remember part of the process. Either way: gudday future me!

Like those fun school trips out to Lake Rerewhakaaitu only to have them ruined by having to write a story about it once we got back to school. Urgh. ↩
… or edits. I usually make multiple passes. ↩

An unhinged carriage problem

Paul Cochrane 🇪🇺 — Thu, 08 Jan 2026 23:00:00 +0000

As part of tutoring high school students in maths and physics, I sometimes run across problems that I find interesting. Here’s a deep dive into one involving an unhinged railway carriage which, at first glance, seems to lack sufficient information.

I find it interesting that some solutions become almost embarrassingly obvious given the right perspective. I also like that there’s usually more than one way to solve a problem. This is one of those situations. Here’s the problem:

A train is moving straight and horizontally at a constant speed. The last carriage is uncoupled from the train and slows with a constant deceleration. The train continues to move at its previous speed. The carriage moves straight and horizontally, eventually coming to a stop after 200 m. Determine the distance the train travelled from the time the carriage was uncoupled to the moment the carriage stopped.

Write the answer in metres (m)

When I first saw this, my instinct was that there wasn’t enough information. The solution requires a very specific answer in metres, yet we’ve not been told the carriage’s deceleration, nor the train’s speed. That struck me as odd.

It turns out that it is possible to calculate a definite value for how far the train travelled before the carriage stopped; it just wasn’t obvious to me from the get-go. This leads to one piece of advice:

Have a go at solving the problem, even if you’re unsure.

There’s another piece of advice that I usually dish out to my students:

Try solving the problem in more than one way. If you get the same answer by a different path, then the answer is more likely to be correct. You might also learn something along the way.

But I’m getting ahead of myself.

Let’s have a go at solving the problem. We’ll first use a geometric argument by drawing the speed versus time graphs for the train and the unhinged carriage. Later, we’ll look at other paths to a solution.

Visualising speed versus time

I’m a big fan of drawing pictures and diagrams to get a feel for a given situation. Interestingly enough, my gut feeling this time wasn’t to draw a train moving along a track (which would have been my usual approach) but to draw graphs of speed versus time.

The question mentions constant speed a couple of times, as well as the uncoupled carriage’s constant deceleration. Thus, my physics-addled mind’s eye straight away saw lines on a speed versus time graph, and I started doodling these on a piece of paper. What follows is a more neatly-drawn¹ version interspersed with explanations.

First, we need some axes and to label them:

The carriage’s initial speed is the same as the train’s speed when it is uncoupled. Let’s call this $v_t$ and mention it on the graph, so that we can refer to it again later.

Since we’re only interested in elapsed time, the time that the carriage is uncoupled from the train happens at zero seconds. The time that the carriage stops, we’ll call $t_1$ . We now label the graph with this information:

We know that the carriage slows with constant deceleration and that deceleration is simply negative acceleration, hence we’ll denote it by $- a$ . Deceleration is a line of negative slope $(- a)$ in the speed versus time graph and connects the time-speed coordinate $0, v_t)$ with $t_1, 0)$ . Adding this to the graph, we have:

We also know that the area under a speed versus time graph is the distance travelled. Therefore, we shade this area to highlight it and make a note on the graph that this is equal to $m200\ \mathrm{m}$ .

That’s cool. We’ve described, in a graphical form, the uncoupled carriage’s behaviour from when it separated from the train up until it stopped moving.

So what happened to the train over this time? Well, we know that it kept going at the same speed. And we know that constant speed on a speed versus time graph is also a straight line, but with zero slope. In other words, it’s a horizontal line from the time-speed coordinate $0, v_t)$ to $t_1, v_t)$ . Let’s add that to our graph:

As with the carriage, the area under its curve is how far the train travelled in this time. We can shade in this area as well:

It’s clear from the graph that the area under the line representing the train’s speed versus time behaviour is enclosed by a rectangle. It’s also clear that the area under the carriage’s curve is enclosed by a triangle, and that the triangle’s hypotenuse bisects the rectangle. In such a case, the triangle’s area is half the rectangle’s area. Since we know that the triangle’s area is equal to $m200\ \mathrm{m}$ , we can say that the rectangle’s area must be equal to double that, i.e. $m400\ \mathrm{m}$ . Thus, the train travelled $m400\ \mathrm{m}$ in the time it took the uncoupled carriage to come to a halt.

There we have it! That’s the answer!

Now we can see that it wasn’t important how fast the carriage decelerated, nor was it important how fast the train was travelling. Thus, my initial feeling about missing information was unfounded. Hence, we see why it was a good idea to attempt to solve the problem to see if we could get anywhere. Also, the answer sort of “pops out” at us as soon as we draw the speed versus time graphs: we only needed a bit of geometry and to know the physical meaning of the area under the curve to find the answer. It’s almost blindingly obvious in the end.

We now put our fingers in our ears and go “la! la! la!” loudly, to try and ignore the fact that we know the answer. Then, we’ll solve the problem algebraically without using any pictures or graphs.

Why do this “the hard way”? Why not? Come on, let’s dig in and see what happens!

An algebraic approach

As with the graphical approach above, we collect what we know from the problem description and see if we can make some headway by combining things logically.

We know that the train travels at a constant speed the entire time, so let’s call that $v_t$ . We’re told that the last carriage is unhinged (i.e. uncoupled) from the train at some time; thereafter, it decelerates at a constant rate. Since deceleration is negative acceleration, let’s call this quantity $- a$ . The carriage starts with the same speed as the train, finally coming to a stop at some later time. Let’s set the initial time to zero and call the time the carriage stops $t_1$ . With this information, we can write an equation to describe the carriage’s speed between these two times. Let’s call the carriage’s speed $v_c$ , which we can write as:

\begin{equation} v_c = v_t - a t, \end{equation}

where $t$ is the elapsed time.

Note that this equation has the same form as the equation for a straight line in the plane:

y = m x + c,

where $y = v_c$ , $m = - a$ , $x = t$ and $c = v_t$ .

We can see that (1) behaves the way we want by considering the start and end points.

At the uncoupling event, $t = 0$ , hence when we substitute this into (1), we find that the speed of the carriage when it gets unhinged is:

v_c(0) = v_t - a \cdot 0 = v_t,

which is the $y$ intercept. That makes sense, because we know that the carriage’s initial speed is the same as the train’s speed. Cool, that means we’re probably on the right track.

The $- a t$ term in (1) linearly decreases the value of $v_c$ , tracing out a line which then intersects the $x$ -axis at $t_1$ . In other words, the speed is equal to zero at $t_1$ . This is the behaviour we want at the other end of the time interval. Good, we’re still on the right track.

We know that the carriage stops at $t_1$ , thus we have the relationship:

v_c(t_1) = v_t - a t_1 = 0.

That might not look that useful, but we can rearrange it to give an expression for the time when the carriage stops, and that could come in handy later:

\begin{equation} v_t - a t_1 = 0, \end{equation}

\begin{equation} \Rightarrow a t_1 = v_t, \end{equation}

\begin{equation} \Rightarrow t_1 = \frac{v_t}{a}. \end{equation}

What else do we know? Well, we know that the train travels at constant speed between $t = 0$ and $t = t_1$ . That means we know how far the train went in that time: this is its speed multiplied by the elapsed time. In other words, the distance the train travelled (which we’ll call $d_t$ ) is:

d_t = v_t t_1.

Since we have an expression for $t_1$ (Equation (4)), we can rewrite the expression for $d_t$ to see if it might be useful:

\begin{equation} d_t = v_t t_1, \end{equation}

\begin{equation} = v_t \frac{v_t}{a}, \end{equation}

\begin{equation} \Rightarrow d_t = \frac{v_t^2}{a}. \end{equation}

Hrm, that doesn’t look like it’s going to be of much help. Oh well. Let’s add it to the growing pile of things that we know anyway and see what else we know and/or can deduce.

What about the distance the last carriage travels? We know that its value is $m200\ \mathrm{m}$ . Can we write an expression for it in terms of the other things we know? Yes, we can! We know that the carriage’s speed is described by:

v_c = v_t - a t.

We also know that distance is the integral of the speed between two points in time.² Thus, to find the distance travelled by the carriage, we integrate Equation (1) with respect to time between the start and end points, $t = 0$ and $t = t_1$ . To be consistent with our other notation, let’s call the distance travelled by the carriage $d_c$ . Putting this all together, we have:

d_c = \int_{0}^{t_1} v_t - a t\ dt,

\left[v_t t - \frac{1}{2} a t^2 \right]_{0}^{t_1},

\Rightarrow d_c = v_t t_1 - \frac{1}{2} a t_1^2.

Squinting at this result, one gets the feeling that it’d be nice to remove at least one of the variables. Since we already have an expression for $t_1$ (Equation (4)), we can try substituting that into the equation for $d_c$ to see what happens:

d_c = v_t \frac{v_t}{a} - \frac{1}{2} a \left( \frac{v_t}{a} \right)^2,

\frac{v_t^2}{a} - \frac{1}{2} a \frac{v_t^2}{a^2},

\frac{v_t^2}{a} - \frac{1}{2} \frac{v_t^2}{a},

\frac{1}{2} \frac{v_t^2}{a}.

Hrm, that $vt2a\frac{v_t^2}{a}$ bit looks familiar. Hang on! That’s the same as the expression for the distance the train travelled from earlier (Equation (7)). In other words,

d_c = \frac{1}{2} d_t,

\Rightarrow d_t = 2 d_c.

This means that the carriage travelled half the distance that the train travelled. Which is the same as saying that the train travelled twice the distance that the carriage travelled. Wow, that turned out to be a very simple relationship in the end!

Now, we know that $md_c = 200\ \mathrm{m}$ , as that was given to us in the question. Thus, the distance the train travelled in the time it took for the carriage to come to a stop is $md_t = 400\ \mathrm{m}$ .

And that’s it! We solved the problem. Yay! And we got the same result as the graphical approach outlined earlier. Cool! 🎉 I love it when a calculation comes together. 😉

There’s something else one can learn here:

What looks like a dead end in a calculation might come in useful anyway.

After all, calculating the distance travelled by the train in terms of its velocity and the carriage’s deceleration looked like it wasn’t very helpful. But in the end, it gave us a useful, simplifying hint which led to the answer.

An average solution

There’s another way of looking at this problem. We can consider average speeds.

The fundamental insight with this approach is that, for a situation involving constant acceleration, the distance travelled is proportional to the average speed.

Let’s first consider the case for the train. Its speed at both the beginning ( $t = 0$ ) and at the end ( $t = t_1$ ) is equal to $v_t$ . We know that the distance it travels is its speed multiplied by the elapsed time:

d_t = v_t (t_1 - 0) = v_t t_1.

Because the train doesn’t change speed, that means the train’s average speed, $vˉt\bar{v}_t$ , is the same as the train’s speed. I.e.

\bar{v}_t = \frac{v_{ t,0} + v_{t,1}}{2} = \frac{v_t + v_t}{2} = \frac{2 v_t}{2} = v_t,

where $v_{t,0}$ and $v_{t,1}$ are the speeds of the train at the beginning and end of the time interval, respectively.

We can now write the distance the train travelled in terms of its average speed:

d_t = v_t t_1 = \bar{v}_t t_1.

This can be formulated more loosely as:

d_t \sim \bar{v}_t.

Because we’re considering the same time interval for both the distance travelled by the train and by the unhinged carriage, the elapsed time (which is equal to $t_1$ ) ends up being just a scaling constant. Hence, the distance travelled is proportional to the average speed.

Of course, the carriage does change speed, and over the same time interval. We also have a constant acceleration³ for the unhinged carriage, so we have the same kind of proportionality relationship between the distance and average speed, i.e.:

d_c \sim \bar{v}_c.

The average speed for the carriage is:

\bar{v}_c = \frac{v_{c,0} + v_{c,1}}{2},

where $v_{c,0}$ and $v_{c,1}$ are the speeds of the carriage at the beginning and end of the time interval, respectively.

Because the carriage’s speed at the beginning is equal to the train’s speed, and the carriage’s speed at the end is equal to zero, we have $v_{c,0} = v_t$ and $v_{c,1} = 0$ . Thus, the carriage’s average speed ends up being:

\bar{v}_c = \frac{v_t + 0}{2} = \frac{v_t}{2}.

I’m sure you can see where this is going. But let’s continue anyway to nail everything down more firmly.

Since the distances are proportional to the average speeds, the ratios of the distances will be equal to the ratios of the respective average speeds. In other words, we can write:

\frac{d_t}{d_c} = \frac{\bar{v}_t}{\bar{v}_c}.

Since we know what $d_c$ , $vˉt\bar{v}_t$ and $vˉc\bar{v}_c$ are, we can rearrange this to give us our only unknown, $d_t$ :

d_t = d_c \frac{\bar{v}_t}{\bar{v}_c},

d_c \frac{v_t}{\frac{v_t}{2}},

d_c v_t \frac{2}{v_t},

2 d_c.

And since we know that $md_c = 200\ \mathrm{m}$ , we have the distance the train travels to be

d_t = 2 d_c = 2 \cdot 200\ \mathrm{m} = 400\ \mathrm{m},

which is our result from before. Yay!

Wrapping up

So there we have it. Although the solution wasn’t very mind-blowing, the journey turned out to be much more instructive than the destination. And that’s much more valuable from a problem-solving perspective.

Why, yes, I did create these graphs with TikZ. Why do you ask? ↩
Yes, I’m slyly re-using the idea of the distance being the area under the curve here. ↩
Well, it’s a deceleration, but that’s just a negative acceleration. I might have mentioned this before. 😉 ↩

DEV Community: Paul Cochrane 🇪🇺

Computational physics with Python: tool setup

A rough plan

Getting started

Installing Python

Installing Visual Studio Code

Installing the Python VS Code extension

Setting up the project folder

Creating a Python virtual environment

Creating a new Python file

A personal statistics program

More next time

I think the bots don’t like me anymore

Rising views

A sudden drop

Xmas lift-off

Hitting the categories for no good reason

Direct AI bot evidence

More questions than answers

Building LaTeX documents on GitHub

A geeky workflow for LaTeX documents

A version lag in Ubuntu’s TeXLive packages

A LaTeX-specific GitHub action

A worked example

Building the document locally

Getting GitHub to build the document for us

Archiving artefacts from the build

Finding font failures

Migrating to latex-action

Where to from here?

Addendum: metropolis and moloch woes

Finding a fisherman’s fastest path from shore to boat

Problem

Solution

At the start, collect what we know

Look at the problem from the beginning and from the end

Construct a solution using Snell's law

Numerical calculations

Extension

Wrapping up

German Perl/Raku Workshop 2026 (Berlin): a report

Getting to Berlin

Pre-workshop meetup

Day 1

Max Maischein (Corion) - Using Coding Assistants with Perl

Abigail - Sharding a database, twice

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Der Datentyp und die Datenbank

Flavio S. Glock - PerlOnJava: A Perl Distribution for the JVM Part 1

Flavio S. Glock - PerlOnJava: A Perl Distribution for the JVM Part 2

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Aus dem Nähkästchen

Thomas Klausner (domm) - Using class

Lee Johnson - I Bought A Scanner (No, Really This Time)

Day 2

Richard Jelinek (TheWhip) - Perl mit AI

Alexander Thurow (Alex) - Thoughts on (Modern?) Software Development - Beobachtungen von einer 21-jährigen Reise

Lars Dɪᴇᴄᴋᴏᴡ (daxim) - Hierarchien in SQL

Sören Laird Sörries - Digitale Souveränität und Made in Europe

Salve J. Nilsen (sjn) - What might a CPAN Steward organization look like?

Day 3

Harald Jörg (haj) - Talking to PipeWire

Herbert Breunung (lichtkind) - Raku Grammars

Raja Renga Bashyam - Perl’s T20 to Test Match Moments of Fibenis: Adaptive system evolving on Natural Lang. Principles

Paul Cochrane (ptc) - Getting FIT in Perl

Julien Fiegehenn (simbabque) - Turning humans into SysAdmins (without having to be one first)

Thomas Klausner (domm) - Deploying Perl apps using Podman, make & gitlab

Getting home

GPW2027

Avoiding empty strings in non-nullable Django string-based model fields

Stumbling over unexpected (to me) behaviour

Working with wibbly wobbly widgets

Building a basic backend application

Tacking on a frontend

Saving empty form fields is a no-no

That’s me in the corner. That’s me with my ORM, losing my integrity

Diving deep into Django’s database dealings

Sticking shackles on strings

Wrapping up

Addendum: Remember to use pytest-django, not plain pytest

StreetComplete: Pokémon Go for map geeks

Nudged into active recovery

Migrating to `latex-action`

Addendum: Remember to use `pytest-django`, not plain `pytest`