code.dblock.org | tech blog

ELPDS: Inspecting FAT Partitions in 1995

2026-10-11T00:00:00+00:00

I recovered another program I wrote in 1995: ELPDS, or Enhanced Logical & Physical Drive Status. Run ELPDS C: and it reports physical disk geometry, partition entries, FAT boot-sector details, and free space. It doesn’t change anything on the disk. My help says it was for checking whether a partition existed and was formatted. I think I was just trying to learn about the underlying partition mechanics.

I didn’t write all of it. The help credits “Mr. Schaeffer” for a “huge part of FIPS code.” That was Arno Schaefer, whose name I misspelled. FIPS could split a FAT partition without deleting its files, often to make room for Linux. Its original project page and Berkeley project page are archived. Comparing my code with the archived FIPS source found nearly identical boot-sector parsing, disk geometry routines, and even comments. I had turned its disk-reading machinery into a standalone status tool.

GitHub Copilot CLI and I made a separate DOS port using Open Watcom, leaving the original source and executable unchanged. It runs in DOSBox-X against a disposable FAT16 disk image: 16 heads, 63 sectors per track, 65 cylinders, and about 32 MiB. We fixed decoding and error handling, but this is still a tool for old DOS disks, not modern ones.

The source, port, and build instructions are on GitHub. FIPS was GPL version 2 or later, so ELPDS is too. Thirty-one years later, I finally got the author’s name and the license right.

ELPDS: Inspecting FAT Partitions in 1995 was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on October 11, 2026.

A 1998 PDF-to-Text Converter

2026-10-09T00:00:00+00:00

In 1998 I needed to convert PDF files to text for a search engine called Alkaline, without requiring separately installed libraries. So I wrote a C++ parser. Alkaline is another story.

I recovered the source from a backup dated December 26, 1998. It reads PDF 1.0 through 1.2, follows object references and page trees, decompresses content with bundled zlib, and prints metadata, page text and bookmark titles. There are my own string, vector and hash-table libraries in there too. The encryption code is a stub. This was a work in progress.

I wasn’t reverse engineering an undocumented format. Adobe had published the specification in 1993, and my comments refer to the PDF Reference, right down to a page number for stream filters. This predates tagged PDF, introduced in 2001. Getting text meant interpreting page drawing commands, not following a tagged reading order.

I was very impressed by how clever the format was. You start near the end, find the cross-reference table, and use its byte offsets to jump straight to the objects you need. A page points to its content and resources, so the reader follows those references rather than parsing the whole file from beginning to end. You don’t have to read the entire document to render one page.

GitHub Copilot CLI and I made it build again as a C++17 port, keeping the parsing approach but replacing the old containers with the standard library and using system zlib. The original is preserved unchanged. The port fixes binary stream lengths, line endings and several text operators, but it still targets those old PDF versions. Don’t point it at a modern PDF and expect miracles.

The source and port are on GitHub, under the MIT license.

A 1998 PDF-to-Text Converter was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on October 09, 2026.

Universal Copy System Link for 97 Windows PCs

2026-10-03T00:00:00+00:00

In 1997 I wrote UcsLink.Fusion for the University of Geneva. We had hundreds of PCs across the city, Sun and Windows NT servers, and Windows 95 and Linux workstations. Getting a user’s software and settings onto whichever PC they sat down at was a job for login scripts. I wrote a Delphi 2.0 application to do it instead.

UCS stood for Universal Copy System. Fusion read a script that mapped network drives, copied shared software, created shortcuts, connected printers, set environment variables and synchronized the clock. It could include other scripts, test conditions and clean up files left by a previous run. The surviving configuration maps a personal drive, a software drive and a group drive, then chooses printers based on the workstation’s location.

A user could disable optional software rather than wait for it to copy at every login, or install it later by double-clicking its icon. Administrators could make tasks mandatory and protect individual options. A tree showed the tasks and their settings; a second list showed what would run. User choices went into a personal profile, separate from the shared script.

When Fusion started at login, it displayed the little progress window below, showing the tasks as it configured the workstation.

Fusion could scan a shared software directory and automatically add each application it found to the list of available software. Each application could come with its own script describing how to install and configure it. Tasks normally ran one after another, but a detached option let copies or banners run concurrently. Later, server-generated “virtual” scripts grouped applications into one file to avoid dozens of slow network accesses.

Fusion was released as public-domain software. It was also used at ITIC, the Instituto de Tecnologia da Informação e da Comunicação (Institute of Information and Communication Technology) at Universidade Santa Úrsula in Rio de Janeiro. Its archived history page says the institute was established on March 30, 1995, initially offering Computer Engineering. It later added an information technology degree and Library Science, with an emphasis on information management. Its mission included supporting the university’s own information and communication technology needs. The illustration below says Fusion would configure the Windows 95 programs available to ITIC students.

Geneva was also helping Santa Úrsula with its campus network. An archived University of Geneva page says that in April 1997, Chancellor Madre Maria de Fâtima Maron Ramos requested an independent assessment of the network installation. A first visit took place April 18–27, 1997, with Ethernet and Fast Ethernet planned for the campus and a fiber-optic backbone connecting buildings on opposite sides of a street. Later visits were made by Jean-François L’haire, from the University of Geneva’s IT division, who came with students to propose hardware and software for Santa Úrsula. Fusion was one of these, along with BpBatch, a remote boot program from the same university. L’haire also taught at Santa Úrsula, and in 1999 he gave a course there live from Geneva over the web.

The last source code backup is from September 29, 1997. There is a whole administrator reference, a student guide and a C++Builder Windows Control Panel extension that launched the configuration browser. An application’s script could define the name, icon and options shown to users in the configuration browser.

I haven’t reconnected it to the university’s old servers. A local demonstration creates a workspace, copies a welcome document and makes a Notepad shortcut, all in its own Wine prefix. The configuration browser works again; the network operations and separate Control Panel extension remain unverified.

The original source and documentation, the port, and the build scripts are on GitHub.

Universal Copy System Link for 97 Windows PCs was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on October 03, 2026.

zBalls: a 1998 Java Applet

2026-09-29T00:00:00+00:00

In January 1998, a classmate and I wrote a game. It was called “Bolongas zBalls”, and it was a Java applet.

You click to start, then move the mouse, without clicking. Touch the dark ball to blow it up, and the next ball turns dark. Clear them all and the next level doubles the number of balls. Touch a plain ball and it spawns another one, so if you’re sloppy, the balls multiply until you lose. Each level has a time limit.

The intro music is the theme song from Capitaine Flam, the French version of the Japanese cartoon Captain Future, which aired on TF1 in 1981. I honestly don’t remember why we used it, nor why the game is called “Bolongas”.

Applets were removed in JDK 26, which is a shame, because a gray box that froze your browser for ten seconds and then asked you to trust a stranger’s code was clearly the future of the web.

You can find the source on GitHub and play the game here.

zBalls: a 1998 Java Applet was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 29, 2026.

Good Morning, Dave: the 1998 INET Conference Kiosk Launcher

2026-09-29T00:00:00+00:00

In July 1998, the Internet Society held INET ‘98, “The Internet Summit”, at Palexpo in Geneva. The University of Geneva provided about 250 computers for the conference, and I was a student there. I wrote much of the conference network’s website, www.inet98.ch, and the launcher that ran on the public Windows 95 PCs instead of Explorer.

The Inet 98 Launcher was a full-height bar on the left of the screen with a button for each installed application: Internet Explorer, Netscape, PC Pine, Telnet, WS-FTP and Office 95 and 97. I wrote it in Delphi 3. It showed a screen saver when a machine sat idle, reset itself, and could reboot the PC to return it to a clean state.

It also had a remote-control server on TCP port 895. Staff could connect from anywhere on the network, type a password and send a message to a user, hide the bar, start the screen saver, or reboot the machine. A wrong password got “alarm has been activated, you are logged!”. The right one got “Good morning dave!”.

This is the launcher running again today, under Wine on macOS. The buttons change icon on hover. The hidden -stats command asks for a password and shows the activity counters. A remote session then logs in. It gets the alarm on a wrong password and the greeting on the right one. Then it sends a message, hides and shows the bar, reads machine stats and starts the screen saver.

The conference was also the first time I had access to a T1 line to the US. Once the machines were up and running, there wasn’t much left for me to do, so I spent hours on IRC.

I found the source of both recently. They’re now at dblock/inet98.

Building It Again

I don’t have Delphi 3, so with Copilot I ported the launcher to Free Pascal and Lazarus. It builds with the Windows version of the compiler and runs under Wine on macOS.

Most of the work was in the details. The binary Delphi forms had to be converted to text. Several embedded bitmaps had headers that Delphi tolerated and Lazarus didn’t. My button component drew into its own device context and came out blank. A background thread started before the main form existed. The Delphi socket components are gone, so a small replacement is built on Free Pascal’s sockets. macOS doesn’t let a normal user listen on port 895, so it listens on 10895. The password dialog’s OK button did nothing, because Lazarus doesn’t apply a button’s default result when it loads a form.

The full list, the original source, the port, the build scripts and a prebuilt inet98.exe are all on GitHub.

Good Morning, Dave: the 1998 INET Conference Kiosk Launcher was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 29, 2026.

File & Folder 98: a 1998 Word Document Manager

2026-09-29T00:00:00+00:00

In the 1990s I wrote a document manager for a small business in Geneva with about 20 workstations. Most of its staff were new to computers, and folders were a challenging idea to grasp. They saved Word documents wherever Word happened to put them, and the network supervisor spent his days looking for lost files by panicked coworkers. File & Folder solved that problem. My 1999 product page said it was for “a small business which is sick and tired of seeing it’s workers putting documents a bit everywhere in the system.”

The first version, File & Folder 1.0, was a Visual Basic app for Windows 3.11. It sold as shareware for US$75.

A 32-bit version for Windows 95 and NT, File & Folder 1.2, followed in 1996. It worked in one root folder with numbered subfolders, supposedly one per client or case number. You typed a number, and it listed the Word documents in that folder, or offered to create one. It drove Word over OLE automation to open and create documents. The source, the Word stand-in and the scripts to run it are on GitHub.

In 1998 I attempted to generalize the idea and rewrote File & Folder from scratch in Delphi 3 as File & Folder 98. It replaced drives and directories with virtual volumes, simplifying the file system navigation into a layout that an administrator could choose. Under a volume, a folder held either documents or other folders, never both. Users created, opened, copied, moved and renamed Word documents within this one window, without needing to use the Word file dialogs. The tool also offered document previews.

File & Folder 98’s original source, the port, the build scripts are on GitHub.

File & Folder 98: a 1998 Word Document Manager was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 29, 2026.

The Second Life of Autoconf for MS-DOS

2026-09-27T00:00:00+00:00

Before GNU Autoconf generated configure scripts, there was a DOS program called Autoconf. It let you keep one CONFIG.SYS and one AUTOEXEC.BAT, then choose among boot configurations by pressing a key.

You did not have to wait for a menu. The PC BIOS kept early keystrokes in its keyboard queue, so you could press a configuration letter before AUTOCONF.SYS had even loaded. When the driver finally ran, it found the key and continued immediately.

I did not write the original. I copied its x86 assembly source by hand from a French computer magazine. It was the first assembly program I had ever seen and the first piece of code I compiled. I spent the next three or four years extending it into my first commercial product.

For a long time I could not remember who had written that first version. I had thrown away the magazine, forgotten the issue, and lost the trail before old print archives became easy to search. Only now, with AI helping sift through a large collection of scanned SVM issues downloaded from Abandonware Magazines and the Internet Archive, was I able to find the seven pages I had copied.

The Magazine

The original Autoconf appeared in the November 1991 issue of Science & Vie Micro, number 88, on pages 227–233. The article, “La configuration idéale”, was written by Julien Pommier and won the magazine’s monthly programming contest, including a 2,000-franc prize.

The seven pages contained the complete assembly listings for AUTOCONF.ASM and the 11-byte READCONF.COM, installation instructions, sample startup files, and the commands required to build everything with MASM, LINK, and EXE2BIN.

I must have spent a week copying the listing without understanding what most of it did, correcting it character by character, and figuring out how to assemble it. I needed multiple boot configurations because I was tired of editing CONFIG.SYS whenever I wanted to play a game.

Thirty-five years later, Copilot and I transcribed the listings again and built them under DOS with JWasm. They produced a 1,180-byte AUTOCONF.SYS and the original 11-byte READCONF.COM.

Then the original program booted again.

Finding Julien

Once I knew his name, I sent Julien the article with a short question: “Is this you?”

He replied the next morning: “Yes it’s me 35 years ago!” He had searched for the article several times but had never found it. He also had no idea that the program had developed a life after its publication. He had no Internet access or BBS at the time, never heard about my fork, later forgot the program’s name, and could not find it among all the results for the other Autoconf used by Linux software.

Being published in SVM had been a major moment of pride for him. Finding the article and the reconstructed history, he wrote, brought back “a whole chapter of my life.”

I told him that his program was the first code I had ever compiled and that it must have influenced my entire career. I had wanted to thank its author for decades, but I had thrown away the magazine and could no longer identify him. Old floppies and hard drives disappeared too, taking some of my own source snapshots with them.

Julien was reading the new HISTORY.md while we exchanged messages. Two people who had never met were finally comparing what the same small assembly program had meant to each of them.

My Autoconf

I lived in Geneva from 1990 through 1999. My versions of Autoconf circulated mostly as ZIP archives on BBSs, beginning with Boris & Co. ([Ne/V\eSiS]), which operated from the basement of Infomaniak when it was still a computer store. The archives traveled alongside pirated software.

The compact magazine program grew into more than 7,000 lines of assembly. It gained named and nested configurations, a sorted menu, configuration previews, one-boot line editing, many keyboard layouts, searchable help, Windows 95 support, and BOOTIT, which could reboot directly into a chosen configuration.

There were also occasional small contributions from others. The full sequence of 145 recorded changes, command-line options, companion utilities, and source archaeology can be found in the reconstructed project history.

The preserved later binary also boots under MS-DOS 5.

The source and both preserved English and French binaries contain the same build string:

assembl.: 11/01/96 (14:26)

That dates the surviving Autoconf 3.00 beta 2 build to January 11, 1996 at 14:26.

MegaBoot

The same search uncovered another program. A friend of mine, David, wrote MegaBoot in 1996 while we spent time in the basement of Infomaniak in Carouge, Switzerland.

MegaBoot was a spiritual successor to Autoconf: another DOS character-device driver that rewrote the in-memory CONFIG.SYS, but with a full-screen menu. I restored the source, made it build with JWasm, fixed two recovered bugs, and booted it under MS-DOS 5.

David granted MegaBoot an MIT license. It now has its own repository at dblock/megaboot.

What Happened to It

MS-DOS 6.0 added native multiple configurations in 1993. Autoconf did not disappear immediately; development continued through the January 1996 beta, and it still offered many things DOS did not.

Here is the same Minimal DOS, DOOM, and Windows 95 setup implemented with the native MS-DOS 6.22 startup menu.

Autoconf faded later. By the time software distribution moved from BBSs to the Internet, I had not moved the project with it, some of its source had been lost, and DOS already had a built-in solution. A separate boot-configuration product was no longer necessary.

The original and later Autoconf sources now live together in dblock/autoconf. MegaBoot lives in dblock/megaboot. Most importantly, I finally found Julien and got to say thank you.

Links

The Second Life of Autoconf for MS-DOS was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 27, 2026.

Porting a 1996 Pascal/Delphi Calculator to Rust (CLI + MCP)

2026-09-24T00:00:00+00:00

In his Rails World 2026 keynote DHH talks about one-shot apps built almost instantly with an agent as part of Omarchy. His canonical example is Omacalc, a dead simple calculator. It’s a good demo and not a hard problem. Let’s take it further and rewrite a more advanced calculator in Rust that we can also run as an MCP server, so an AI coding agent can outsource arithmetic to it instead of hallucinating a square root.

In 1994 I wrote an expression evaluator for a lab assignment. It grew into Expression Calculator, a shareware Windows app I sold through a company I co-founded, Vestris Inc. In 1997 it got pressed onto a CD-ROM and sold 3,000 copies in Germany under the name Global Calculator. I made money and users wrote fan mail. This week, Copilot and I ported its Pascal/Delphi core to Rust as excalc-rs (crates.io), a CLI and MCP server, in under 24 hours.

Both the port and the original are mathematical beasts. They can:

Chain 12 comparison and logical/bitwise operators, and 12 arithmetic operators with correct precedence
Fit 8 general/rounding functions and 7 statistics functions (mean, variance, standard deviation)
Evaluate 36 standard math functions: trig, inverse trig, and hyperbolic variants, both in radians and degrees
Answer 17 number theory questions: GCD/LCM, Fibonacci, primality, Mersenne and perfect numbers, Euler’s totient
Run 18 financial functions: NPV, IRR, loan payments, present/future value, depreciation schedules
Numerically integrate anything via 7 quadrature methods (trapezoid, Simpson, Gaussian, and more)
Compute 21 advanced/special functions: the Gamma and Beta functions, elliptic integrals, Fresnel integrals, the error function, dilogarithm, Dawson’s integral, sine and cosine integrals

Let’s verify that Euler’s Gamma function is the continuous extension of the factorial (Γ(n) = (n-1)!), and comes back essentially zero (floating-point noise from numeric integration):

calc 'gamma(10) - 9!'
# 0.000000054249539971351624

Γ(10) equals 9! to 7 decimal places, computed via numeric integration rather than table lookup.

Check out the docs/.

The 1996 Original

It wasn’t just a four-function calculator. You could work in hexadecimal, and long-running calculations ran as separate tasks. Here it is evaluating a hex expression and searching for a prime, with two tasks showing in the UI:

The original was years of work. The Pascal source code is on GitHub, open-sourced in 2009 once Vestris wound down in its original British Virgin Islands offshore incarnation. The core common/MCalc.pas is a 4,036 lines long evaluator. The full Windows app, UI included, is 10,339 lines of Pascal across the repo, backed by a 189-page user’s guide I apparently wrote it in XEmacs and typeset with SgmlTools. I have no memory of most of this code or the math behind it. It’s 30 years old. I was 20.

In 1997, MediaGlobe GmbH sold 3,000 CD-ROM copies in Germany as Global Calculator, in English, German, and French. Here’s the front and back of the box:

I still have two unopened copies.

A user was asking for a Linux port as early as 1999. Christian Rose wrote, “I’ve never used any better calculator software. But as I’m now moving to Linux, I wonder if the Expression Calculator will ever be ported to Linux?” It took me 27 years, but here we are.

The 2026 Port

The Rust port’s git history is one Copilot CLI session, 145 turns, spread over 24 hours:

2026-09-23 20:46  Initial scaffold: core arithmetic engine, standard math, statistics
2026-09-23 20:47  Add CI: build/test on Linux/macOS/Windows, fmt + clippy checks
2026-09-23 20:53  Release v0.1.0
2026-09-23 21:14  Add test coverage reporting to CI via cargo-llvm-cov and Coveralls
2026-09-23 21:38  Add MCP server exposing evaluate as a stdio tool
2026-09-23 22:29  Implement general/rounding functions (abs, frac, intg, round, trunc, ceil, floor, random)
2026-09-23 22:53  Add comparison and logical/bitwise operators
2026-09-23 23:16  Implement advanced / special functions
2026-09-23 23:32  Implement financial functions
2026-09-23 23:43  Implement general-purpose numeric integration
2026-09-24 06:07  Add short descriptions to every README example
2026-09-24 06:27  Implement variable assignment (:=)
2026-09-24 07:24  Add degree/radian conversion and degree-native trig functions
2026-09-24 07:59  Add Homebrew formula and CI validation
2026-09-24 08:09  Add Windows MSI installer via cargo-wix
2026-09-24 08:22  Release v0.2.0

The first v0.1.0 cut that did basic math shipped 7 minutes after the initial scaffold. I slept for 6 hours and went out on a run. The complete port totaled 59 commits, 5,060 lines of Rust, 217 tests, and a v0.2.0 published to crates.io, tapped on Homebrew, and shipped as a Windows MSI, by the morning.

The token bill for the port was 732 API calls across the session, ~83 million input tokens processed (~80 million of those were cache reads), and about 262,000 output tokens at a rough napkin math cost estimate of $50. Pretty great ROI given that I sold the original Expression Calculator for $25 a copy!

Some Interesting Math

Much of the advanced math in the calculator was taught by professors Ernst Hairer and Gerhard Wanner from their book, Analysis by Its History. I took the course as an undergrad.

For example, the book spends real time on elliptic integrals, which get their name from the problem of computing the arc length of an ellipse, a problem with no elementary closed form. excalc-rs implements ellipticE, the incomplete elliptic integral of the second kind, exactly as the original Pascal did as a numeric integration, not a series approximation:

calc "4 * 5 * ellipticE(0.8)"
# 25.52699886339813

That’s the circumference of an ellipse with semi-major axis 5 and semi-minor axis 3 (eccentricity sqrt(1 - 3^2/5^2) = 0.8), a number with no closed form, computed by adaptive quadrature under the hood, the same way ci, chi, erf, and a dozen other special functions are as thin wrappers around a shared int(expression, variable, lowerBound, upperBound, tolerance) engine. See docs/functions/advanced.md.

Try It Out

cargo install excalc
calc "sqrt(16) + sin(pi/2)"
# 5

Use brew tap dblock/excalc-rs https://github.com/dblock/excalc-rs and brew install excalc on macOS/Linux, or grab the MSI from the latest release on Windows.

Using AI Effectively in Technical Writing

2026-09-23T00:00:00+00:00

I write a lot, and I use AI a lot. But AI does not write my blog posts. Mostly.

AI is useful for making some of my writing less tedious. Recently, I asked GitHub Copilot CLI to read a few dozen posts from this blog and derive a VOICE.md to assist my writing. The result is now checked into this repo and linked from AGENTS.md, so any AI agent working here gets the same reminder: this blog is authored by me, not by AI and the agent’s job is to help me rather than pretend to be me.

The useful and interesting part of VOICE.md was how it captured my weirdly specific patterns.

Start with a real story, failure, command, bug, or piece of data.
Say the opinion early.
Provide examples, pull requests, commands, screenshots, numbers, links.
Admit mistakes.
Let short posts stay short.
End quickly, use Russian jokes or a link.

Technical writing is just like coding, but do not attempt to fully automate it. Be picky about words, punctuation, examples, and whether a sentence actually sounds like something you would say. Use AI to produce a flow or even a draft, to collect patterns, suggest structure, and do the boring, time-consuming work around technical reproductions or samples. When a post needs the same example in Ruby, Python, JavaScript, Go, Rust, PHP, C#, Java, Elixir, Swift, Objective-C, and Dart, have an agent generate the first pass then verify, fix, and explain the interesting parts.

Using AI Effectively in Technical Writing was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 23, 2026.

Serving Markdown for AI Agents, Now as a Jekyll Plugin

2026-09-19T00:00:00+00:00

Back in January I wrote Serving Markdown for AI Agents: for every page on this blog, there’s also a .md version at the same URL, discoverable via a <link rel="alternate" type="text/markdown"> tag, so AI agents can fetch clean Markdown instead of parsing HTML. It also made me $360, via referral conversions an AI agent apparently generated after reading the clean Markdown version of a post.

That worked, but it lived in this repo as a one-off script, _scripts/render_markdown.rb, wired into the GitHub Actions deploy workflow (needed since GitHub Pages’ native build only allows a small allowlist of plugins, which jekyll-md isn’t on), with the <link> tags added by hand via Liquid and a markdown_url front matter field on every page.

I’ve since extracted all of it into jekyll-md, a proper Jekyll plugin. It does the same thing - converts each page’s fully rendered HTML output to Markdown and injects the discovery <link> tag - but as a Jekyll::Generator and Jekyll::Hooks, with no external script or per-page front matter required.

What Changed

Add the gem and enable the plugin:

# Gemfile
gem 'jekyll-md'

# _config.yml
plugins:
  - jekyll-md

If you don’t configure anything else, jekyll-md looks for <main> or [role="main"] before falling back to the whole <body>, since that’s the closest thing HTML has to a content/chrome convention. You can also configure a CSS selector to convert from, e.g. md: selector: "#markdown-content", and other options - see the README for the full list.

What About llms.txt?

There’s a related convention, llms.txt, a single root-level file that’s supposed to give an AI agent a curated map of a site. I considered adding llms.txt generation to jekyll-md, then didn’t. The spec is explicit that the file should “stay small enough to fit in context” and contrasts itself with sitemap.xml, which it calls out for being too large and unfiltered to be useful. A plugin walking every page and dumping it into llms.txt - which is what some similar plugins do by default - just recreates the sitemap problem in Markdown instead of solving it. This blog alone has almost 600 posts; nobody wants all of them in one file.

Instead, I wrote llms.txt by hand as a plain Jekyll page with Liquid front matter, listing a handful of pinned posts, the 10 most recent ones, and a few key pages, reusing this blog’s existing pinned: true front matter flag rather than inventing a new mechanism. You can see the result at code.dblock.org/llms.txt and the template that generates it.

In Meetings, Raise Hands Before Reading

2026-09-17T00:00:00+00:00

I spent five and a half years at AWS before moving (back) to Microsoft, where I work today. At Amazon, many meetings began with silent reading. Instead of presenting a document, the author gave everyone time to read it before the discussion started.

There was a small facilitation trick that made this work surprisingly well: when reading began, everyone raised a hand. When someone finished, they lowered it. The meeting started with all hands up and counted down to zero.

At Microsoft, I found the inverse practice: everyone began with their hands down and raised one when they finished. At the time of writing this, you’ll find me hard at work changing the culture of raised hands at Microsoft, one meeting at a time. Raise your hand as you start reading, lower it when you are done.

Both approaches appear to communicate the same information. They do not. Counting down is better than counting up.

TL;DR:

A raised hand shows who still needs time, which is the information the facilitator needs.
Counting down ends unambiguously at zero without counting participants.
A forgotten click makes the group wait instead of cutting off a reader.
The facilitator can see progress and check in when only one reader remains.
Reading ends with every hand down, so raising one can immediately mean “I want to speak.”

But first, why read during the meeting at all? Jeff Bezos explained the practice at Amazon. I really like this as it forces one to prepare for the meeting, gets everyone on the same page, and offers some of the smartest but quietest people an opportunity to comment on their own pace.

Back to the hands.

At Amazon, a raised hand meant “I still need time.” The signal described the state that mattered to the facilitator: these people were still reading. When the last hand went down, the group was ready. At Microsoft, a raised hand meant “I am done,” which was less actionable. The facilitator did not need to know who was done. They needed to know who still needed time.

With hands up at the start, the meeting counts down. At zero, begin the conversation.

When hands go up as people finish, the facilitator must count them and compare that number with the expected number of readers. Was it ten people or eleven? Did someone join late? Did someone leave? Is a person without a raised hand still reading or not participating? Counting up requires knowing the denominator. Counting down only requires reaching zero.

People forget to click buttons. At Amazon, someone who forgot to lower their hand caused the group to wait a little longer. The facilitator could ask whether they were done.

At Microsoft, someone who forgot to raise their hand was indistinguishable from someone who was still reading. Worse, if the facilitator miscounted the expected readers, they might begin the discussion while someone was still trying to finish the document.

The Amazon model’s failure mode was to give people more time. The Microsoft model could fail by cutting them off.

A decreasing number of hands makes the pace of the room obvious without interrupting the silence. If several hands are still up, the group needs more time. When one hand remains, the facilitator usually checks in with the last reader: “Do you need another minute?” The reader can ask for more time or say that they are ready, without polling the entire room.

This lets the facilitator adapt the reading period to the actual document and actual readers instead of guessing in advance or repeatedly asking, “How much more time do people need?”

At Amazon, people lowered their hands when done and moved on. The active signal belonged to the people who still needed something from the meeting: silence and time.

At Microsoft, finished readers accumulated raised hands and kept signaling a state that no longer required action. The display became increasingly busy while the useful information - who was still reading - remained represented by an absence.

The Amazon practice also created a clean transition from reading to discussion. By the time reading ended, every hand was down. Anyone could then raise a hand to signal that they wanted to speak.

The inverse practice left every finished reader’s hand raised at exactly the moment the conversation began. Everyone first had to lower their hand before the same gesture could mean “I want to speak.” If someone forgot, the facilitator could not tell whether it was a stale “I finished reading” signal or a new request to join the discussion. From the Systems Engineering perspective, good protocols reset their state before changing the meaning of a signal. Counting down naturally resets every hand to down, ready for the conversation.

Start with every hand raised. Lower yours when you are done. Begin the conversation at zero.

In Meetings, Raise Hands Before Reading was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 17, 2026.

Porting a Discord Bot to Microsoft Teams, Entirely With AI

2026-09-16T00:00:00+00:00

Slava (slack-strava) connects a Strava account to a chat and posts a card for every activity, complete with map, pace, and elevation, plus commands like connect, disconnect, stats, and leaderboard. In 2023 I ported Slava to Discord by hand, evening by evening over about three weeks, and it took most of that stretch to get a working bot called Strada (discord-strava). This week I ported the same app to Microsoft Teams as Strata (teams-strava) in 3 days instead of the 3 weeks the Discord port took, using time carved out during the Microsoft Global Hackathon. By “I”, I mean GitHub Copilot CLI and I.

The 2023 Baseline

discord-strava’s git history is a fair record of how long a manual port takes. The first commit, “Initial fork from slack-strava,” landed July 30, 2023. “Most interactions working” was three days later. Getting install/help/error-handling polish took through August 20:

2023-07-30 23:56  Initial fork from slack-strava.
2023-08-02 23:46  Most interactions working.
2023-08-03 06:18  Remove PNG retrieval, Discord displays redirects correctly.
2023-08-03 06:26  Removed clubs.
2023-08-03 08:28  Fixed model specs.
2023-08-03 18:20  Fix API specs.
2023-08-04 19:44  Fix command specs.
...
2023-08-08 10:34  Countinously poll with 1 minute intervals.
2023-08-20 22:59  Improved install button and text.

20 commits spread across 9 evenings over roughly three weeks (there’s a real job and a life in between those timestamps). All hand-typed, with GitHub Copilot’s inline autocomplete helping the way it helped everyone in 2023, but no agent driving the actual porting work.

The 2026 Port

teams-strava’s git history is a single continuous Copilot CLI session, 107 conversational turns over three calendar days, and the timestamps compress dramatically:

2026-09-14 11:05  Initial port of discord-strava to Microsoft Teams
2026-09-14 16:39  Fix local dev setup and personal-scope install handling
2026-09-14 16:43  Fix 400 error replying to personal-scope install notice
2026-09-15 08:29  Document CLI-only local dev workflow in DEV.md
2026-09-15 08:41  Fix Graph permission GUIDs and add missing CLI setup steps in DEV.md
2026-09-15 09:03  Fix Strava webhook subscription errors and threaded channel posts
2026-09-15 09:11  Send the Strava connect link via a private 1:1 message
2026-09-15 09:15  Fix broken help rendering in Teams
2026-09-15 09:18  Revert connect to posting in-channel; drop personal-scope DM for now
2026-09-16 08:33  Document production Azure Bot/Entra setup in DEV.md, fix --endpoint flag
2026-09-16 08:46  Add script/verify_production.rb production sanity check
2026-09-16 08:49  Point manifest at production bot, bump version to 1.0.0
2026-09-16 09:10  Make Strata free during beta and fix homepage app download
2026-09-16 09:16  Fix production NameError: rubyzip is a test-only transitive dependency
2026-09-16 09:26  Fix 'Activity resulted into multiple skype activities' error on update

A working bot (connect, disconnect, post activities, help) existed by the end of the first day: five and a half hours elapsed between the first and last commit, but roughly three of those were actually spent hands-on-keyboard, in bursts, with breaks for a normal workday in between.

The next two sessions were where I was genuinely out of my depth: registering an Entra app, wiring up Bot Framework client-credentials auth, building and validating a Teams app manifest, getting the bot into a tenant’s app catalog, and eventually standing up a separate production Azure subscription. I’d never touched any of it before this week. Copilot CLI ran the az and m365 CLI commands, read the error messages back to me, and looked things up (multi-tenant bot registration being deprecated, a missing service principal, a renamed --endpoint flag) faster than I could have found them myself reading Microsoft Learn cold. That’s arguably the bigger win over the 2023 Discord port: not “wrote the Ruby faster” but “got me through an unfamiliar cloud platform’s auth and app-distribution model without me having to become an expert in it first.” Either way, GitHub Copilot CLI got the whole port done in 3 days instead of the 3 weeks the Discord one took, roughly 7x faster.

Copilot CLI’s own usage tracking gives a sense of scale for just that first session: 659 API calls, about 272,000 output tokens generated, and roughly 72.8 million input tokens processed, of which about 71 million were cache reads rather than fresh tokens (the CLI re-sends accumulated context on every turn, and prompt caching is what keeps that affordable). That’s the token cost of a chatty pair-programming session where the “pair” reads the whole codebase back to itself before every reply. The session started on GPT-5.4 for the first 108 calls, then switched to Claude Sonnet 5 for the remaining 551, model choice is a CLI setting, not something baked into the port.

Copilot CLI usage isn’t metered per token, it’s included in a Copilot subscription, so there’s no invoice to point at. But pricing it out at today’s public list prices for comparable models (roughly $3/$15 per million input/output tokens, with cache reads discounted to a fraction of that, cache writes at a slight premium) puts that first session at somewhere around $25-30 of raw model spend, almost all of it cache reads.

This Isn’t a Fair Fight

There’s zero reason to still do this kind of work by hand in 2026. Discord’s bot API is comparatively simple: a webhook, embeds, slash commands. Microsoft Teams brought its own pile of accidental complexity that the AI had to work through, not around: Bot Framework client-credentials auth against Entra ID, Adaptive Cards instead of embeds, a manifest/app-catalog model for distribution, and Teams Store submission requirements that don’t exist for Discord at all. The scope of this port is arguably larger than the 2023 one, and it still took a fraction of the time.

AI of course still makes mistakes:

# TeamsStrava::CardRenderer used to render one Adaptive Card per embed
# (activity + one per photo). Teams' update API rejects an activity
# update with more than one attachment:
#
#   400 BadSyntax: "Activity resulted into multiple skype activities"
#
# Fixed by combining every embed into a single card/attachment.
body = embeds.flat_map { |embed| card_body(embed) }
activity.add_card(::Teams::Cards::AdaptiveCard.new(*body)) unless body.empty?

# rubyzip was only ever required as a transitive, test-only dependency
# of selenium-webdriver, so `zip -j` worked in every spec run and then
# raised NameError: uninitialized constant ...::Zip the first time a
# real user hit the download endpoint in production.
gem 'rubyzip', require: 'zip'

Both bugs shipped, passed a full green test suite, and only surfaced against the real Teams API and the real production environment. That’s not an argument against AI-driven development, it’s an argument for test coverage: when you’re merging on green because you trust the AI wrote the code, and largely didn’t review every line yourself, your test suite is the only thing standing between a passing build and a broken production. A 574-example spec suite at 87.95% line coverage and a clean rubocop run caught plenty, but no test suite covers what it doesn’t know to test, and there’s still no substitute for a production smoke test before you tell people the thing works.

Try It Out

Strata is in beta and not yet listed in the Teams Store, but it’s real and running in production. Head to strata.playplay.io to download the app manifest and sideload it into your own tenant. This is temporary while I go through Teams Store submission; once that’s done, installing will be a one-click affair.

Standardizing Exception Message Style in Ruby

2026-09-05T00:00:00+00:00

While reviewing dozens of PRs from ericproulx optimizing Grape’s internals recently, I noticed that the bare raise ArgumentError, "..." calls scattered across the codebase were inconsistent: some messages were capitalized, some ended in a period, most were not. Longtime readers know where this is going.

Ruby’s own core and standard library exceptions don’t do this - TypeError: no implicit conversion from nil to integer, ArgumentError: wrong number of arguments, and so on all read lowercase and unpunctuated, because the message is meant to be read after the exception class name and a colon, not as a standalone sentence.

Grape’s own Grape::Exceptions::* classes already follow this convention. The bare raise ArgumentError, "..." calls in dsl/entity.rb, dsl/inside_route.rb, dsl/validations.rb, and validations/types/dry_type_coercer.rb didn’t, so I fixed those seven sites and documented the convention in CONTRIBUTING.md, in #2909.

To avoid regressions, I wrote rubocop-exception_messages, a RuboCop plugin gem with two cops:

ExceptionMessages/Casing flags (and autocorrects) messages that don’t start with a lowercase letter.
ExceptionMessages/Punctuation flags (and autocorrects) messages with a trailing period, with an exception for a literal ellipsis ("still processing.."), which is stylistic rather than a sentence ending.

Both cops recognize raise Class, "message" and raise Class.new("message") forms, and handle interpolated (dstr) messages by only checking the literal string segments (the first segment for casing, the last for punctuation), since interpolated values in the middle are out of the cop’s control.

# bad
raise ArgumentError, 'Missing required option.'

# good
raise ArgumentError, 'missing required option'

The gem ships as a modern RuboCop plugin (via lint_roller), so it’s a one-line addition to a consuming project’s .rubocop.yml:

plugins:
  - rubocop-exception_messages

rubocop-exception_messages 0.2.0 is out now, and I’ve added it back to Grape’s own Gemfile and .rubocop.yml in #2909, so the convention it started from is now enforced by CI going forward. Not everyone will agree with my choice of lowercase and unpunctuated, of course, so EnforcedStyle support to configure the opposite convention is available, along with ExceptionMessages/RedundantExceptionName, which flags messages that redundantly repeat the exception class name, and ExceptionMessages/QuoteStyle, enabled by default, which checks that interpolated values in exception messages are consistently marked, e.g. "unknown type: `#{type}`" — the same PR fixed the 16 messages across Grape’s codebase that weren’t.

Standardizing Exception Message Style in Ruby was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on September 05, 2026.

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby)

2026-08-28T00:00:00+00:00

distance_of_time_in_words is a small Ruby gem that turns two Time objects into a human-readable string like “3 days and 4 hours”. Several separate bug reports against it turned out to be variations on the same theme: computing a duration between two timestamps is not the trivial subtraction it looks like, the moment time zones are involved. The first two fixes shipped in dotiw 5.6.0; four more followed shortly after in dotiw 5.6.1.

Bug 1: `dst?` Lies When You Least Expect It

#63 reported that a duration of one minute was rendered as “less than 1 second” for users in Europe/Dublin. The gem’s TimeHash had a DST correction that looked reasonable:

d = largest - smallest
d -= 1.hour if smallest.dst? && !largest.dst?
d += 1.hour if !smallest.dst? && largest.dst?

The idea: if a DST transition happened between the two times, Time subtraction already accounts for the wall-clock jump, so cancel it back out before splitting the duration into calendar units. That works everywhere except Ireland. Europe/Dublin uses an inverted DST scheme: its winter time is legally defined as “standard time minus one hour” rather than the more common “standard time is winter, summer is +1”. Depending on whether a Time was constructed via Time.at(seconds) or datetime.to_time, dst? could report different values for the exact same instant, even though utc_offset agreed. The correction fired when it shouldn’t have, and a real one-minute gap got silently zeroed out.

Reproducing it doesn’t even require mocking dst? — just running the example with the right TZ set is enough:

ENV['TZ'] = 'Europe/Dublin'

start = Time.at(DateTime.now)
finish = DateTime.now + 1.minute

# => "less than 1 second"
# expected: "1 minute"
distance_of_time_in_words(start, finish)

The fix (PR #152) was to stop asking “is this DST?” and just compare the actual offsets:

def offset_decreased?(smallest, largest)
  smallest.utc_offset > largest.utc_offset
end

def offset_increased?(smallest, largest)
  smallest.utc_offset < largest.utc_offset
end

utc_offset doesn’t care how the Time was constructed or what a particular country calls its winter clock — it’s just the number of seconds off UTC. Reliable, and it doesn’t require knowing anything about Europe/Dublin’s specific legal quirk.

Bug 2: DST Isn’t the Only Thing That Changes an Offset

Fixing #63 with utc_offset comparisons was more correct, but still baked in an assumption: that any offset change is a ±1 hour DST transition. #153 broke that assumption. Running the test suite under TZ=Pacific/Norfolk produced a spurious “23 hours and 30 minutes” leaking into results that should have just been a clean calendar distance.

It turns out Norfolk Island permanently changed its UTC offset from +11:30 to +11:00 on 4 October 2015, announced by the island’s Administrator a month earlier — a one-time tzdata rule change, not a recurring seasonal transition. The old code’s ±1 hour hardcoding had no way to represent a 30-minute, permanent shift.

Again, a real (non-mocked) reproduction is enough — no dst? mismatch involved this time, just a genuine historical offset change baked into tzdata itself:

ENV['TZ'] = 'Pacific/Norfolk'

start = '2015-1-15'.to_time
finish = '2016-3-15'.to_time

# => "1 year, 2 months, 23 hours, and 30 minutes"
# expected: "1 year and 2 months"
distance_of_time_in_words(start, finish, true)

The real fix (PR #154) was to stop special-casing “1 hour” and generalize to whatever the actual offset delta is:

def offset_delta(smallest, largest)
  largest.utc_offset - smallest.utc_offset
end

Here’s why that’s needed, worked out with real numbers. start.utc_offset is +11:30 (41400 seconds) and finish.utc_offset is +11:00 (39600 seconds). Ruby’s Time subtraction (finish - start) already factors that in: it returns 36,721,800 seconds, which is 425 days and 1800 seconds (30 minutes) — not a clean 425 days. That’s correct: 30 real minutes did elapse due to the offset change, so the raw distance is right.

The bug was in the next step, where that distance gets split into years/months/weeks/days. That calendar breakdown doesn’t work from seconds at all — it reads largest.year, largest.month, largest.day and subtracts smallest’s, which are plain calendar fields with no concept of UTC offset. Jan 15 to Mar 15 is a clean “1 year, 2 months, 0 days” by the calendar, no remainder. Meanwhile the old buggy code applied its ±1 hour DST correction before computing the distance (since it still thought in terms of “1 hour”, not the real -1800 second delta), which left the wrong remainder behind: 36,721,800 - 3600 = 36,718,200 seconds, i.e. 424 whole days plus an 84,600-second (23.5 hour) remainder — reported as “23 hours and 30 minutes”. Neither the ±1 hour hardcoding nor the 30-minute reality had anywhere to go once years/months/days had already consumed the calendar-shaped part of the duration, so it leaked out as bogus hours and minutes. Using the real offset_delta (-1800, not ±3600) and applying it consistently everywhere the code touches @distance removes that artifact entirely, leaving just “1 year and 2 months”.

This is a strictly more general version of Bug 1’s fix — the “DST transition” case just falls out as offset_delta happening to equal ±3600 seconds. Once we stopped assuming what kind of offset change was possible, both the recurring and the one-off cases worked with the same code path. The lesson: don’t encode a specific real-world cause (DST, 1 hour) into your math when what you actually care about is a more general effect (offset changed, by however much).

Do Other Languages Have This Problem?

Curious whether this is a dotiw-specific mistake or a trap every “humanize a time difference” library falls into, I reproduced both scenarios — the Norfolk Island offset change and the Dublin DST-adjacent case — against similar libraries in JavaScript, Python, Go, Rust, PHP, C#, Java, Elixir, Swift, Objective-C, and Dart: date-fns, dayjs, moment.js, humanize, arrow, go-humanize, chrono-humanize, native DateTime::diff, Carbon, Humanizer, PrettyTime, Timex, humanizer, RelativeDateTimeFormatter/DateComponentsFormatter, and timeago. All the test code is on GitHub if you want to run it yourself.

Every one of them was clean on the Dublin case, and every one but one was clean on Norfolk too. Here’s the Norfolk Island case in JavaScript (date-fns) and Python (humanize):

process.env.TZ = 'Pacific/Norfolk';
const start = new Date(2015, 0, 15);
const finish = new Date(2016, 2, 15);

// => "about 1 year"
formatDistance(start, finish, { includeSeconds: true });

os.environ['TZ'] = 'Pacific/Norfolk'
start = datetime(2015, 1, 15, tzinfo=ZoneInfo('Pacific/Norfolk'))
finish = datetime(2016, 3, 15, tzinfo=ZoneInfo('Pacific/Norfolk'))

# => "1 year, 2 months"
humanize.naturaldelta(finish - start)

And the Dublin case in Rust (chrono-humanize) and PHP (Carbon, the closest analog to dotiw since it also supports a compound breakdown):

let dstart = Dublin.with_ymd_and_hms(2024, 10, 27, 1, 59, 30).earliest().unwrap();
let dfinish = dstart + Duration::minutes(1);

// => "in a minute"
HumanTime::from(dfinish.signed_duration_since(dstart))

$dstart = Carbon::create(2024, 10, 27, 1, 59, 30, 'Europe/Dublin');
$dfinish = $dstart->copy()->addMinute();

// => "1 minute before"
$dstart->diffForHumans($dfinish);

// => "1 year 2 months" (Norfolk case, compound breakdown, still clean)
Carbon::create(2015, 1, 15, 0, 0, 0, 'Pacific/Norfolk')
    ->diff(Carbon::create(2016, 3, 15, 0, 0, 0, 'Pacific/Norfolk'))
    ->forHumans();

C#’s Humanizer doesn’t attempt a calendar year/month breakdown at all, only weeks/days/hours/minutes, so the Norfolk case has no calendar-shaped bucket to leak into:

var norfolk = TimeZoneInfo.FindSystemTimeZoneById("Pacific/Norfolk");
var start = new DateTimeOffset(2015, 1, 15, 0, 0, 0, norfolk.GetUtcOffset(new DateTime(2015, 1, 15)));
var finish = new DateTimeOffset(2016, 3, 15, 0, 0, 0, norfolk.GetUtcOffset(new DateTime(2016, 3, 15)));

// => "60 weeks, 5 days, 30 minutes"
(finish - start).Humanize(precision: 5);

Java’s PrettyTime only ever formats a single instant relative to another (“1 year from now”), so there’s no compound breakdown at all to leak into:

ZonedDateTime start = ZonedDateTime.of(2015, 1, 15, 0, 0, 0, 0, ZoneId.of("Pacific/Norfolk"));
ZonedDateTime finish = ZonedDateTime.of(2016, 3, 15, 0, 0, 0, 0, ZoneId.of("Pacific/Norfolk"));

// => "1 year from now"
new PrettyTime(Date.from(start.toInstant())).format(Date.from(finish.toInstant()));

Elixir’s Timex, however, does reproduce the bug — same shape as dotiw’s original Norfolk failure, just a smaller leftover because it computes the real offset delta instead of hardcoding an hour:

{:ok, start} = DateTime.new(~D[2015-01-15], ~T[00:00:00], "Pacific/Norfolk", Tzdata.TimeZoneDatabase)
{:ok, finish} = DateTime.new(~D[2016-03-15], ~T[00:00:00], "Pacific/Norfolk", Tzdata.TimeZoneDatabase)

# => "1 year, 2 months, 30 minutes"
Timex.Format.Duration.Formatters.Humanized.format(
  Timex.Duration.from_seconds(DateTime.diff(finish, start))
)

That trailing “30 minutes” is exactly the Norfolk offset delta leaking out, the same artifact dotiw used to produce as “23 hours and 30 minutes” before PR #154. It’s a good confirmation that the bug isn’t a Ruby-specific mistake so much as a natural consequence of building a compound years/months/…/minutes breakdown from a raw second count without accounting for the offset change along the way — most libraries just happen to avoid the compound breakdown (or, in Carbon’s case, avoid the bug despite it) rather than being immune to the underlying trap.

I opened bitwalker/timex PR #793 with a fix, following the same strategy as dotiw’s: instead of formatting an opaque Duration (which has already lost all calendar context by the time it reaches the formatter), the fix adds a format/2 that takes both datetimes directly, computes years/months via real calendar arithmetic, and only converts the true leftover to a duration:

Timex.Format.Duration.Formatters.Humanized.format(start, finish)
# => "1 year, 2 months"

While testing this fix, I also found that format/2 crashes if finish comes before start — negative years/months get passed straight into Gettext’s plural translation, which requires a non-negative count. format/1 has always been sign-independent (Duration.from_erl({0, -65, 0}) and Duration.from_erl({0, 65, 0}) both format the same way), so format/2 should be too. Filed as a follow-up, bitwalker/timex PR #794.

Timex itself is largely unmaintained at this point — the last push to main was mid-2025, and it has more than 70 open issues — so while I was at it, I checked whether a maintained alternative avoids this whole class of bug. humanizer is a small, actively developed, English-only library with a relative_time/2,3 function. It’s clean on both the Norfolk and Dublin cases, and it also handles reversed argument order correctly without crashing — it diffs absolute instants and branches on sign rather than doing calendar-aware year/month shifting, which sidesteps the bug class structurally at the cost of using fixed-width buckets (7/30/365 days) for weeks/months/years instead of exact calendar arithmetic. The reproduction is in the same test repo, under elixir/humanizer_test/.

I later extended the reproduction to Swift, Objective-C, and Dart. Swift and Objective-C share the same underlying Foundation implementation: RelativeDateTimeFormatter/NSRelativeDateTimeFormatter (single-largest-unit “time ago” style) and DateComponentsFormatter/NSDateComponentsFormatter (a compound breakdown, directly analogous to dotiw’s output). All clean — Norfolk, Dublin, reversed order, and zero distance. Dart’s timeago package is clean too.

One thing initially looked like a fourth bug during that pass, worth mentioning because I got it wrong at first. Given a reversed (fromDate, toDate) pair, NSDateComponentsFormatter renders:

NSDateComponentsFormatter *f = [[NSDateComponentsFormatter alloc] init];
f.unitsStyle = NSDateComponentsFormatterUnitsStyleFull;
f.allowedUnits = NSCalendarUnitYear | NSCalendarUnitMonth;
f.calendar = cal; // Pacific/Norfolk

[f stringFromDate:start toDate:finish]  // => "1 year, 2 months"
[f stringFromDate:finish toDate:start]  // => "-1 year, 2 months"

That looks inconsistent — surely it should read "-1 year, -2 months" if the underlying delta is negative in both fields? But this is actually standard mixed-radix negative notation, the same convention used for negative durations (-1:30:00 means minus one-and-a-half hours, not “minus one hour plus thirty minutes”) or negative degrees/minutes/seconds coordinates: only the leading unit carries the sign, and the rest are magnitudes of that same negative quantity. NSCalendar confirms this is intentional: the raw components really are year=-1, month=-2 underneath, and the formatter correctly collapses that into a single leading sign for display, exactly as it should. Not a bug — see the test repo under objc/ and swift/ for the full reproduction and reasoning.

The main reason none of the others reproduce the bug is structural: most round to a single largest unit (“about 1 year”, “a minute ago”) instead of building a compound breakdown across years, months, weeks, days, hours, and minutes the way dotiw does. With nowhere calendar-shaped for a stray 30 minutes or 23 hours to end up, there’s no remainder left to misattribute. Carbon is the exception that proves the rule: it does support a compound breakdown similar to dotiw’s output, and still gets it right, because the offset math happens correctly underneath, at the DateInterval level, before any splitting into units occurs.

One other thing stood out while testing the Dublin case in Rust and C#. Both refuse to let you construct a local time that falls in an ambiguous window (the “fall back” hour that occurs twice) without handling it explicitly. Rust’s chrono-tz:

match Dublin.with_ymd_and_hms(2024, 10, 27, 1, 59, 30) {
    chrono::LocalResult::Single(dt) => println!("Single: {}", dt),
    chrono::LocalResult::Ambiguous(a, b) => println!("Ambiguous: {} OR {}", a, b),
    chrono::LocalResult::None => println!("None (doesn't exist, e.g. spring-forward gap)"),
}
# => Ambiguous: 2024-10-27 01:59:30 IST OR 2024-10-27 01:59:30 GMT

And .NET’s TimeZoneInfo, which surfaces the same fact via an explicit query instead of an enum:

var dublin = TimeZoneInfo.FindSystemTimeZoneById("Europe/Dublin");
var local = new DateTime(2024, 10, 27, 1, 59, 30, DateTimeKind.Unspecified);

dublin.IsAmbiguousTime(local); // => true
dublin.GetAmbiguousTimeOffsets(local); // => [00:00:00, 01:00:00]

Ruby (and most of the other languages tested) will silently pick one interpretation of an ambiguous wall-clock time and move on. Forcing the caller to disambiguate explicitly is exactly the kind of design that would have made a bug like #63 harder to write in the first place.

Bug 3: Two Unrelated Offsets Aren’t a Transition

offset_delta from Bug 2 fixed the “real transition” case, but it introduced a subtler mistake: it assumed any two Time values with different utc_offsets must represent the same clock crossing a real transition, and folded the difference in unconditionally. #160 showed that’s not true. Comparing a Time pinned to UTC against a Time pinned to a fixed -08:00 offset — two clocks that have nothing to do with each other, no shared tzdata history, no transition between them — still triggered the same folding logic:

start = Time.utc(2026, 1, 15, 12, 0, 0)
finish = Time.new(2026, 1, 15, 12, 0, 30, '-08:00')

# => "less than 1 second" (8 hours silently subtracted)
# expected: "8 hours"
distance_of_time_in_words(start, finish)

The fix (PR #161) added a same_clock? guard before applying offset_delta at all — only fold the offset when both Times plausibly represent observations of the same underlying clock (same system zone abbreviation, both non-UTC, etc.), not merely because they happen to disagree on offset:

def offset_delta(smallest, largest)
  return 0 unless same_clock?(smallest, largest)

  largest.utc_offset - smallest.utc_offset
end

Bug 4: `to_time` Doesn’t Always Mean the Same Thing

Shipping same_clock? immediately raised the next question: what actually counts as “the same clock”? #162 is a case where two ActiveSupport::TimeWithZone values, in two different named zones (Asia/Tokyo and America/Los_Angeles), get converted to plain Time via #to_time before reaching dotiw. The Time#zone accessor is normally a String (a zone abbreviation like "JST") or nil for a fixed offset — same_clock? treated any two non-nil #zones as good enough. That was true until Rails 8.0, where to_time_preserves_timezone = :zone became the default (permanent as of 8.2): TimeWithZone#to_time now returns a plain Time whose #zone is the actual ActiveSupport::TimeZone object, not a string. Two different zone objects both being “not nil” made same_clock? say yes to two completely unrelated zones, and the real 1-hour difference between Tokyo and Los Angeles got folded away into “less than 1 second” again — but only on Rails >= 8.0. Reproducing it needed the Rails 8 code path specifically:

tokyo_time = ActiveSupport::TimeZone['Asia/Tokyo'].local(2026, 1, 16, 4, 0, 0).to_time
la_time = ActiveSupport::TimeZone['America/Los_Angeles'].local(2026, 1, 15, 12, 0, 0).to_time

# On Rails >= 8.0: tokyo_time.zone and la_time.zone are both TimeZone objects (not strings),
# so the old same_clock? treated them as "the same clock" and folded the 1-hour gap away.
# => "less than 1 second" on Rails >= 8.0, "1 hour" on Rails <= 7.2
distance_of_time_in_words(tokyo_time, la_time)

The fix (PR #163) taught same_clock? to actually compare the zone objects for equality instead of just checking they’re both present:

def same_clock?(smallest, largest)
  if smallest.respond_to?(:time_zone) || largest.respond_to?(:time_zone)
    smallest.respond_to?(:time_zone) && largest.respond_to?(:time_zone) &&
      smallest.time_zone == largest.time_zone
  elsif !smallest.zone.is_a?(String) || !largest.zone.is_a?(String)
    !smallest.zone.nil? && smallest.zone == largest.zone
  else
    !smallest.zone.nil? && !smallest.utc? && !largest.zone.nil? && !largest.utc?
  end
end

This one is a good reminder that a library’s own dependencies can quietly change the shape of the objects you’re handed. dotiw never called to_time itself — a Rails minor version bump changed what Time#zone returns for values constructed elsewhere entirely, and the bug only showed up for people on the new default.

Bringing In More Test Cases

Since both of these bugs turned out to have prior art elsewhere, I went back through the test suites of the libraries surveyed for Bug 2/3 — Luxon’s diff tests, Timex’s humanized-duration tests, and the tz_test reproductions — and pulled in the ones that translate directly into dotiw regression examples: a UTC-vs-CEST offset comparison from Luxon (PR #166) and the historical Norfolk Island offset change (PR #167), both passing cleanly against the fixed same_clock?/offset_delta. (These started life bundled together in a single PR #164, later split apart once it became clear the third example below needed materially different treatment.)

The Timex-derived case — a Europe/Dublin DST fall-back, one real minute elapsing across the clocks-back transition — turned up a fifth wrinkle while adapting it: same_clock? correctly recognizes both timestamps as the same clock (they really are the same TimeZone object), so offset_delta still folds in the full 1-hour offset change. But here the actual elapsed time is only 60 seconds — smaller than the offset delta being folded in — so the correction overshoots and produces a negative corrected distance, again collapsing to “less than 1 second” instead of “1 minute”. Unlike Bugs 3 and 4, this isn’t about misidentifying whether two Times are the same clock; it’s that the folding math assumes the real elapsed time is always large relative to the offset shift, which breaks down right at the boundary of a transition. Filed as #165 and fixed in PR #169: the offset correction now only ever applies to the sub-day leftover, once the distance has already been split into calendar fields, rather than to the top-level distance used to decide which calendar branch (build_years, build_days, etc.) to take in the first place — so a genuinely tiny elapsed time can no longer be pushed past zero by a much larger offset shift.

Bug 5: An Unforced Conversion, Not a Rails Version Limitation

Verifying the #165 fix across every supported Rails version turned up one more thing. The regression spec for #165’s sibling case — the Norfolk historical offset change, this time expressed as ActiveSupport::TimeWithZone values rather than plain Time — only passed on Rails >= 8.0. On Rails < 8.0, it failed with a spurious “1 year, 2 months, and 30 minutes” instead of “1 year and 2 months”, suspiciously similar to the very bug #154 had already fixed. I was pairing with an AI coding assistant on this fix, and its first instinct was to shrug this off as an inherent Rails < 8.0 limitation (the same to_time_preserves_timezone distinction from Bug 4) and skip the spec on older Rails.

That instinct was wrong, and it took me pushing back — “the following code should always give the correct answer, no?” — before it looked closer instead of accepting its own shortcut. The real cause: distance_of_time_in_words unconditionally called #to_time on any TimeWithZone argument before doing anything else with it:

from_time = from_time.to_time if !from_time.is_a?(Time) && from_time.respond_to?(:to_time)

On Rails < 8.0, TimeWithZone#to_time (without to_time_preserves_timezone set) returns a plain Time in the process’s local system zone, discarding the actual zone entirely — which is exactly the information same_clock? needs to recognize two readings as the same clock across a transition. But nothing about TimeHash actually needs a plain Time in the first place: TimeWithZone already supports every operation it performs — subtraction, #advance, #year/#month/#day/#hour, #utc_offset — without ever being converted. The #to_time call wasn’t a Rails-version workaround at all, just an unforced, avoidable conversion that happened to only cause visible damage before Rails 8.0’s default changed what it produced.

Filed as #170 and fixed in PR #167 with a coerce_to_time helper that leaves Time and TimeWithZone arguments untouched, only calling #to_time on genuinely non-Time-like values (Date, DateTime):

def coerce_to_time(value)
  return value if value.is_a?(Time) || value.respond_to?(:time_zone)

  value.respond_to?(:to_time) ? value.to_time : value
end

With that in place, the Norfolk TimeWithZone example (and the #165 Dublin fall-back example) both pass on every supported Rails version, 7.0 through 8.1, with no skip required — a stronger fix than the version-gated one I’d initially assumed was necessary.

The Common Thread

All three failure modes share a shape: a plausible-looking shortcut (dst? instead of utc_offset, “correct by exactly 1 hour”, “convert to a plain Time up front”) that works for the overwhelmingly common case and quietly breaks for a specific, real-world edge case that a bug reporter with an unusual time zone eventually ran into. None were caught by the existing test suite, because the test suite ran in one time zone, on inputs that never crossed the affected boundaries — and, in Bug 5’s case, on only one version of Rails.

The actual fix was the same in spirit each time: replace the specific assumption with the general, verifiable fact it was standing in for — actual offsets instead of a DST flag, an arbitrary delta instead of a fixed hour, and no conversion at all where none was ever needed. If you maintain a library that touches wall-clock time, it’s worth asking, for every “obvious” shortcut in the code, what real-world weirdness it’s quietly assuming doesn’t exist — and, per Bug 5, whether “this only works on newer Rails” is really a platform limitation or just an unforced move your own code is making. Europe/Dublin and Pacific/Norfolk are more common exceptions to your assumptions than you’d think.

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby) was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 28, 2026.

Benchmarks Are Free Now

2026-08-15T00:00:00+00:00

My previous post walked through four bugs in ruby-enum, a gem I maintain, all stemming from the fact that class-level instance variables aren’t inherited by subclasses. The third fix, #59, made keys, key?, value?, key, value, to_h, parse and each walk up superclass and merge in a parent’s enums, so a subclass would see everything its ancestors defined. It was correct, fully tested, and shipped. It also made every one of those methods roughly 5x slower on any subclass.

def _enum_hash
  if superclass < Ruby::Enum
    superclass.send(:_enum_hash).merge(_own_enum_hash)
  else
    _own_enum_hash
  end
end

This recomputes the merged hash, walking the entire ancestor chain, on every single call. There’s no caching. A one-level subclass calling .value pays for building a brand new hash, on top of the superclass doing the same, every time. The test suite didn’t notice because tests check correctness, not speed, and correctness was fine.

I only found this because I asked Copilot CLI to add a benchmark script comparing lookups at different inheritance depths, mostly out of curiosity about how the “Benchmarks” section of the README would read next to the new feature. It took one prompt and about a minute to get a working script:

class Colors
  include Ruby::Enum
  define :RED, 'red'
  define :GREEN, 'green'
end

class SubColors < Colors
  define :BLUE, 'blue'
end

class SubSubColors < SubColors
  define :YELLOW, 'yellow'
end

benchmark('base class (no inheritance)', n) { Colors.value(:RED) }
benchmark('subclass (1 level)', n) { SubColors.value(:RED) }
benchmark('sub-subclass (2 levels)', n) { SubSubColors.value(:RED) }

The first run told the story immediately: a 1-level subclass’s .value calls took roughly 5x as long as the base class, and a 2-level subclass was worse still. Nobody had written this benchmark before merging #59 because writing a throwaway benchmark script used to feel like more ceremony than it was worth for a one-off performance check. Now it’s a single sentence to an agent, and the script stays in the repo afterward as a rake benchmark:inheritance task anyone can rerun.

The fix was small: memoize the merged hash and invalidate the cache only when define adds a new entry.

def _enum_hash
  @_enum_hash ||= if superclass < Ruby::Enum
                    superclass.send(:_enum_hash).merge(_own_enum_hash)
                  else
                    _own_enum_hash
                  end
end

Re-running the same benchmark after the fix (#60):

--- .value lookups, by depth of inheritance ---
base class (no inheritance): 0.0627
subclass (1 level): 0.0608
sub-subclass (2 levels): 0.0606

Subclass lookups are now indistinguishable from the base class, regardless of depth. I also had Copilot CLI write a second benchmark (#61) comparing basic Ruby::Enum operations against plain Ruby equivalents, since I was about to write a README claim about the gem’s overhead and didn’t want to write “negligible” without a number to back it up. Constant access turned out to be free (Colors::RED is exactly as fast as a plain Ruby constant), but hash-backed lookups like .value and .key? carry a real, if small, 3-5x cost versus calling Hash#[] directly - the price of the extra method dispatch and object wrapping Ruby::Enum does. Worth knowing, not worth avoiding the gem over. That number, along with the exhaustive Ruby::Enum::Case matcher’s much larger 50-100x overhead versus a native case statement, is now spelled out in a dedicated Performance section in the README, so nobody has to ask or guess.

None of this changes the underlying lesson that a performance regression is easy to introduce and easy to miss when your tests only check correctness. What’s changed is the cost of catching it. Writing a benchmark script used to be the kind of thing you’d skip on a Friday afternoon for a “just a getter method” change. Now, benchmarks are free.

Benchmarks Are Free Now was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 15, 2026.

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL)

2026-08-14T00:00:00+00:00

The ruby-enum gem is a small library I maintain that adds enum-like behavior to a class via include Ruby::Enum and define :KEY, value. Four pull requests landed against it recently, each fixing a different symptom, and all four turned out to be the same underlying bug: class-level instance variables set in a module’s included hook are not inherited by subclasses the way you might expect. All of these fixes shipped in ruby-enum 1.2.0.

Ruby::Enum stores its keys and values in instance variables on the class itself, set up when the module is included.

def self.included(base)
  base.extend ClassMethods
  base.instance_variable_set(:@_enum_hash, {})
  base.instance_variable_set(:@_enums_by_value, {})
end

This works fine for a single class. It gets interesting the moment subclasses or class reloading show up.

A user opened #56, reporting DuplicateKeyError from a Rails console after a class that had already defined its enums got reloaded. It reproduces without Rails.

class_body = proc do
  include Ruby::Enum

  define :RED, 'red'
end

Colors = Class.new(&class_body)
Colors.class_eval(&class_body) # raises DuplicateKeyError

Rails’ development-mode autoloader re-evaluates a class body, and the second define :RED sees @_enum_hash still holding RED from the first load, so the duplicate-key check fires. The fix clears the hash whenever Ruby::Enum is included, rather than assuming it’s always a fresh class. The contributor that reported the problem and submitted the fix also caught a sneakier variant: a subclass that redundantly re-includes Ruby::Enum (include is supposed to be idempotent, right?) was wiping out enums inherited from its parent, because included unconditionally reset the instance variables:

class OtherSecondSubclass < FirstSubclass
  include Ruby::Enum # redundant, but shouldn't lose FirstSubclass's enums

  define :MAGENTA, 'magenta'
end

Thanks, Nazar, for tracking both of these down with tests.

Months later, #49 surfaced a related crash: a subclass that never calls define itself, just inheriting from a parent that does, blew up on .values.

class Colors
  include Ruby::Enum

  define :RED, 'red'
end

class SubclassWithNoOwnDefines < Colors
end

SubclassWithNoOwnDefines.values # NoMethodError: undefined method `values' for nil

This is because @_enum_hash is only ever set in two places: the included hook, and redundantly again in define. A subclass that inherits Ruby::Enum transitively and never calls define runs neither, so its own @_enum_hash is nil. This is the crux of it: SubclassWithNoOwnDefines.instance_variable_get(:@_enum_hash) and Colors.instance_variable_get(:@_enum_hash) are two completely separate variables, even though one class is a subclass of the other. Instance variables, unlike methods, don’t look up the ancestor chain.

Eight methods (keys, key?, value?, key, value, to_h, parse, each) had this bug, just with less obvious failure modes. The fix in #58 was to stop reading the raw @ivar directly and go through a private reader that lazily defaults to an empty hash.

def _enum_hash
  @_enum_hash ||= {}
end

Once a subclass with no enums of its own correctly returned an empty list instead of crashing, the obvious next question was whether it should instead see its parent’s enums, the same way it sees inherited methods. Thus, #59 extended all eight methods to walk up superclass and merge in inherited enums, with a subclass’s own definitions taking precedence when they overlap.

def _enum_hash
  if superclass < Ruby::Enum
    superclass.send(:_enum_hash).merge(_own_enum_hash)
  else
    _own_enum_hash
  end
end

Same lesson, opposite direction: since @_enum_hash isn’t automatically inherited, subclass-aware behavior has to be built by hand, walking superclass and merging state explicitly.

Recomputing that merge on every single call is correct but wasteful - O(depth) work per lookup with no caching. I benchmarked it (more on that in a follow-up post) and found a one-level subclass paid a 5x tax on .value lookups versus the base class. #60 memoized the merged hash, invalidating it only when define adds a new entry.

Class-instance-variables in Ruby - @ivar set on a class object, as opposed to instance-level @ivars on regular objects - are per-class. They aren’t inherited, and reloading a class doesn’t reset them for you. If a gem’s DSL needs subclass-aware or reload-safe behavior, that has to be built in explicitly: clear state on include, default lazily instead of assuming initialization already ran, and walk superclass yourself if you want inheritance-like semantics.

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL) was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 14, 2026.

Generating AI Descriptions of Automated Pull Requests

2026-08-11T00:00:00+00:00

The slack-ruby-client library, an open source Ruby gem I maintain, runs a scheduled GitHub Actions workflow that regenerates code from Slack’s API definitions and opens a pull request with the diff. The commit message and CHANGELOG entry used to be a generic “Update API (2026-08-11)”, which told a reviewer nothing about what actually changed. Here’s how we taught the workflow to describe its own diffs, using GitHub Copilot CLI, which open source maintainers can get for free.

The Idea

The workflow already computes a diff before opening the pull request. Instead of a boilerplate commit message, we pipe that diff through an LLM and ask it to summarize what changed, then use the response as the commit message and PR body.

- name: Check for changes
  id: changes
  run: |
    if git diff --quiet; then
      echo "changed=false" >> "$GITHUB_OUTPUT"
    else
      echo "changed=true" >> "$GITHUB_OUTPUT"
    fi
- name: Prepare diff for AI summary
  if: steps.changes.outputs.changed == 'true'
  run: |
    git diff --stat | sed 's/^/      /' > /tmp/diff_stat.txt
    git diff | head -c 20000 | sed 's/^/      /' > /tmp/diff.txt

The sed 's/^/ /' indent isn’t decorative. actions/ai-inference substitutes template variables as raw text into a prompt YAML file before parsing it, so a multi-line diff starting at column 0 breaks the indentation of the enclosing content: |- block scalar. Pre-indenting the file to match keeps the YAML valid no matter what the diff looks like.

The Prompt File

actions/ai-inference supports .prompt.yml files, a small convention for keeping the system/user prompt out of the workflow YAML.

messages:
  - role: system
    content: |-
      You write CHANGELOG entries describing an automated API update to slack-ruby-client, a
      Ruby gem whose Web API endpoint methods, argument validations, specs, and bin commands
      are code-generated from vendored Slack API method definitions (via a git submodule and
      rake task).

      Given a diffstat and a diff of the regenerated files, respond with ONLY a single JSON
      object (no markdown code fences, no other text) in exactly this shape:
      {"entries": [string, ...]}

      Rules for entries:
      - Each entry is a single short line, imperative mood, no leading bullet/dash and no
        trailing period (the caller adds both).
      - Group related changes together into one entry per notable change or affected method
        group, rather than one entry per file.
      - Focus on developer-visible API surface changes: new/removed/renamed methods, new/
        removed arguments, validation changes.
  - role: user
    content: |-
      
      

Asking for a single line per group of changes, rather than per file, matters, a single Slack API update can touch dozens of generated files for one conceptual change (adding an argument to five related methods, say), and nobody wants five identical CHANGELOG lines about it.

Wiring It into the Workflow

- name: Generate changelog entries with AI
  if: steps.changes.outputs.changed == 'true'
  id: ai
  uses: actions/ai-inference@v1
  with:
    prompt-file: ./.github/prompts/changelog-entries.prompt.yml
    file_input: |
      diff_stat: /tmp/diff_stat.txt
      diff: /tmp/diff.txt
- name: Build changelog entries
  id: entries
  run: |
    entries=""
    if [ "$" = "true" ]; then
      response_file="$"
      echo "AI changelog response:"
      cat "$response_file" || true
      json_line="$(grep -E '^\{.*\}$' "$response_file" 2>/dev/null | tail -n 1)"
      if [ -z "$json_line" ]; then
        echo "::error::AI changelog response did not contain a JSON object, see response above."
        exit 1
      fi
      entries="$(printf '%s' "$json_line" | jq -r '.entries[]? // empty')"
    fi
    if [ -z "$entries" ]; then
      entries="Update API ($)"
    fi

A few defensive touches worth calling out. The step always logs the raw AI response, so a bad run leaves a paper trail in the logs. Rather than trying to parse the whole response file as JSON, it greps for the last line that looks like a JSON object (^\{.*\}$) and parses just that: Copilot CLI sometimes narrates its reasoning (“Let me check the diff…”, “Now I have enough info…”) before printing its final answer, and naively parsing the entire file as JSON would either crash on that narration or, worse, silently discard a perfectly good response. Finally, if no such JSON line is found at all, the workflow fails loudly with ::error:: instead of quietly falling back to a generic changelog entry, an earlier version of this step swallowed genuine parsing failures and it took a couple of confusing scheduled runs to notice.

Once we have the entries, we use them both as the commit message/PR body and to insert one CHANGELOG line per group, all referencing the same (predictable, since GitHub allocates them sequentially) PR number:

lines = entries.map do |entry|
  "* [##{pr_number}](#{pr_url}): #{entry} - [@slack-ruby-ci-bot](https://github.com/apps/slack-ruby-ci-bot)."
end.join("\n")

You Can’t Use GitHub Models

If you’re setting this up today, skip GitHub Models as the backend, it was retired on July 30, 2026 and actions/ai-inference no longer talks to it at any version. The v1 tag, in particular, doesn’t float to the rewrite, it’s stuck resolving to the old GitHub-Models-only code, so don’t expect a version bump to fix things automatically. The current major version, v3, speaks exclusively to GitHub Copilot CLI instead, which changes a few things about the setup:

- name: Set up Node
  uses: actions/setup-node@v6
- name: Install Copilot CLI
  run: npm install -g @github/copilot
- name: Generate changelog entries with AI
  if: steps.changes.outputs.changed == 'true'
  id: ai
  uses: actions/ai-inference@v3
  with:
    prompt-file: ./.github/prompts/changelog-entries.prompt.yml
    model: ''
    file_input: |
      diff_stat: /tmp/diff_stat.txt
      diff: /tmp/diff.txt
  env:
    COPILOT_GITHUB_TOKEN: $

Copilot CLI has to be installed on the runner (the action doesn’t bundle it any more), authentication is via COPILOT_GITHUB_TOKEN rather than the old token input, and responseFormat/jsonSchema inputs are gone entirely, hence asking for bare JSON in the prompt and parsing it defensively, as above. We also set model: '' explicitly; the action’s built-in default (gpt-4.1) isn’t necessarily available on every Copilot plan, and an empty string tells the CLI to fall back to whatever model it has access to.

For the token, if your org has a paid Copilot Business or Enterprise plan, you can enable “Allow use of Copilot CLI billed to the organization” and grant the workflow the copilot-requests: write permission, then the built-in GITHUB_TOKEN just works, no secret needed. Free organizations (like slack-ruby) don’t have that option, since free Copilot access for open source maintainers is granted to individual maintainer accounts, not organizations, so the fallback is a personal fine-grained PAT with the “Copilot Requests” account permission, stored as a COPILOT_PAT secret.

Testing Before Merging

Both workflows have a github.repository == 'slack-ruby/...' guard so they don’t run on forks by accident, which also means we can’t just dispatch them there to test. We got around this by pushing a disposable branch to our own fork, temporarily overriding the guard (if: true), adding a throwaway step to force a non-empty diff (the real scraping step usually finds nothing new on a given day), and dispatching manually.

gh workflow enable "Update API" --repo dblock/slack-ruby-client
gh workflow run "Update API" --repo dblock/slack-ruby-client --ref test-copilot-cli
gh run watch <run-id> --repo dblock/slack-ruby-client --exit-status

This is how I caught both the missing-token and the unavailable-model issues above, neither of which was obvious from reading the action’s README.

Links

Generating AI Descriptions of Automated Pull Requests was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on August 11, 2026.

Coding with AI Agents is Now a Baseline Expectation for Managers

2026-05-05T00:00:00+00:00

AI-first Engineering is now the operating default in many organizations, including mine. Developers have kept up. Vibe coding became agentic engineering, and the race towards truly autonomous engineering isn’t slowing.

But what are we, managers, to do?

A manager job continues to include recruiting and retaining people, setting clear goals and expectations, fostering communication, owning team workflows, and coaching daily behaviors. To this list we must now add driving AI transformation.

Being a passive advocate is not enough. Unlike other subjects, no amount of AI training will help you keep up with the pace of evolution of this technology. Therefore, one cannot drive AI transformation without being an active AI practitioner. But what does being an active AI practitioner look like for a manager?

To find out, I landed myself into a small Engineering team (7 people) within my 100+ people organization five weeks ago. This small group develops an essential internal Microsoft system used by every single Engineer at the company. I wanted to learn firsthand about their challenges by onboarding into the project, and maybe contribute 2-3 PRs myself. I decided to dedicate my Copious Free Time™ to this work, to only use Copilot (you can use Claude, or another CLI, too), and to attend the team’s daily standup.

Before I talk about what I did or learned, I must apologize to the team for giving them a heart attack upon my arrival. It’s rare that a VP of Engineering, many levels “above”, inserts themselves into any team unless there’s some huge, urgent, problem. This wasn’t an issue with the specific team, but transforming the way we work remains absolutely urgent, and it’s my responsibility to do everything I can to make it happen.

Initially, I expected to make 2-3 pull requests. Instead, I was able to make 89 (!), broke at least two production features, but also shipped some meaningful improvements. These fell into several categories.

Improved developer experience. I fixed several issues in local dev, wrote a new CONTRIBUTING guide, added a script to start and shutdown various services together, and added an AGENTS.md to make the repo AI-agent-ready.
Did batch dependency upgrades to address CVEs. Major upgrades required rework of the actual code. Two of these silently broke features in very subtle ways, showing gaps in integration testing, but also taking a lot of team’s time to debug unexpectedly.
Increased test coverage and overall repo quality. I wrote a number of missing unit and integration tests and fixed a few flaky ones. A clear win.
Improved CI/CD pipeline. I was able to bring the CI time down from over an hour to ~30 minutes, mostly by not building projects without code changes, and disabling the many checks and guards that didn’t need to run on every pull request.
Executed some overdue modernization. I finished a Webpack to Vite migration that another engineer stalled on because of conflicting priorities, significantly improving local build time, upgraded TypeScript 4 to 5, Node.js 16 to 20, LESS to SCSS, MSTest 2.x to 3.x. All these upgrades were on the team’s backlog, but nobody ever had time to do them.
Fixed many minor bugs. Other than bugs reported by users, I paid attention to warnings during build or in the JavaScript console, and asked Copilot to address them. I improved error display, corrected dark mode CSS, addressed sass deprecation warnings and ESLint errors.

Here’s what I learned.

This AI sh*t is wild. Driving Copilot is like holding the reins of a Russian winged troika. The only limitation was my own time, memory, and the amount of changes I was able to keep active in my head in parallel at one given time. I’d come up with a thing to do, tell Copilot to do it, it would make the change, open a pull request, get it reviewed by another AI, address comments, and iterate to green. I would intervene once this loop was finished, review the change, and mark it as ready to be reviewed by another Engineer.
We are absolutely not ready for the onslaught of agent-generated changes. Human attention quickly became the bottleneck. If a manager with a full-time job can open 20+ pull requests per week that pass CI and accomplish a positive change, a group of 5 full-time engineers plus an army of autonomous agents will be generating hundreds. The team immediately wondered whether they would go from being developers to full-time code reviewers, while real breaking changes slipped through otherwise trivial updates.
Copilot is the new rubber duck, developer social, and software architect. It’s now much faster to ask Copilot to explain a problem and then to fix an issue than to discuss any of it with teammates. It’s faster to design and implement 3 versions of a feature than to discuss which approach is cleaner ahead of time. You can now truly lead with code.

But the most interesting thing that happened during this experiment is that the team’s PR velocity doubled without counting mine. Using Copilot became contagious. I am confident this is permanent — I never want to write code by hand again. There’s no turning back.

If you manage a team of any size and have never coded with AI at work, become the janitor of one of your team’s repos. Start by improving onboarding docs and CI/CD time. Doing this work was both impactful and a lot of fun. Feel the energy!

Coding with AI Agents is Now a Baseline Expectation for Managers was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on May 05, 2026.

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog

2026-04-11T00:00:00+00:00

In April 2025 I wrote Apologizing for My Obsessiveness Over Punctuation, a post about my various organizational compulsions. Near the end, almost as an aside, I mentioned that I obsessively categorize expenses in Monarch, a personal finance app, linking it with my referral code. That post earned me exactly one referral in the nine months that followed.

Then, on January 15th, 2026, I wrote Serving Markdown for AI Agents. The idea is simple: for every post on this blog, there’s now a .md version at the same URL. AI agents can discover and fetch clean markdown instead of parsing HTML. I didn’t think much of it.

Exactly thirty days later - the length of Monarch’s free trial — I started getting a stream of referral conversion notifications without any change in SEO traffic.

Eighteen signups.

Twelve converted to paid. At $30/referral, that’s $360.

We live in the future.

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on April 11, 2026.

Opening Proprietary Code to Contributors Checklist

2026-04-08T00:00:00+00:00

Before AI coding assistants, a typical engineering team built expertise with the years: new team members joined, contributed small bug fixes, then were given more ambitious tasks over time as they became more comfortable in a codebase, to ultimately become experts. This process took years.

In contrast, today, almost every engineer, and many non-engineers, have access to tools that can gather context from any codebase, and produce a large volume of high-quality code in a day. This lowers the bar for contributing meaningful changes to the software we build and enables many more individuals without domain or codebase expertise with good ideas to see them to light.

At work, I asked my team to actively seek contributions from our customers with an active engagement for our proprietary code. Inspired by the open-source model, we are reviewing our systems from the angle of a newcomer easily contributing to them.

Here’s a checklist to apply to any repo.

Create a single landing CONTRIBUTING.md that welcomes contributors and encourages them to contribute while insisting on higher standards, such as needing to write automated tests with every contribution.
Make your source code repo discoverable. Your source code README, and your product or tool should have a visible link to your single CONTRIBUTING.md.
Include a simple to follow “Getting Started” checklist in CONTRIBUTING.md that enables any developer at the company to make a trivial change in the application and submit a pull request.
Ensure that your project has an automated test suite that runs in CI, is trivial to run locally, has few to no dependencies, and has enough coverage to give confidence to any new contributor that they did not break key functionality.
Evolve every project to a state where a minimum viable version of it can run locally without the need to ask for permissions, certificates, or keys, install or get access to unnecessary dependencies, removing those barriers from the new contributor path. Describe how to run the project locally in CONTRIBUTING.md.
Ensure safe CD by making the project’s deployment model self‑describing, clearly signaling where changes land first, what approvals and gates exist, and how regressions are detected and rolled back, so both new and existing contributors can ship changes with confidence.
Prefer GitHub fork/PR model where contributors do not need permissions to your source code and protect source such that contributors cannot accidentally force push an update to main.
One should be able to open a PR without ever needing to contact your team that owns the project.
Enable and encourage contributors to open bugs and feature requests directly and triage new issues weekly. Engage customers publicly within these systems rather than offline or e-mail.
Establish a publicly accessible channel for your own developers and for contributors to meet and ask technical questions and link it from CONTRIBUTING.md.
Create a daily short standup for your team that is open to others actively contributing to your repo to drop into and make it easily discoverable. Use the standup to socialize external contributions across the team.
Create a habit of all team members reviewing and approving PRs and delegate repetitive requests, such as needing tests, to A.I. reviewers. Ensure that both team PRs and PRs made by external contributors are engaged within one day, and that all team members are reviewing and approving each other’s PRs regularly, not just one person.
Create an automated CHANGELOG or a Release Notes process that highlights both team and external contributors, and that is discoverable from your product or tool. Take the time to directly highlight one’s contribution to their manager when impactful.
Make the repo AI-friendly with AGENTS.md that contains instructions for AI that help humans collaborate with AI to produce a feature.
Continue prioritizing most impactful features to be shipped by your own team while actively engaging your customers by inviting them to contribute the features that you cannot deliver quickly. Highlight external contributions in business reviews.

And if nobody volunteers to contribute to our projects, most of these steps will also make it easier and more efficient for my own team members to work on the codebase, to enable partner teams to do work, and reduce the time needed to onboard new engineers joining my organization.

Level up!

Opening Proprietary Code to Contributors Checklist was originally published by Daniel Doubrovkine at code.dblock.org | tech blog on April 08, 2026.

code.dblock.org | tech blog

ELPDS: Inspecting FAT Partitions in 1995

A 1998 PDF-to-Text Converter

Universal Copy System Link for 97 Windows PCs

zBalls: a 1998 Java Applet

Good Morning, Dave: the 1998 INET Conference Kiosk Launcher

Building It Again

File & Folder 98: a 1998 Word Document Manager

The Second Life of Autoconf for MS-DOS

The Magazine

Finding Julien

My Autoconf

MegaBoot

What Happened to It

Links

Porting a 1996 Pascal/Delphi Calculator to Rust (CLI + MCP)

The 1996 Original

The 2026 Port

Some Interesting Math

Try It Out

Links

Using AI Effectively in Technical Writing

Serving Markdown for AI Agents, Now as a Jekyll Plugin

What Changed

What About llms.txt?

Meta

In Meetings, Raise Hands Before Reading

Porting a Discord Bot to Microsoft Teams, Entirely With AI

The 2023 Baseline

The 2026 Port

This Isn’t a Fair Fight

Try It Out

Links

Standardizing Exception Message Style in Ruby

Adventures in Daylight Saving, Norfolk Island, and Time Zone Math (in Ruby)

Bug 1: dst? Lies When You Least Expect It

Bug 2: DST Isn’t the Only Thing That Changes an Offset

Do Other Languages Have This Problem?

Bug 3: Two Unrelated Offsets Aren’t a Transition

Bug 4: to_time Doesn’t Always Mean the Same Thing

Bringing In More Test Cases

Bug 5: An Unforced Conversion, Not a Rails Version Limitation

The Common Thread

Benchmarks Are Free Now

Ruby Instance Variables Are Not Inherited (and Why That Breaks Your DSL)

Generating AI Descriptions of Automated Pull Requests

The Idea

The Prompt File

Wiring It into the Workflow

You Can’t Use GitHub Models

Testing Before Merging

Links

Coding with AI Agents is Now a Baseline Expectation for Managers

How I Made $360 by Serving Markdown to A.I. agents from My Jekyll Blog

Opening Proprietary Code to Contributors Checklist

Bug 1: `dst?` Lies When You Least Expect It

Bug 4: `to_time` Doesn’t Always Mean the Same Thing