DEV Community: Christian • ancer

Testing a Batch Image Pipeline Before It Touches Your Files

Christian • ancer — Wed, 28 Oct 2026 09:00:00 +0000

Making crop work on one image is the easy part. Making it safe to run on two hundred of somebody else's files is the actual job, and what decided when it shipped was a test list.

The first two tests on that list failed. Not on the crop, which was the point of the list, but on the version of Convertim that had been out since July.

Crop shipped on Monday, in Convertim 2.1. This is how the pipeline is tested, what the crop had to pass before it shipped, and what those two failures taught me about the two hundred tests that had been passing all along.

What was already there

Convertim is a portable image converter for Windows: a desktop app and a CLI, both on top of one conversion engine built on sharp. The desktop app reaches the engine through Electron's main process; the CLI calls it directly. Same functions, same options.

That shared engine is where most of the tests point. There are a little over two hundred, on Node's built-in test runner, in a few layers:

Engine and pipeline. Formats in and out, quality, lossless, both resize modes, rotation and flips, colour adjustments, text and image watermarks in each position, and the guards that refuse to vectorise a photo.
The CLI as a real process. Flags, JSON output and exit codes. A batch with one corrupt file and one valid file has to convert the valid one and exit with 2, partial success.
The packaged executable. A smoke test that runs the real binary and checks that what comes out decodes.
The bridge. Every channel the preload script calls has a handler on the other side, and the renderer never gets require or process.

The presets live in one file, src/shared/presets.js, which the interface imports and the tests import too. A test of the Web preset reads the real preset, not a copy of its numbers, so changing a value there changes what gets tested.

Version 2.1 adds the command line to that list. The social presets behind its new --social flag come from the same file, and a saved profile goes through the same code in the app and in the CLI, with a test that checks both give the same image.

Fixtures built to make mistakes visible

None of the test images are photos. They're generated by code before the tests run, and each one exists to make one kind of mistake impossible to miss:

Fixture	What it is	What it catches
`asym-h`, `asym-v`	Half red, half blue	A flip that doesn't swap the halves
`quadrants`	A different colour in each quarter	Where a watermark, or now a crop, actually landed
`gray120`	Flat grey, 120 on every channel	Brightness, contrast and saturation as one measurable number
`alpha`	Semi-transparent green	Transparency lost where it should survive
`corrupt`	A sentence of text saved as `.jpg`	A broken file that takes the batch down with it
`noise`	Random pixels from a fixed seed	A "photo" that is identical on every run
`high-freq`	One-pixel black and white stripes	Only two colours, maximum detail: the case that got past the colour-only SVG guard

quadrants is the workhorse. Simplified, it's this:

// 80×60, a unique colour in each quarter: a test can tell exactly which
// corner or area an operation touched.
for (let y = 0; y < 60; y++) {
  for (let x = 0; x < 80; x++) {
    const i = (y * 80 + x) * 3
    const top = y < 30, left = x < 40
    const [r, g, b] =
      top && left ? [255, 0, 0]   // NW red
      : top       ? [0, 255, 0]   // NE green
      : left      ? [0, 0, 255]   // SW blue
      :             [255, 255, 0] // SE yellow
    buf[i] = r; buf[i + 1] = g; buf[i + 2] = b
  }
}
await sharp(buf, { raw: { width: 80, height: 60, channels: 3 } }).png().toFile(quadrantsPath)

Checking pixels without golden images

The tempting way to test an image pipeline is golden files: save a known-good output, then compare every new output against it byte for byte. It breaks every time the encoder changes how it rounds something, and when it breaks it tells you nothing about what is wrong.

So the suite asks narrower questions, each one with an answer that can't be in doubt:

Dimensions and ratio, exactly.
A pixel whose colour is certain. Flip asym-h horizontally and the pixel in the top-left corner must now be blue.
A region that should, or shouldn't, change. A watermark in the south-east has to change that corner of quadrants and leave the opposite one alone, measured as a difference over the region against a threshold, not as an exact match.
Exact equality only where it's promised. A lossless round trip has to give back identical pixels, because that is the entire promise of lossless.
Order instead of value, where exact numbers would be brittle. A higher quality has to land closer to the original than a lower one, and the Min size preset has to spend fewer bytes per pixel than High quality.

Most of it comes down to a helper this small:

async function readPixel(filePath, x, y) {
  const { data, info } = await sharp(filePath).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
  const cx = Math.min(Math.max(0, x), info.width - 1)
  const cy = Math.min(Math.max(0, y), info.height - 1)
  const i = (cy * info.width + cx) * 4
  return [data[i], data[i + 1], data[i + 2], data[i + 3]]
}

For crop, quadrants gets one more job. Crop it from 80×60 to a 60×60 square and the border between red and green tells you where the crop happened without anyone looking at the result. Anchored in the centre, the border lands at x = 30. Anchored left, at x = 40. Anchored right, at x = 20. Three pixel reads per anchor, and no image ever opened.

The crop test list

Before the crop was anywhere near done, I wrote down what it has to survive:

A phone photo stored sideways is upright before anything gets cropped.
The original survives. Always.
Every preset gives its exact ratio, for landscape, portrait and square inputs, and for an input that already matches.
The anchor lands where it says, read off quadrants.
Padding saved as JPG is the colour that was asked for, not black.
Transparency survives wherever the format supports it.
Rotation happens before the crop and the watermark after it, so a corner watermark is still there.
Small inputs are enlarged only when a final size asks for it, and the preview says so when they are.

The first two were supposed to be formalities. They're the two that failed.

Failure one: phone photos come out sideways

Many phone photos aren't stored the way you see them. The camera writes the pixels in one orientation and adds an EXIF tag saying how to turn them. To test that, I needed a photo like that, and none of the fixtures was one: every fixture is generated from raw pixels, and code doesn't hold the phone sideways.

So I made one. Stored as 200×100, red on the left and blue on the right, with orientation 6, which means "rotate 90° clockwise to display". Seen properly, it's a 100×200 portrait with red on top.

test('a photo stored sideways comes out upright', async () => {
  const red = await sharp({ create: { width: 100, height: 100, channels: 3, background: '#ff0000' } }).png().toBuffer()
  await sharp({ create: { width: 200, height: 100, channels: 3, background: '#0000ff' } })
    .composite([{ input: red, left: 0, top: 0 }])
    .withMetadata({ orientation: 6 })
    .jpeg()
    .toFile(phonePhoto)

  const result = await convertToFormat(phonePhoto, out, { outputFormat: 'webp' })
  const meta = await sharp(result.outputPath).metadata()

  assert.equal(meta.width, 100)   // fails: 200
  assert.equal(meta.height, 200)  // fails: 100
})

It failed with no crop involved at all. Convertim 2.0 writes it out at 200×100, without the tag. The engine never turns the image upright, and since it doesn't keep the metadata either, the tag that would have told a viewer how to turn it is gone too. A plain conversion, a resize: a photo stored sideways comes out sideways.

Crop only turns that from annoying into destructive. A sideways photo can be rotated back. A sideways photo cropped to 4:5 has already lost the wrong part of itself.

The fix turned out to be small. sharp 0.34 has autoOrient(), and in 2.1 it goes first in every path that reads an image (conversion, optimisation, vectorisation and the previews), always before the user's own rotation. The part that needed care was everything that measured the image: in 0.34, metadata() still reports the stored size, and the oriented size comes separately, in metadata().autoOrient. Every resize, every crop and every watermark is now computed from the second:

function getVisibleSize(metadata, transforms = {}) {
  const oriented = metadata.autoOrient || metadata
  const quarterTurn = transforms.rotation === 90 || transforms.rotation === 270
  return quarterTurn
    ? { width: oriented.height, height: oriented.width }
    : { width: oriented.width, height: oriented.height }
}

The test above is in the suite now, along with one for every other orientation value a camera can write.

Failure two: "never overwrite" had a gap

Convertim has one rule I considered unbreakable: it never writes over a file. If photo.webp already exists, the output becomes photo_1.webp. Crop makes that rule matter more, because a cropped image is missing pixels for good, and the original is the only copy of them.

The test for it had one thing none of the old tests had: two files with the same name, converted at the same time.

test('two inputs with the same name never share an output', async () => {
  const [a, b] = await Promise.all([
    convertToFormat(join(dir, 'photo.jpg'), dir, { outputFormat: 'webp' }),
    convertToFormat(join(dir, 'photo.png'), dir, { outputFormat: 'webp' }),
  ])
  assert.notEqual(a.outputPath, b.outputPath)   // fails: both are photo.webp
})

Both conversions chose photo.webp, and the second one wrote over the first. Every single time I ran it.

The name check and the write are far apart. The engine looks for a free name when a conversion starts, and the file only appears on disk when the encode finishes. In between, another conversion has time to look, see the same free name and take it too. The CLI converts one file at a time, so it never hits this. The desktop app runs several in parallel (half your CPU cores, by default), and its default output folder is the source folder, so photo.jpg and photo.png side by side are enough.

On its own, that costs one output. With Delete originals turned on, both originals are deleted after two "successful" conversions, and one of the two images is gone.

If you are still on 2.0, update. Until you do, set the concurrency to 1, or don't use Delete originals on a batch where names repeat.

The fix is in 2.1. The name is reserved in the same step that checks it: the output file is created empty and exclusively, with Node's 'wx' flag, which fails if the file already exists. If it does, the conversion moves on to the next suffix.

function reserveOutputPath(filePath) {
  const dir = path.dirname(filePath)
  const ext = path.extname(filePath)
  const base = path.basename(filePath, ext)
  for (let counter = 0; ; counter++) {
    const candidate = counter === 0 ? filePath : path.join(dir, `${base}_${counter}${ext}`)
    try {
      fs.closeSync(fs.openSync(candidate, 'wx'))
      return candidate
    } catch (e) {
      if (e.code !== 'EEXIST') throw e
    }
  }
}

The encoder then writes over its own reservation, and removes it if the encode fails. Behind that there's a second safety net: an original is only deleted if its output is on disk with exactly the size that conversion wrote.

Why two hundred tests never saw either

Neither bug was subtle once a test went looking for it. They survived because of what the fixtures were.

Every fixture is generated from raw pixels, so none of them carries metadata. Every test writes into its own fresh folder and converts one thing at a time. That makes the suite fast, reproducible and independent, which is exactly what a suite should be. It also means it lived in a world with no cameras and no two files with the same name.

Generated fixtures test the code you wrote. Real files bring the world with them: the tag a phone added, the folder where someone exported the same picture twice. Both bugs lived in the gap between the two.

So the list has a third kind of input now, next to the generated fixtures and the real files: generated ones that imitate what real files do, not only what their pixels look like. Orientation tags, repeated names, conversions that overlap.

What isn't automated

Some things are still checked by eye, on purpose. Before every release there's a manual checklist, around five hundred lines long, run against a folder of real files the generated fixtures can't imitate: a JPG over 5 MB, an animated GIF, a JPG truncated with a hex editor, a filename with spaces, an ñ and an emoji, and folders nested three deep.

For crop, that folder grows: real portraits, real landscapes, screenshots and logos on transparent backgrounds, run through every preset and looked at as a grid of thumbnails. It's the only test that can answer the one question the automated ones can't: does the default look right?

Done means it fails predictably

A batch feature isn't done when it works on one image, or even on two hundred clean ones. It's done when it fails predictably: when the two hundredth image behaves like the first, when a broken file fails on its own and the rest of the batch carries on, when two files with the same name can never become one, and when the worst a bad default can do is something you notice in a grid of thumbnails, not something you discover after posting.

Both fixes shipped in 2.1 on Monday, and both are tests now, so neither can come back unnoticed. They went out with the rest of the list, once running it had become boring. That was the whole release plan.

Crop or Pad? Designing Fixed Aspect Ratios for Batch Image Conversion

Christian • ancer — Wed, 21 Oct 2026 08:00:00 +0000

Convertim, the image converter I build, can already turn a 4:3 photo into a 1080×1350 image. It does it by stretching the photo until it fits.

That's its Force dimensions mode: exact width, exact height, aspect ratio ignored. Under the hood it's sharp's fit: 'fill'. It does exactly what it says, and for a photo it's the worst of the three possible answers. The other two are what I'm working on now: cropping to fixed ratios, and padding to them.

Convertim is a portable Windows image converter: a desktop app and a CLI on top of the same engine, built on sharp (libvips), running entirely on your machine. Its whole point is batches. Drop two hundred files, pick a format, go. That single fact changes how crop has to be designed, and almost none of the hard decisions turned out to be technical.

I'm writing this while building it. Most of it is decided now, and I'll say why. What isn't settled yet is whether those decisions survive a few hundred real images.

Fixed ratios, not a crop handle

The first decision was what not to build: a freeform crop, with a rectangle you drag over each image.

Freeform crop is one decision per image. That's perfect for one photo, and it's what a photo editor is for. Convertim is built for two hundred at a time, and two hundred drag handles is not a feature, it's an afternoon.

So crop in Convertim means fixed aspect ratios, chosen once for the whole batch: eleven common ones, from 1:1, 4:5 and 9:16 to 16:9 and 3:1, plus a custom one anywhere between 1:10 and 10:1. One rule, applied to everything. Presets by destination come on top: pick where the image is going (an Instagram portrait, a story, a YouTube thumbnail, a LinkedIn banner) and get the exact size and ratio. They're built on the same rule.

Every ratio change costs the same

When an image doesn't match the target ratio, there are only two honest answers:

Crop what sticks out. The frame is full, and some pixels are gone.
Pad what's missing. Every pixel survives, and part of the frame is filler.

What I didn't expect is that they cost exactly the same. Turning a 4000×3000 photo (4:3) into 4:5, at its own resolution:

	Crop	Pad
Result	2400×3000	4000×5000
Cost	40% of the pixels, thrown away	40% of the canvas, filler

It isn't a coincidence. The fraction you lose by cropping is always the fraction you fill by padding: one minus the smaller aspect ratio divided by the larger. A 16:9 video frame turned into a 9:16 story costs 68%, whichever way you do it.

So the question is never which one is cheaper. It's whether you would rather pay in lost pixels or in filler, and that depends on the image, which is exactly what a batch doesn't let you look at.

Where to anchor the crop

Crop has a second question hiding inside it: which part to keep. sharp's cover takes a position, and the answers come in three families:

// Same image, same 4:5 box, three different results.
sharp(input).resize({ width: 1080, height: 1350, fit: 'cover', position: 'centre' })
sharp(input).resize({ width: 1080, height: 1350, fit: 'cover', position: 'north' })
sharp(input).resize({ width: 1080, height: 1350, fit: 'cover', position: sharp.strategy.attention })

Centre is the predictable one. It's also the one that cuts the top of someone's head when a portrait is cropped to a wider ratio, because in most portraits the face sits in the upper half of the frame.
Top (north) protects the heads. It only does anything when the crop removes height; when it removes width, it behaves exactly like centre. And it fails on anything whose subject sits low in the frame.
Content-aware strategies look at the pixels. entropy keeps the busiest region; attention looks for luminance frequency, colour saturation and skin tones. On average they often do better than either of the others.

That "on average" is the problem. In a batch, the anchor doesn't need to be clever, it needs to be predictable. With centre or top, someone can picture what will happen to the whole batch before pressing the button. With attention, the only way to know where image 137 was cropped is to open image 137, and saving you from opening every image is the reason a batch tool exists.

So the default is centre, and the anchor is a 3×3 grid: the centre, the four edges and the four corners. Content-aware crop is there too, as Smart crop, but it's a checkbox that starts unticked, with a short note right next to it. It works well with one clear subject on a simple background, with a subject that has more colour or contrast than its surroundings, and with portraits, because it weighs skin tones. It can fail with busy backgrounds like foliage or crowds, with several subjects spread across the image, and with a dull subject on a louder background. It doesn't recognise faces or objects: it follows colour, contrast and skin tones. Ticking it is a choice to trade predictability for a better average, and the note is there so that it's an informed one.

What to pad with

Padding has its own question: what goes in the gap?

For formats with an alpha channel (PNG, WebP, AVIF), transparency looks like the obvious answer. The image stays exactly what it was, and the frame around it is nothing. It's one of the options, but not the default: the default is a solid colour, white, for every format, so the same batch gets the same frame whether it comes out as PNG or as JPG.

JPG has no alpha channel, and this is where sharp surprised me. Pad with a transparent background, save as JPG, and the padding comes out black. Not the colour you asked for: pad with transparent white and you still get black, because the colour of a fully transparent pixel doesn't survive the trip.

The obvious fix doesn't work either:

// Looks right, and isn't: the padding is still black in the JPG.
await sharp(input)
  .resize({ width: 1080, height: 1350, fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
  .flatten({ background: '#ffffff' })
  .jpeg()
  .toFile(output)

sharp flattens the alpha before it resizes, whatever order the calls are written in, so flatten never sees the padding that contain adds afterwards. It does flatten the transparency that was already in the input; it just can't reach the gap. What works is deciding the colour before the padding exists:

// Without an alpha channel, the gap needs a solid colour from the start.
const background = supportsAlpha(format)
  ? { r: 0, g: 0, b: 0, alpha: 0 }
  : '#ffffff'

await sharp(input)
  .resize({ width: 1080, height: 1350, fit: 'contain', background })
  .toFormat(format)
  .toFile(output)

With that in place, transparent padding saved as JPG comes out white, not black, and a colour pad is the background of the whole frame: the image's own transparency is flattened onto that colour too, not only the bands around it.

And it isn't only a padding question: a transparent PNG converted to JPG faces the same choice, crop or no crop. In Convertim 2.0 it came out on black. In the update it's flattened onto white.

Besides a colour and transparency, there's a third option: blur. The gap is filled with the image itself, scaled up to cover the whole frame and heavily blurred, with the full image on top. It's the usual way to turn a landscape photo into a 9:16 story without colour bars. The blur runs on a copy at an eighth of the final size, which is then scaled back up: it looks like a huge blur at full size and costs a fraction of one.

The order of operations

Then there's where crop goes in the pipeline. In Convertim 2.0 the pipeline was written in this order: the user's rotation and flips, colour adjustments, resize, watermark, encode. Crop changes what has to come before what:

Orientation. A phone photo stored sideways, with an EXIF tag saying which way is up, has to be turned upright before anything measures it. Skip that, and the app measures a portrait as a landscape and crops the wrong side. (Testing this turned up something I'll write about next week.)
The user's rotation. Crop to 4:5 and then rotate 90°, and you've made a 5:4.
Crop or pad, and resize. In sharp they're one operation: cover scales until the box is full and cuts the rest, contain scales until the image fits and fills the rest.
Watermark. After the crop, never before. A watermark in a corner is exactly what a crop removes first, and its size is computed from the final dimensions, so it has to wait for them anyway.
Encode, with the padding colour already decided.

That's the order it runs in now, in a single pipeline shared by conversion, optimisation and the preview, so the preview shows exactly what will be written.

The trap is that a sharp chain isn't a script. Some operations run in a fixed internal order, whatever order you call them in. In the version Convertim uses (0.34), a 90° rotate() runs before the resize even if you chain it after, and so does flatten(), which is the JPG trap above. extract(), sharp's manual crop, is the exception: it runs where you put it.

So the order of operations isn't something I trust from reading the code. It's something to test, by checking the output dimensions and where the pixels ended up. More on that next week too.

Small images

One more decision that looks technical and isn't: what happens when the input is smaller than the destination? A 640×480 photo going into a 1080×1350 preset.

sharp enlarges by default, so cover scales it up and crops, and you get a soft 1080×1350. Convertim's existing quality presets already behave like that: the Web preset takes a 400-pixel-wide image up to 1200, and there's a test checking that it does.

The alternative, withoutEnlargement, has a surprise when combined with cover: a small image comes back untouched. Not cropped, not padded, just its original size in its original ratio. So "never upscale" and "always 4:5" can't both win. If a preset promises a ratio, either the image gets enlarged, or the crop happens at the image's own resolution and the preset only ever shrinks.

Convertim does both, depending on what you ask for. A ratio without a final size scales nothing: crop keeps the largest box of that ratio inside the image, and pad builds the smallest canvas that holds it (up to 16,383 pixels a side, WebP's limit). A final size, or a social preset, which always has one, is a promise of exact pixels, so the image is scaled to it, up if it has to be, and the preview says when an image is being enlarged.

The default is the product

On a single image, a bad crop costs two seconds: you see it, you undo it, you move on. In a batch, nobody sees it. Two hundred images go in, two hundred come out, and the first time anyone looks closely at number 137 might be after it's been posted.

That's why the default deserves more time than the crop itself. The crop is a handful of sharp options. The default is a decision applied two hundred times without anyone looking, and it's what most people will get, because most people never change a default.

Here's where things stand:

Decided: fixed ratios, no freeform crop, one rule per batch. Orientation and rotation before the crop, the watermark after it. A solid padding colour whenever the format has no alpha channel.
The defaults: crop, anchored in the centre, with smart crop as an opt-in. White padding for every format, with transparency and blur as options. No scaling without a final size; with one, the image is enlarged if it has to be, and the preview says so.
Still to prove: that those defaults hold up on a few hundred real images.

Every one of those defaults went through the same three questions. Which failure is easier to spot in a grid of two hundred thumbnails? Which failure leaves the whole image in the output, and which one doesn't? And can someone predict the result for the entire batch before pressing the button? Centre and white are the answers anyone can predict before pressing it. But a question answered in the abstract isn't answered yet. These are the defaults going into testing, not a promise: if a few hundred real images say otherwise, they change.

In a batch tool, the default isn't a detail of the feature. It is the feature, for everyone who drops the files, presses the button and never opens the options. That's why this part gets more time than the crop itself, and why crop doesn't ship until the defaults have been argued with real images. No date yet.

Next week: the test images I use to break this before anyone else does.

Shipping Desktop Software to People Who Will Never Read the Docs

Christian • ancer — Wed, 14 Oct 2026 08:00:00 +0000

Rueda de Actos has a README. It's long, half technical documentation and half user manual, and it's accurate: the data model, every feature, where the backups live, what to do after a bad close.

Nobody who uses the app will ever read it.

That isn't a complaint about users. It's the most important design constraint the app has, and it took me two versions to treat it as one.

Rueda de Actos is the Windows desktop app I built for a festival group in Alcoy, Spain: five events, eleven spots each, and a rotating turn that has to stay fair year after year. The person who runs it is a volunteer on the group's board. They aren't technical, they open the app once a year, and on the night that matters there's no store to reinstall from, no support line and nobody to call. For most of the year I'm not in the room.

So every instruction that matters has to be somewhere they'll actually look, at the moment they need it. This is the last article in the series about this app, and it's about the unglamorous part: getting software into the hands of people who will never read the docs, and keeping it working there.

Before the app exists: the installer

The first moment is the only one where the app can't speak for itself, because it isn't running yet.

The installer is a standard Windows setup wizard, in Spanish, the language of the people who use it. And it isn't code-signed, so the first time it runs, Windows shows a blue warning: Windows protected your PC. The button that runs it anyway is hidden behind a More info link.

I went through the economics of a signing certificate in an earlier article. What matters here is what that screen does to someone who isn't technical. It reads as "this is a virus", and the software has failed before it has opened.

Nothing inside the app can fix that. So the explanation travels with the file: before anyone double-clicks, the person who will install it is told that a blue warning is coming and exactly which two things to press, in the words Windows will show them, Más información and then Ejecutar de todas formas.

The difference is all in the timing. A warning you didn't mention looks like a problem. A warning you predicted looks like proof that the instructions were right, and that buys trust for everything that comes after.

The first screen: an empty state that says what to do

The database is created empty. There's no demo data and no sample list. An earlier build seeded the table from a bundled file, and it turned out to fire whenever the table was empty, not only on the first run, so it went.

An empty table is a dead end, though. A grid of headers with nothing under it doesn't tell you what to do next. So when there's nobody in the list, the table isn't shown at all. In its place, translated from Spanish:

No members yet

Load the full list with Import, in the header, or add them one by one with Add member.

The event buttons stay disabled until there's someone to choose from. In an earlier build they didn't, and starting an event on an empty list produced empty backups and blocked the rota.

An empty state is the first page of the manual, and it's the only page that's guaranteed to be read.

Getting the data in: their spreadsheet, and errors that name the row

Every association already has a spreadsheet. The alternative to importing it is typing everyone in by hand, which is how a tool dies before its first use.

So Import takes the spreadsheet the group already had, Excel or JSON, with a single condition: the first row holds the headers, and one of them is Nombre. Headers are matched with or without accents, by their visible or internal name, abbreviations are accepted, and columns the app doesn't know are ignored. The details of that leniency are in the September article on real use.

What matters for people who won't read the docs is what happens when the file is wrong. If any record fails validation, the whole import is rejected, the data already in the app isn't touched, and the message says how many records failed and which rows, with the reason for each.

All or nothing is deliberate. A failed import is obvious. A half-done import looks exactly like a list, and nobody counts the rows to check that they all arrived.

And then the step that would be in bold in any manual: after importing, you have to press Save. Which brings me to the one rule in this app that has to be impossible to miss.

One button that makes it real

The data model is strict on purpose. The app always starts from the last saved state, and Save is the only thing that commits anything. Closing without saving is a clean undo of the whole evening, which is exactly what you want after a session that went sideways.

A rule like that is invisible unless the interface shows it, so it shows it all the time. The status bar along the bottom always says one of two things, Saved or Unsaved changes, and hovering the second one tells you to press Save. The comment above that element is the whole argument:

<!-- What isn't saved is lost on close, so the state has to be on screen at
     all times, not just in the exit warning. -->

The exit warning exists too. Closing with something pending asks first, with three buttons: Save and exit, Exit without saving, Cancel. Clicking outside doesn't dismiss it. And if saving fails, the app stays open:

// If Save fails, we don't carry on: that would be exactly the case where it hurts most.
if (result.isConfirmed) return guardarDatos()
return result.isDenied === true

For the close that happens anyway (the wrong button, a flat battery, someone tidying up the cables), there's an escape hatch: Settings → Data management → Load temporary version (session) brings back the last thing that was on screen, saved or not, with the date of each version next to it.

None of that is documentation in the usual sense. But the status bar, the three buttons and the recovery option explain the data model better than any paragraph could, and they do it at the only moments the user is thinking about it.

Backups that live on the same disk

The app backs itself up: a full copy of the database every thirty minutes, keeping the last ten. It's a real safety net, for one specific failure: I've just broken the data.

It does nothing for the other one, the laptop died, because those copies sit on the same disk as the original. I said that in the offline-first article, and it bears repeating, because automatic backups are exactly the kind of feature that makes people stop worrying, and this is the one case where they should keep worrying.

What actually protects the group's history is an export saved somewhere else: a USB stick, an external drive, an email. JSON and Excel both re-import without losing anything, so with that file a brand-new installation gets everything back through the same Import as on the first day.

The trouble is that nobody thinks about this until it's too late, and nobody reads the paragraph telling them to. So the export sits where the data is worth the most. The final summary, the screen that appears when the fifth event closes, has the export buttons on it, and the highlighted one is the JSON export. At that moment the evening's work is done, someone is still at the keyboard, and a copy is one click away.

Updating without losing a year

The database doesn't live next to the program. It's in the user's Windows profile, so installing a new version over the old one never touches it. What does change is its shape, and the database a new version finds is, by design, a year old.

So the schema is versioned. Every change to it ships as a migration that runs on first launch, each one inside a transaction, so a failure stops the chain instead of leaving the database half converted. The migrations that move existing data have their own tests, because the database they will meet on that machine is the real one, with years of history and no copy on any server. I wrote about how those tests work in the testing article.

From the user's side, all of that has to collapse into a sentence they already believe without being told: the new version keeps my data.

A year later: the guide

The hardest user to design for is the same person, twelve months later. They used the app once, last year, and have forgotten all of it: where Import is, what the amber card means, why some cells are striped.

For that person, the app carries its own guide, one click away inside the app: nineteen short numbered sections, from managing members and choosing people for an event to verifying or skipping, reopening, the gender rules, squad leaders, search, saving and recovering, export and import, the final summary and how windows and notices behave.

A few rules make it usable rather than merely complete:

It uses the screen's words. Every button is named exactly as it appears, in bold, and every path is the real one: Settings → Data management → Load temporary version (session).
Each section is a handful of short sentences. Nobody reads a guide from the top. People scan it for the one thing they're stuck on.
It changes with the app. When version 2 added search, reopening and the new event states, the guide grew in the same release. A feature isn't finished until its section is written.

A guide inside the app has one advantage over every other kind of documentation: it's the only one guaranteed to still be there, on the right machine, a year from now.

The interface is the documentation

Look at where the instructions in this app actually live: a heads-up that travels with the installer, an empty state, an error that names the rows, a status bar, a dialog with three buttons, the export buttons on the last screen of the night, and a guide written in the words of the screen.

That's the documentation. For someone who isn't technical, the documentation that exists is the interface itself. Everything else, the README, the FAQ, this article, gets read by people who no longer need it.

This is the last article I'll write about Rueda de Actos for a while. The case study, with screenshots made from test data, is on my site: ancer.es/en/project/rueda-ligeros.

What Happened When My App Finally Met the Room

Christian • ancer — Wed, 07 Oct 2026 08:00:00 +0000

Last Friday, the app I have spent most of this year on did the one job it exists for.

It is called Rueda de Actos, a Windows desktop app for the Filà Ligeros, one of the groups that take part in the Moros y Cristianos festival in Alcoy, Spain. Once a year it hands out participation in five festival events, eleven spots each, following a rotating turn that has to stay fair from one year to the next. It does it in a single session, in a room, projected on a wall, in front of the people whose names are in the table.

Version 1 had that session last year. It took about three hours, and I came home with a notebook full of things to fix. In September I wrote about what that notebook turned into, about designing for a projected screen and about testing for one shot a year. This is the other half: what happened when version 2 met the same room.

The short version: it worked from start to finish, the session took under an hour, and the notebook has two lines in it.

Same chair, same rule

I did exactly what I did last year. I sat in the room, I kept my hands off the keyboard, and I wrote down every hesitation: every pause before a click, every time the person driving went back on something they had just done, every question from the room that the screen could not answer.

I don't ask for feedback afterwards. Asking gets you opinions about the app in the abstract. Watching gets you the gap between what someone expected to happen and what happened, and that gap is the only thing worth writing down.

Last year the notebook ended up with fifteen items. Most of them became version 2.

Under an hour

Last year's session took about three hours. This one took under an hour.

I am not going to claim all of that for the software. Part of it is a room that had already done this once with an app on the wall, and knew what was coming. But part of it is visible in what actually got used, and the most interesting thing about that list is where it came from.

What got used

Verification at eleven. Every time an event reached eleven people, the app stopped and opened the verification window: the eleven names, a checkbox for squad leaders, and a way to take someone out before closing. That window is the moment the room checks the app, not the other way around.

The search box. Last year, the single most repeated moment of the evening was somebody scrolling a table of nearly a hundred rows looking for a name while everyone waited. This year, when someone needed a name, it got typed instead of hunted.

An event that didn't get its eleven. Not every event fills. In version 1, an event that closed short looked exactly like a full one: five identical green cards. This year the card went amber and said what had happened, and that is what next year's turn will read.

A verified event, corrected. At some point, an event that had already been verified needed different people in it. Last year, the only tool for that would have erased every event played afterwards, so the correction went onto paper, and from that moment the paper was the record, not the app. This year the event was reopened, corrected and verified again, and the app stayed the record of what happened.

Three of those four (the search box, the amber card and the reopen) exist because of last year's notebook. None of them was in the rules I was given when I built version 1. That is still the strongest argument I know for shipping something incomplete and then watching it being used.

What nobody noticed

Most of what I wrote about in September never came up.

Cells blocked by unpaid dues or penalties don't say why, so the room sees that a rule was applied without learning anything private about anyone. Dialogs can be dragged out of the way. Notices that need no answer slide into a corner and leave on their own, and only the ones that change the table under everyone's eyes take the whole screen.

There is not a single line in the notebook about any of it. For that kind of design, that is the result you want. Privacy that works is invisible. A notice that doesn't interrupt is one nobody remembers. If any of those decisions had been wrong, they would have been wrong in public, in front of exactly the people they affect, and they would have been the first thing I wrote down.

The two lines

This is the whole notebook for this year:

Moving between cells, and marking or unmarking them, from the keyboard instead of double-clicking.
A scroll that adjusts itself.

Compare that with last year. Version 1's notes were about things the app could not do: correct a mistake without losing work, tell a full event from an incomplete one, get the group's data in without me. Those were missing capabilities. This year's two lines are about something else entirely: the hands of the person driving.

That is what a second round looks like, I think. You only notice how many times someone reaches for the mouse once nobody is waiting for you to fix something bigger. Double-clicking works. It is also the slowest way to walk down a list, aim at a cell on a projected table and do it again, with a room watching each move.

What goes into the next version

Both lines are already built, and they go out with the next version.

The table is now a single Tab stop. Inside it, the arrow keys move between rows, Home and End jump to the first and the last, and the space bar marks or unmarks the person in the event in progress. The part I cared about most is that the keyboard doesn't get its own logic:

// The row the keyboard is on. It goes by position, like the rows' `key`: when an
// event closes and the rota moves people to the back of the queue, focus stays
// where it was on the table instead of chasing the person to the bottom.
const filaActiva = ref(0)

function onTeclaFila(e: KeyboardEvent, idx: number) {
  if (e.altKey || e.ctrlKey || e.metaKey || hayModalAbierto()) return

  if (TECLAS_NAVEGACION.includes(e.key)) {   // arrows, Home, End
    e.preventDefault()
    enfocarFila(destinoDe(e.key, idx))
    return
  }

  // Space on the row's edit button belongs to the button.
  if (e.key !== ' ' || e.target !== e.currentTarget) return
  e.preventDefault()
  // Holding it down can't keep marking and unmarking the same person.
  if (e.repeat || !columnaActual.value) return
  // Exactly what a double-click on the current event's cell does, blocks included.
  onCeldaDblClick(idx, columnaActual.value)
}

The space bar calls the same function as the double-click. Every rule that blocks a cell (dues, penalties, the gender of the squad, not repeating an event) applies to both, because there is only one path. A second path would have been a second place for those rules to drift apart, and on this app a rule that drifts doesn't throw an error. It produces a plausible, unfair result.

Focus going by position is the other detail that only makes sense in this room. Closing an event rotates the queue: everyone who took part moves to the back. If focus followed the person, it would jump to the bottom of the table every time an event closed, and the operator would lose their place in front of everyone.

The scroll is a single line once the row has focus:

fila.focus({ preventScroll: true })
// Centred in the visible area: once the row passes the middle of the screen, the
// table scrolls to keep it there. At the very top and bottom there's nothing to
// centre against, and the scroll stops at the edge, which is what you want.
fila.scrollIntoView({ block: 'center' })

And one guard that only makes sense in front of a room:

// With a dialog open, the table ignores the keyboard. The dialog doesn't trap
// focus, so Tab can end up on a row behind it, and the space bar would change
// the selection without anyone seeing it.
function hayModalAbierto(): boolean {
  return document.body.classList.contains('modal-open')
}

A change nobody can see is the worst kind of change in front of a room. The table simply stops listening while something is covering it.

What stays out

Nothing in the notebook argues for the things I said no to last month. Not a second person editing at the same time, not cloud sync, not a configurable number of events and spots, not a general undo. One person drove, in one room, and the outcome counted because everyone watched it happen. None of those features would have made that hour better, and most of them would have made it different.

The temptation after a good night is to read it as permission to add things. I am reading it the other way: the notebook is the spec, and the spec got shorter.

The only metric

Software that runs once a year has no analytics worth the name. No retention curve, no error tracking, no release every week. The night is the whole feedback loop, and whatever you learn in that room is all the feedback you get until the next one.

So the only measure I really trust is the length of the notebook. Last year: fifteen items, pages of them. This year: two lines. Next year I will sit in the same chair, with the same notebook, and keep my hands off the same keyboard. A blank page is the goal. I don't expect to get it.

The full case study, with screenshots made from test data, is on my site: https://ancer.es/en/project/rueda-ligeros.

Testing When You Only Get One Shot a Year

Christian • ancer — Wed, 30 Sep 2026 09:00:00 +0000

Most software gets a second chance. A bad deploy on Tuesday is fixed by Wednesday morning, and by Friday nobody remembers it happened. That safety net is so ordinary that it disappears from the way we talk about quality: we argue about coverage percentages because, underneath, we assume anything we miss can be corrected later.

I spent the last months on an app where that assumption is false, and it changed how I decide what to test.

The deployment model is the requirement

Rueda de Actos is a Windows desktop app I built for a filà, one of the associations that take part in the Moros y Cristianos festivities in Alcoy, Spain. Once a year the board sits down and hands out the spots for five acts, eleven places each, following a rotation that decides who takes part and who waits another year.

That session is the entire product. It happens once. It happens live, with the screen projected in front of the room. And it happens on a machine that is not connected to anything.

Three properties fall out of that:

No network. The app never opens an outbound connection. Everything lives in a local SQLite file inside the user's Windows profile.
No auto-update. There is no update channel to check, because there is no network. A new version means someone runs a new installer over the old one.
One live run per year. Between two real sessions there are twelve months, and I am not in the room for eleven and a half of them.

Together they remove the thing every web developer leans on without noticing: I cannot ship a fix before it matters. The build installed on that machine is the build that runs. By the time anyone notices a problem, the decision it affected has already been made, out loud, in front of the people it affects.

Coverage percentage is the wrong question

The question I actually needed to answer was not how much of this is covered. It was:

If this path is wrong, when do we find out, and what does it cost to fix it then?

That splits the codebase into three groups.

Wrong and obvious immediately. The user sees it, retries, moves on. Cheap. A test here buys very little.
Wrong and obvious later, with the data still intact. Annoying, recoverable, worth some tests.
Wrong and plausible. No error, no crash, nothing red anywhere. The app produces a result that looks exactly like a correct result and isn't. Or data quietly stops existing.

Roughly 400 tests, and almost all of them live in the third group.

Where the tests actually are

1. The rotation

This is the critical one, and it is critical precisely because it never fails loudly.

If the wheel logic is wrong, nothing throws. The screen shows eleven names per act, correctly formatted, in a table that looks right. What has actually happened is that somebody was skipped, or got a second turn before someone else got a first. Nobody sees a stack trace. Someone notices months later that they have been left out two years running, and at that point the damage is social, not technical. In a volunteer association, fairness is the entire reason this software exists.

So the rotation is not tested as a function with a known return value. It is tested as a set of invariants over simulated years:

// simplified
it('never grants a second turn before everyone has had a first', () => {
  let wheel = newWheel(makeMembers(40))

  for (let year = 0; year < 5; year++) {
    const assigned = runYear(wheel)      // 5 acts, 11 places each
    wheel = advance(wheel, assigned)
  }

  expect(maxTurns(wheel) - minTurns(wheel)).toBeLessThanOrEqual(1)
})

The valuable tests here run the wheel across several years and then assert a property of the outcome, never an exact list of names. Exact-list assertions break the moment a rule changes, and they teach you nothing when they do. Invariants survive rule changes, which is the whole point: they encode what fairness means, not what the current implementation happens to produce.

The same style covers the awkward cases that real use produced. Skipping an act must not advance anyone's turn. Closing an act half full must not pretend it was complete. Reopening a closed act to correct a mistake must leave the queue exactly as it would have been had the correction been made the first time.

2. The rules that block a spot

Gender rules for squads, payment status, sanctions, licence validity, and the rule against repeating an act you already did in a previous year. On top of that, three configuration switches that each turn one of those rules off, because different associations work differently.

They interact, so they are tested as a matrix rather than one by one. A member can be eligible under the gender rule and blocked by the licence, or blocked by both, or unblocked by a switch that only lifts one of the two.

One of these tests is not about logic at all. Payment and sanction status block a spot but must never be rendered in the projected table, because the room is watching. So there is a test asserting that the sensitive field does not appear in the table markup for a blocked member. It is a privacy requirement, and writing it as a test is what stops it being quietly undone by a future refactor of that component.

3. Schema migrations

The tests nobody applauds, and the ones I would keep if I could keep only one group.

Every year, the installed version is a year old. Upgrading means running the new installer over the previous one, and the database sitting in the user's profile is the real one, with the real history of who took part in what. There is no seed data to fall back on and no server-side copy anywhere.

So every schema version ships with a migration, and every migration ships with a test that starts from a fixture database at the previous version, migrates it, and asserts everything survived: members, years, acts, flags, corrections. Not "the migration completed without throwing", but the row counts and the row contents, plus whatever the new version adds.

Two more tests guard the edges. Migrations must be ordered and idempotent, and the app must refuse to open a database written by a newer version rather than trying its best. That last one sounds theoretical until you remember how these installers travel. Reinstalling last year's build from an old pendrive is a completely realistic accident.

4. Import and export, in both directions

The app starts empty. Real data gets in through an import from the spreadsheet the association already had, which is to say: a file a human maintained by hand, for years, with no schema in mind.

That means accents, trailing spaces, inconsistent capitalisation, blank rows in the middle, a header row that is not the first row, and a name column that might be called Nombre, NOMBRE or Nombre y apellidos. The alternative to importing that file is typing everyone in by hand, which kills a tool before it is ever used. The messy path is the main path.

Excel and JSON both work in both directions, and the tests treat that as a round trip: export the full wheel, re-import it into an empty database, assert the resulting state is identical. An export you cannot re-import is not a backup, it is a report.

The fixtures are deliberately dirty. The clean file passes on day one and never catches anything again.

5. The build itself

The suite runs on every build of the installer. The installer is not produced by hand from whatever happens to be in my working tree: an automated process builds it from source with the same pinned dependency versions the tests ran against. If the suite fails, no installer comes out.

That matters more here than in a service I can redeploy. The artefact is physically handed over. The file that reaches that machine is the last point at which anything can still be corrected, so it should not be possible for it to exist in an untested state.

It is not perfect. The installer is still unsigned, so Windows SmartScreen warns the first time it runs, and no amount of testing fixes that particular rough edge. It is a signing certificate, not a bug.

What I deliberately don't test

Visual layout. Checked by using the app, not by asserting on pixels.
Electron and SQLite themselves. They have their own test suites, written by people who know them better than I do.
Components with no logic in them. A unit test there mostly proves I typed the props twice.
Performance. Dozens of people and a handful of years of history. Nothing here will ever be slow, and a benchmark would only give me something to maintain.

None of those are unrecoverable if they are wrong. That was the only criterion.

The rule I ended up with

Test budget is finite, whatever anyone says about coverage. The way I spend it now is by asking, for every path, when a mistake would surface and what fixing it would cost at that point.

Loud failures are cheap, because the user becomes the test. Silent, plausible failures are expensive, because nothing tells you they happened, and by the time something does, the moment has passed. The rotation is the purest example I have worked on: no exception, no error state, a result that looks completely reasonable, and a consequence that arrives months later and lands on a person rather than on a log.

In a few weeks the app runs for real again, offline, on one machine, in front of a room. Feature work has already stopped. From here it is tests, polish and leaving things alone.

I will write about how it goes.

What a Year of Real Use Changed About My App

Christian • ancer — Wed, 23 Sep 2026 09:00:00 +0000

Version 1 of this app was used for real exactly once. One evening, last year, for about three hours.

I was in the room. I didn't touch the keyboard, and I only answered questions when the session would otherwise have stopped. What I did instead was write things down: every hesitation, every time the person driving it went back on something they'd just done, every question from the room that the screen couldn't answer.

That notebook is, almost line for line, the changelog of version 2.

The app is Rueda de Actos, a Windows desktop app for the Filà Ligeros — one of the groups that take part in the Moros y Cristianos festival in Alcoy, Spain. Once a year it hands out participation in five festival events, eleven slots each, following a rotating turn that has to stay fair from one year to the next. The session happens in a meeting room, projected on a wall, with the board watching.

What I deliberately didn't do was ask

I could have sent a list of questions the next morning. It would have been faster and it would have produced a worse list.

If I'd asked what's missing, I'd have got three or four reasonable answers, because that's what the question invites: a considered opinion about the app in the abstract. The list I actually came home with had fifteen items on it, and the ones that mattered most were things nobody would have volunteered — in the moment they didn't register as missing features. They registered as this is just how it is.

The notebook had two columns. What the person did, and what they seemed to expect would happen. Only the gap between those two things was worth anything. A pause before a click is a gap. Going back to fix something a different way than the app offered is a gap. Somebody in the room asking a question that the screen was already answering, badly, is a gap.

Asking gets you opinions. Watching gets you requirements.

Here's what came out of it.

1. A closed event has to be re-openable

About ninety minutes in, on the fourth of the five events, somebody noticed that a name in event two shouldn't have been there.

Version 1 had exactly one answer for this: Restore by Event, which reloads the snapshot taken just before that event was verified. It works perfectly. It also erases events three and four, which had taken forty minutes and a fair amount of discussion to settle.

So it didn't get used. The correction was written on paper and applied later. Which means that from that moment on, the app was no longer the record of what had happened — the paper was.

Reopening a single event is easy to describe and slightly more interesting to implement than it looks, because closing an event doesn't only fill cells. It rotates people. Everyone who took part moves to the back of the queue, and that rotation is the entire fairness guarantee the app exists to provide.

The obvious fix — restore each person's previous queue number — is wrong. Their old neighbours have moved on:

// Someone pulled out of a reopened event does NOT get their old num_rueda
// back: the people who did go out are no longer ahead of them, and everyone
// has moved up a place. What they get is their relative position — behind the
// first of their former predecessors who still hasn't gone out. Number 7, with
// number 3 already rotated away, comes back as 6, which is what they're owed.
lista.splice(idxActual, 1)

let destino = 0
for (let i = idxPrevio - 1; i >= 0; i--) {
  const anterior = lista.find(
    (p) => p.nombre === state.ordenPrevioReabierto[i] && !haSalidoEsteAño(p)
  )
  if (anterior) {
    destino = lista.indexOf(anterior) + 1
    break
  }
}

lista.splice(destino, 0, persona)
reasignarNumerosRueda()

ordenPrevioReabierto is just the list of names as it stood in the snapshot taken before that event closed. If the snapshot is gone, the person goes last among those who haven't been out yet — a worse placement, but the reopen still happens. Refusing to correct an error because a backup file is missing would be solving my problem, not theirs.

A year later, this is the feature I'd point at if somebody asked what watching bought me. It wasn't a missing button. It was a case where the app's only recovery mechanism was so expensive that the user quietly stopped using the app instead.

2. An event that wasn't full was showing as full

Skipping an event already existed in version 1. That wasn't the problem.

The problem was afterwards. A skipped event and one that closed with eight of eleven slots looked exactly like a full one — five identical green cards across the top, all reading as done.

That's not sloppiness in the view layer, it's information being destroyed at close time. The per-event counter gets clamped to the limit when an event is verified, because that's the flag for "played":

// Slots actually covered when each event closed; null = not closed yet.
// This needs its own record because `contadores` can't tell you: on close it
// gets pinned to the limit to mark the event as played, so a skipped event or
// one verified half-empty is indistinguishable from a full one.
plazasCubiertas: { escuadra1: null, escuadra2: null, diana1: null, diana2: null, diana3: null },

With that in place the card can tell the truth:

// Played, but without filling all 11 slots: skipped, or verified with fewer
// people. The rota carries on either way, so the card is the only place this
// is recorded.
function actoIncompleto(acto: ActoName): boolean {
  const cubiertas = appState.plazasCubiertas[acto]
  return actoFinalizado(acto)
    && cubiertas !== null
    && cubiertas < appState.limitePorColumna[acto]
}

It now goes amber and says Skipped or Incomplete, with the real count — 8/11 — and the status bar warns at the end of the rota how many closed short.

This matters more than a colour, because that history is the input to next year's turn. An event closed with eight people is not the same fact as one closed with eleven, and version 1 was quietly writing down the second when the first had happened. Reality doesn't fill every slot. Software that assumes it will ends up storing a slightly false year, then reasoning from it.

3. The spreadsheet they already had

Version 1 started from a JSON file. I know that file was fine, because I built it myself, out of their spreadsheet, on my machine.

Which is the whole problem. An app whose first screen needs a data migration performed by its developer is not a tool that group owns. It's a tool I own and let them use.

They had a spreadsheet. Every association has a spreadsheet.

So version 2 imports and exports both Excel and JSON, in both directions — and, the part that actually took the work, accepts a sheet somebody typed by hand. The only hard requirement is a column called Nombre.

Headers are matched after normalisation, and both the visible header and the internal field name are accepted:

// No accents, no case, whitespace collapsed: the header the app writes has
// accents and the one the user types may not, and "Género" and "genero" have
// to be the same column.
function normalizar(texto) {
  return String(texto == null ? '' : texto)
    .normalize('NFD')
    .replace(/\p{Diacritic}/gu, '')
    .replace(/\s+/g, ' ')
    .trim()
    .toLowerCase()
}

Values are read the same way — H/M for gender, X or Sí for a checkbox, Cad. for an expired license, because that's what people actually put in cells. But there's one decision in there I'd defend harder than the rest:

const SI = new Set(['si', 'sí', 's', 'x', 'true', 'verdadero', '1'])
const NO = new Set(['no', 'n', 'false', 'falso', '0'])

// Unrecognised values come back untouched instead of becoming "No": the main
// process validates afterwards, and it's better for the user to see what they
// typed wrong than for the app to decide for them and silently change a fact.
function aSiNo(valor) {
  const bruto = texto(valor)
  if (bruto === '') return ''
  const clave = normalizar(bruto)
  if (SI.has(clave)) return 'Sí'
  if (NO.has(clave)) return 'No'
  return bruto
}

Being lenient about input and being lenient about meaning are different things. Reading x as yes costs nothing. Reading an unrecognised value as "No" would let a lenient importer write a false fact about a person, and nobody would ever find out.

The reciprocal fix was less glamorous: in version 1 the Excel the app exported could not be imported back. It generated a file it couldn't read. Nobody had complained, because nobody had tried, but a format that only goes one way isn't an export — it's a printout.

4. Nobody types accents in front of a room

The single most repeated moment of the evening was somebody looking for a name in a table of ninety-six rows, scrolling, while the room waited.

Version 2 has a search box. The whole feature is about fifteen lines, and the only part that matters is that it doesn't ask for precision:

// The names come in from the imported file in caps and with accents, so
// without normalising, searching "jose" wouldn't find "JOSÉ".
function normalizar(texto: string): string {
  return texto.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase()
}

Two smaller decisions came from the same three seconds of watching. Results are ordered by where the match starts, so people whose name begins with what you typed come first — when you type a first name, that's who you mean, even if the same string shows up inside somebody else's surname. And the highlight is sliced out of the original string, not the normalised one, so the accents and capitals survive on screen:

return hallados.slice(0, MAX_RESULTADOS).map(({ indice, persona, pos }) => {
  const nombre = persona.nombre || ''
  return {
    indice,
    persona,
    antes: nombre.slice(0, pos),
    coincide: nombre.slice(pos, pos + termino.length),
    despues: nombre.slice(pos + termino.length),
  }
})

None of this is clever. It's the kind of thing that gets skipped because it isn't a feature, it's a detail — and then it turns out to be the difference between finding a person in two seconds and scrolling a table in front of an audience.

5. Closing the app shouldn't cost you the evening

This one didn't come from a hesitation. It came from the app being closed with unsaved work in it.

The data model here is deliberately strict: the app always boots from the saved database, never from the working session. Save is the only point that consolidates anything. That's a real feature — it means closing without saving is a clean undo of the entire evening, which is exactly what you want after a session that went sideways.

It also means an accidental close is catastrophic, and an accidental close is not a hypothetical. It happened.

You can't fix that by relaxing the rule, because the rule is the feature. So every change to the working session also writes it somewhere separate:

// Single point every change to the working session passes through, so it's
// also where "there's something pending Save" gets marked.
function guardarEnSession(): void {
  ipc.saveSessionPersonas(state.listaPersonas)
  state.cambiosSinGuardar = true
}

That lands in its own SQLite table, next to the consolidated one:

CREATE TABLE IF NOT EXISTS session_data (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    timestamp TEXT
);

And Settings → Load temporary version (session) brings it back, with both timestamps shown side by side so you can see what you're choosing between. Closing the app now also asks, offering Save and exit / Exit without saving / Cancel — and if the save fails, it doesn't exit.

The general shape of this: if you make a strict rule about when data is committed, you owe the user a way back from the one case where that rule hurts. Not a softer rule. An escape hatch, clearly labelled as one, sitting outside the normal flow.

What I didn't build, and why

Fifteen items in the notebook. Not fifteen features. Some of the best decisions of version 2 were the ones I talked myself out of:

Two people editing at once. This never came up as a request; it came up as a could it. The session has exactly one person driving, in a room, on purpose. That's what makes the outcome authoritative. Multi-user doesn't improve that evening, it dissolves it.
Cloud sync or cloud backup. The app backs up its database locally every thirty minutes, which protects against nothing if the machine dies. The honest answer to "what if the laptop breaks" is export the file and put it somewhere else, and I ship that instead. Adding a server would also undo the entire offline-first argument the app is built on.
A configurable number of events and slots. Genuinely the most tempting one, and it came from me rather than from the room — the generalisation itch. Five events, eleven slots, in that fixed order, is what this group does. Making it configurable buys a hypothetical second customer and charges every screen in the app a layer of indirection to get there.
A general undo stack. Reopening an event covers the case that actually occurred. Ctrl+Z over a rotating queue is a much larger idea wearing a small idea's clothing.
Auto-update. It checks nothing and connects nowhere. Updating means running the new installer over the old one, and that is the whole story.

Every one of those makes the app more capable in the abstract and worse at the single evening it exists for. Saying no to them is not restraint or minimalism, it's the same design work as saying yes to the other five — done in the direction nobody gives you credit for.

Version 1's job was to produce the list

The uncomfortable part is how cheap every one of these fixes was. A field that stores what the counter destroys. A normalise call. A second table. A placement loop that took an afternoon.

I could not have specified any of them up front, and I don't think a longer analysis phase would have got me there. I wrote version 1 from the rules of the rota — slots, rotation, squads, veterans, licenses, penalties — and every one of those rules was implemented correctly in version 1. It was a correct application. The list above isn't in the rules. It lives in the gap between the rules and one evening in a room in Alcoy.

So "a year of real use" is doing some work in that title, and I should be precise about it: one session run live, and twelve months of that session's result being the thing people actually consulted. Both halves produced findings. The evening produced the hesitations; the year afterwards produced the ones you only notice when you go back to the data and it doesn't say what happened.

Between them they produced a better requirements document than any process I could have run beforehand, and the cost was sitting still and writing things down.

If there's something to take from it, it isn't watch your users — everybody says that and nobody schedules it. It's narrower: version 1 doesn't have to be complete. It has to be good enough to be used for real, once, in the actual conditions. Then you have to be in the room, and you have to keep your hands off the keyboard.

Designing a UI That Gets Projected in Front of a Room

Christian • ancer — Wed, 16 Sep 2026 09:00:00 +0000

Almost every interface decision I make assumes a private screen. One person, their own monitor, their own data in front of them. It's such a safe assumption that it never gets written down anywhere.

For the last few months I've been building a Windows desktop app called Rueda de Actos, for the Filà Ligeros — one of the groups that take part in the Moros y Cristianos festival in Alcoy, Spain. Its job is to hand out participation in five festival events, eleven slots each, following a rotating turn that has to stay fair from one year to the next.

It breaks that assumption completely.

The app runs once a year, in a meeting room, projected on a wall, with the whole board watching. One person drives it. There are ninety-six names in the table on screen, and a good number of them belong to people sitting in that room.

Every interesting design decision in this app came out of that one sentence.

The room is the spec

Put the scenario next to the usual mental model and the assumptions fall over one by one.

The usual assumption	The actual session
One user looking at the screen	One user driving, a room reading over their shoulder
The data is about other people	The data is about the audience
A mistake costs a few seconds	A mistake happens in front of everyone it affects
You can use the app again tomorrow	The session happens once a year

None of that is exotic. It's a projector and a meeting, which describes a fair amount of internal software. The difference here is that the rows are the audience — this is a group of neighbours and friends deciding who marches in which squad, and the tool is standing in the middle of it.

So the brief stopped being "make this efficient to operate" and became something closer to "make this safe to project".

The block is public. The reason is private.

Two things can make a person ineligible: unpaid dues and a standing penalty. Both are recorded per person. Neither one appears anywhere in the table.

They live in the individual record, behind the pencil icon on the row, as two toggles next to the license status. That record opens for one person at a time, and in practice it gets opened when nobody has a reason to look.

What the table shows instead is that the cell can't be clicked. That's it.

The reason this works is that a blocked cell is deliberately ambiguous. Three different rules produce it, and they all render identically:

// Behind on dues, or carrying a penalty.
const blockedByStatus = (person.unpaidDues || person.penalty)
  && event === activeColumn && !assignedThisYear

// Already taking part in another event this year.
const blockedByAnotherEvent = !state.allowMultipleEvents
  && hasAnyEventThisYear(person) && !assignedThisYear && person[event] == null

// Already did this same event in an earlier edition.
const blockedByRepeat = !state.allowRepeatEvent
  && event === activeColumn && !assignedThisYear && person[event] != null

// One class. Three reasons. The cell never says which.
classes['cell-blocked'] = blockedByStatus || blockedByAnotherEvent || blockedByRepeat

And that class is a single flat pattern, with nothing attached to it:

td.cell-blocked {
  background-image: repeating-linear-gradient(
    -45deg, transparent 0 5px, rgba(100, 116, 139, .13) 5px 6px
  );
  cursor: not-allowed;
  pointer-events: none;
}

The room sees that the rules were applied. The room does not learn who owes money.

The temptation I had to talk myself out of was the tooltip. On any other desktop app I'd have added title="Blocked: unpaid dues" without thinking — it's helpful, it's cheap, it's what a good interface does. Projected, it's the worst feature in the product: the same private fact, on a half-second delay, rendered wherever the mouse happens to be resting, at wall size.

Worth being precise about where the line sits, because it isn't "hide every status". The avantcarga license — the paperwork some members need for certain events — is right there in the open, as a small coloured card next to each name and as a running count in the header: 32 valid, 13 expired, 51 none. Nobody minds. It's an administrative fact about a document.

Money and penalties are a fact about a person, in a room full of people who know them. That's the line, and it isn't a technical one. It came from asking what would be uncomfortable to have on a wall, not from a data classification exercise.

Everyone has to stay oriented, not just the operator

In a normal app, only the user needs to know where they are. Here, thirty people are following along without touching anything, and every question they can't answer for themselves becomes an interruption: wait, which event are we on? how many are left? is that one full?

So the state of the session is permanently on screen, not tucked behind the current interaction:

Five cards across the top, one per event, each showing 8/11 and a men/women split (H 8 M 0), with a fill bar. The event in progress is the blue one.
The active column is tinted down the entire height of the table, so a row halfway down the list still reads as belonging to the current event.
A status line along the bottom: how many people are in the rota, which event is in progress, and whether the squad has locked to a gender.

One small detail I like more than it probably deserves. When an event closes, its per-gender counters are reset internally, so leaving them on the card would show a confident H 0 M 0 for an event that had just filled eleven slots. The card swaps them for a state instead — Completed, Skipped, Incomplete, Pending verification — and only shows numbers while they still mean something.

Nobody would catch that in a code review. Projected, a wrong number on a wall gets a question from the third row, and the session stops while somebody explains that the zero doesn't mean what it says.

If you cover something, let them move it

When the eleven slots fill, a verification modal opens listing the eleven people, with a checkbox for squad leaders and an × to remove anyone who shouldn't be there. It's the moment the room is paying most attention.

It also covers about eleven rows of the table underneath — which is exactly when somebody asks whether so-and-so already went out last year.

On a private screen the answer is trivial: close the dialog, look, open it again. In front of a room, that means throwing away a selection you just made while eleven people wait for you to rebuild it.

So every modal in the app can be dragged out of the way:

const INTERACTIVE = 'button, a, input, select, textarea, label, [contenteditable]'

function onPointerDown(e) {
  if (e.button !== 0) return
  const target = e.target
  if (target.closest(INTERACTIVE)) return

  // The handle is the header. Small dialogs have no header, so anything
  // non-interactive works there.
  const header = contentEl.value?.querySelector('.modal-header')
  if (header && !header.contains(target)) return

  measureBase()
  pointerStart = { x: e.clientX, y: e.clientY }
  offsetStart = { ...offset.value }
  dragging = true
  contentEl.value?.setPointerCapture?.(e.pointerId)
  e.preventDefault()   // without this, dragging selects the dialog's text
}

Two things in there exist only because of the room.

The first is that check against INTERACTIVE. Dragging from a button would make the checkboxes in that verification list less than perfectly reliable to click, and a mis-click during verification is the one mistake you cannot make quietly.

The second doesn't appear in that snippet: every offset is clamped against window.innerWidth and innerHeight before it's applied, so the dialog can't be dragged past the edge of the screen. This is a kiosk-shaped desktop app — no browser chrome, no page scroll, nothing to rescue a window that left the viewport. Get that wrong and the operator is closing a modal they can no longer see, blind, in front of everybody.

The position also resets to centre on every open, rather than remembering where the last dialog was left. Where you dragged the previous dialog says nothing about what the next one is covering.

Interrupt for changes, not for confirmations

The app has one dialog system, and the rule that decides how a message appears turned out to be a single line:

// A notice is a dialog that closes itself and expects no answer.
const isNotice = computed(() =>
  dialog.timer > 0 && !dialog.showConfirmButton && !dialog.showCancelButton
)

If there's nothing to answer, it isn't allowed to take the screen. Saved, 12 records imported, Exported to XLSX, Event reopened — corner of the screen, no backdrop, a thin bar draining to show how long it stays, gone in two seconds. The app underneath keeps working the whole time.

Dimming an entire projected wall to announce "Saved" is absurd once you've watched it happen. It was also covering the modal that was in the middle of closing behind it.

The interesting case is the one that still blocks.

The squad rules say an event locks to a gender once six of the eleven go the same way. When that happens the app doesn't just note it — it un-assigns everyone of the other gender from the event, which rewrites rows the room is actively reading.

That started life as a corner notice. It was wrong. The toast slid away after two seconds, the table simply changed, and people were left wondering what the operator had done.

It's now the one message in the app allowed to take the whole screen: centred, no backdrop click, no Escape, and a single Understood button somebody has to press before the session moves on. It names the rule that fired — Men's event — and says plainly that the women have been un-assigned.

The rule I ended up with: interrupt when the screen changed underneath the room, never to confirm something the operator did on purpose.

At three metres, colour is the interface

Nobody in the fourth row is reading a table cell. They're reading colour and position, and only leaning in when something looks off.

So colour carries real information, and it's the only part of the visual design with a strict budget:

Green — assigned in the current edition.
Hatched grey — unavailable, reason unstated.
One tint per past year — 2023 amber, 2024 yellow, 2025 blue, and so on. You can see how long ago someone last did an event without reading a single number.
Bold year — that person was a squad leader that year.
A small coloured card beside the name — license valid, expired, or missing.

Everything else is grey. There is no colour in this UI that doesn't mean something, which is less a matter of taste than of bandwidth: the moment you use a tint for decoration, the room starts trying to decode it.

The honest caveat: those license cards are colour-only, three images that differ in nothing but hue, with a title carrying the exact status. That would not pass an accessibility review, and it's on the list. The rest of the palette is redundant — every tinted cell also contains the year as text, and blocked cells carry a hatch pattern as well as a fill — but the cards genuinely aren't, and writing this up is what made me notice.

None of this was in the requirements

Here's the part that bothers me a little.

Every decision above is small and cheap. Not painting two fields. One CSS class covering three cases. A pointerdown handler with an early return. A boolean choosing corner over centre.

And not one of them was in anything I was given. The brief was the rules of the rota — slots, rotation, squads, veterans, licenses, penalties — and every one of those rules is in the app, correctly. You could implement the entire specification, pass every test, and still ship something that quietly puts a member's unpaid dues on a wall in front of them.

They came from watching the previous version being used. Not from a demo and not from a call: somebody had been running this session for years, and the shape of that evening — the projector, the questions from the room, the window that had to be closed to check something — was the real requirements document. It just wasn't written like one.

I don't have a repeatable process for extracting that, and I'm suspicious of anyone who claims one. The closest thing I have is a question I now ask early, before any of the interesting technical questions: where will this be running, and who else can see the screen?

Context of use is a functional requirement

We're fairly disciplined about non-functional requirements when they have familiar names. Performance, accessibility, security — those get budgeted for.

Where the screen is doesn't have a familiar name, so it gets skipped. And when it's skipped, what you ship is an interface that is entirely correct and still fails on the one night it's used, because you built for a desk and it ended up standing in front of a room.

The rota is fair either way. The maths doesn't care where it runs. But the whole point of building this was that the group could watch the reasoning happen and stop having the argument — and that only works if the screen shows exactly what the room is entitled to see, and not one field more.

Building Offline-First Desktop Software in 2026

Christian • ancer — Wed, 09 Sep 2026 09:00:00 +0000

Every new app is drawn with a server in it.

Accounts, an API, sync, a subscription tier. It gets decided before anyone asks the question that actually matters: where will this run, and who is standing in front of it?

For the last few months I've been building a Windows desktop app called Rueda de Actos. It's a custom tool for the Filà Ligeros, one of the groups that take part in the Moros y Cristianos festival in Alcoy, Spain. Its job is to hand out participation in five festival events, eleven spots each, following a rotating turn that has to stay fair year after year.

It makes zero network calls. Not one. No accounts, no sync, no telemetry, no update check.

That isn't nostalgia and it wasn't a shortcut. It's the answer the context gave.

The room decides the architecture

Software gets used somewhere, and that somewhere usually has more to say about your stack than any benchmark does.

Here is the somewhere: a room, a projector, the whole board sitting around a table, and one person driving the app while everyone watches the screen. It happens once a year. The wifi in that building is whatever it happens to be that night.

Run a cloud app against that scenario and count the failure modes:

The connection drops on the one night of the year the tool is needed.
Members' personal data leaves the building to sit on somebody else's server.
The tool stops working the day a subscription lapses, or the day I stop maintaining it.

None of those are exotic. They are the ordinary price of having a server, and normally you pay it gladly, because you get sync, multi-user access, remote access and painless updates in return. In this room you get none of that back. There is one user, one machine, and one session a year.

So the server came out. What's left is a database file on the computer of the person running the meeting.

The stack

Layer	Choice
Shell	Electron 31
UI	Vue 3 (Composition API) + Bootstrap 5
Data	SQLite via `better-sqlite3`
Build	Vite
Tests	Vitest
Packaging	electron-builder → NSIS installer
Logging	electron-log, to a local file

Nothing exotic. The interesting part is what the renderer is allowed to do. It runs with nodeIntegration off and contextIsolation on, so its entire access to the machine is whatever the preload script decides to hand it:

// electron/preload.js
contextBridge.exposeInMainWorld('api', {
  getPersonas: () => ipcRenderer.invoke('db:getPersonas'),
  savePersonas: (data) => ipcRenderer.invoke('db:savePersonas', data),
  importXLSX: (path) => ipcRenderer.invoke('import:xlsx', path),
  exportJSON: (data, path) => ipcRenderer.invoke('export:json', data, path),
  // ...
})

The UI is a web app that cannot touch the filesystem or the database. It can call the handful of functions the preload hands it, and nothing else. Every one of them is validated on the other side before it reaches SQLite. Removing the server does not mean removing the boundary — it means the boundary moved inside the process.

What disappears when you delete the server

Accounts and authentication. Physical access to the laptop is the authentication.
Sync and conflict resolution. There is one writer. There is never a merge.
Recurring cost. Nothing to pay, nothing to renew, nothing to migrate when a provider changes its pricing.
Attack surface. No listening port, no endpoint, no token to leak, no dependency on my uptime.
The privacy conversation. Not because it was answered well, but because it stopped applying.

That last one was the part the client actually felt. "Where do the names end up?" — "On your computer. They never leave it."

Three problems move in instead

Deleting the server doesn't simplify the project. It relocates the difficulty.

1. Backups are your job now

There is no nightly dump on somebody else's infrastructure. So the app makes its own: a full SQLite copy every 30 minutes, keeping the last ten.

function performBackup() {
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
  database.backupToFile(path.join(backupDir, `rueda-ligeros-${timestamp}.db`))
  rotate(backupDir, MAX_BACKUPS)   // newest ten stay, the rest are unlinked
}

performBackup()
setInterval(performBackup, 30 * 60 * 1000)

better-sqlite3 exposes SQLite's own online backup API, so this is a consistent snapshot rather than a file copy taken mid-write.

Worth being honest about what this protects against: those copies live on the same disk as the original. They save you from "I just broke the data", not from "the laptop died". The second one has a different answer, further down.

2. Migrations run on a machine you will never see

There is no maintenance window, no staging environment, no rollback button, and nobody to call. The user double-clicks the new version and the schema has to be correct by the time the window appears.

So the schema is versioned, and the app migrates itself on startup:

function runMigrations(db, log) {
  const currentVersion = getSchemaVersion(db)   // from a metadata table
  const pending = migrations.filter(m => m.version > currentVersion)

  for (const migration of pending) {
    db.transaction(() => {
      migration.up(db)
      setSchemaVersion(db, migration.version)
    })()
    log.info(`Migration v${migration.version} applied: ${migration.description}`)
  }
}

Each migration is a { version, description, up } object in an ordered array, each one runs inside a transaction, and a throw stops the chain instead of leaving the database half-converted.

That structure earned its keep on migration 3, which normalised the event assignments out of the personas table into a persona_actos child table. SQLite's answer to dropping columns is create-copy-drop-rename, which is well documented and looks harmless:

Create the new child table.
Read the old assignments.
Rebuild the parent table without the old columns.
Insert the assignments into the child table.

Get steps 3 and 4 the wrong way round and you lose data silently. With foreign_keys = ON, the DROP TABLE personas in step 3 fires an implicit DELETE, which cascades through ON DELETE CASCADE and empties the child table you just carefully filled. No error. No warning. An empty table, and a version number claiming the migration succeeded.

The comment explaining that ordering is now four lines long and sits directly above the code. When a migration runs on a stranger's machine, in a building you're not in, the day before the tool is needed, there is no second attempt.

3. Distribution is a person carrying a file

No auto-update. Not even a version check — a version check is a network call, and the whole premise was that there aren't any. The electron-builder config has no publish block and never will: there is nowhere to publish to, and nothing to check against.

New version means a new installer, run over the old one, data preserved. That is the entire update story.

And then there's SmartScreen. The installer isn't code-signed, so Windows greets a non-technical user with a blue full-screen panel that says "Windows protected your PC" and hides the button that runs it anyway behind a More info link. To a developer that's an inconvenience. To the person installing it, that dialog reads as "this is a virus", and the software has failed before it ever opened.

There are two options: buy a certificate, or explain. A code-signing certificate is a recurring cost, and even with one, SmartScreen reputation takes downloads to accumulate — which an app with a single-digit user count will never get. So the build script is written to sign automatically the day a certificate exists, and until then the answer is documentation: one line in the install guide, and a heads-up to the person who will click the button, before they click it.

It's an unsatisfying answer. It's also the honest one, and pretending the dialog doesn't exist would have been worse.

The data has to be able to leave

With no server, there is no "your data is safe with us" to offer. What you can offer instead is that nothing is trapped.

Everything imports and exports in both directions, as XLSX and as JSON. Import accepts the spreadsheet the group was already keeping — a hand-made one is fine, as long as there's a name column. Export writes a file that goes on a USB stick, into an email, or onto another machine.

That's also the real backup story. The half-hourly copies protect the session; the export is the one that survives the hard drive. And it's the answer to the question every custom-software client should ask and rarely does: what happens to us if you disappear? The data is a spreadsheet. Somebody else can pick it up.

Testing replaces the operations you don't have

No error tracking, no logs streaming back to me, no ability to hotfix anything. Whatever ships is what runs until somebody tells me otherwise.

What's left is testing before the fact: close to 400 tests covering the turn rotation, the eligibility rules, validation, the migrations and the import/export round trip, running on every build of the installer. Plus electron-log writing to a local file, so that when something does go wrong there's something concrete to ask the user for.

That trade is easy to underestimate. Server-side, you can be wrong for twenty minutes. Here, being wrong means being wrong for a year.

Offline-first isn't a step back

The reflex is to read a local desktop app as what we used to do before we knew better. Sometimes that's exactly what it is. Here it isn't.

Everything the cloud would have added to this project — sync, accounts, remote access, seamless updates — is worth nothing in a room with one machine and one session a year. Everything it would have introduced — a connection that can fail, a bill that can lapse, personal data on somebody else's disk — lands squarely on the night it matters most.

Picking an architecture is not picking the most current option. It's picking the one that still works under the real conditions of use.

The wifi in that room can do whatever it likes. The app opens.

The First Version Is Just The Beginning

Christian • ancer — Wed, 29 Jul 2026 09:00:00 +0000

Releasing a piece of software feels like reaching the finish line. After weeks or months of planning, writing code, fixing bugs and polishing details, clicking the "Publish" button is a satisfying moment. But the more products I build, the more I realize that a release isn't the end of the journey. It's simply the point where the product stops being shaped only by the developer and starts being shaped by the people who actually use it.

Before a launch, every design decision is based on assumptions. You can test your application, ask for opinions and imagine different workflows, but there's a limit to how much you can learn in isolation. Real users always find unexpected ways to use a product. They notice friction you had stopped seeing, ask questions you never considered and often reveal problems that only appear outside your own development environment.

One thing I've learned is that software rarely improves because of one huge update. More often, progress comes from dozens of small refinements. A shortcut that saves a few seconds. A button that's easier to find. A clearer error message. A better default setting. None of those changes deserves a headline on its own, but together they have a significant impact on how the product feels after weeks or months of use.

Feedback plays an important role in that process, although not always in the way people expect. Feature requests are useful, but they are only one type of feedback. Sometimes the most valuable comments aren't asking for something new—they're describing a moment of confusion or explaining why a workflow didn't behave as expected. Those observations often highlight opportunities to simplify the product rather than expand it.

That's the mindset I've tried to keep while working on Convertim. Since its release, the objective hasn't been to add features as quickly as possible. Instead, I've focused on understanding how people use the application, improving existing workflows and being selective about what deserves to become part of the product. Every new feature increases the cost of maintenance, documentation and testing, so saying "not yet" is often as important as saying "yes."

This approach isn't the fastest way to build software, but I believe it leads to better products in the long run. A tool that stays focused is usually easier to understand, easier to maintain and more enjoyable to use than one that tries to solve every possible problem. Growth is important, but clarity is what keeps a product useful over time.

Final Thoughts

Version 1.0 isn't the destination. It's the first opportunity to learn from real users and real workflows. The goal isn't to ship as many updates as possible, but to make each one meaningful. Looking back, I think that's what building software is really about: continuous improvement, thoughtful decisions and accepting that the first version is only the beginning.

Every Dependency Has a Cost

Christian • ancer — Sat, 25 Jul 2026 09:00:00 +0000

One of the best things about modern software development is that we don't have to build everything ourselves. Open-source libraries and third-party packages let us solve complex problems in minutes instead of days, allowing us to focus on what actually makes our applications unique.

That's why adding a dependency often feels like an obvious choice.

The problem is that every dependency comes with baggage.

You're not only importing code—you are also importing someone else's release cycle, security updates, breaking changes, licensing decisions, and maintenance priorities. Even the most popular packages can become abandoned or introduce changes that force you to adapt your own project.

That doesn't mean dependencies are bad. Many of them save hundreds of hours of work and have become industry standards for good reason. The key is being intentional instead of installing a package for every small problem.

Before adding a new dependency, I usually ask myself a few simple questions:

Does it solve a significant problem?
Is the project actively maintained?
Could I reasonably implement this myself?
If I needed to remove it later, how difficult would that be?

Those questions don't always lead to the same answer, but they help avoid unnecessary complexity.

While building Convertim, I've found that saying "no" to an extra dependency is sometimes the better engineering decision. A few more lines of code today can mean fewer updates, fewer compatibility issues, and less maintenance in the future.

Architecture isn't only about choosing the right technologies.

Sometimes it's also about choosing what not to add.

The Features We Chose Not To Build

Christian • ancer — Wed, 22 Jul 2026 09:00:00 +0000

When people talk about software development, the conversation usually revolves around what gets added. New features generate excitement, screenshots, release notes and marketing material. They give users something tangible to explore and give developers something new to build. It's easy to believe that the value of a product grows in direct proportion to the number of capabilities it offers.

In reality, some of the most important product decisions never appear in a changelog.

Every feature starts as a good idea. Someone encounters a problem, imagines a solution and suggests adding another option, another setting or another workflow. Looking at those ideas one by one, it's surprisingly difficult to reject them because each proposal often makes perfect sense on its own. The challenge only becomes visible when you look at the product as a whole instead of evaluating individual requests.

Every Feature Is a Long-Term Commitment

Adding functionality isn't just about writing code. Every new feature becomes part of the application for as long as the product exists. It needs documentation, testing, maintenance and compatibility with everything that comes afterwards. Future updates have to take it into account, bug fixes become more complicated and every new release has one more moving part that can potentially fail.

Those costs are rarely obvious when the feature is first implemented. At that moment, all you see is the problem it solves. The maintenance cost only becomes apparent months or even years later, when the product has evolved and dozens of independent decisions begin interacting with one another.

That's why product development isn't simply a process of adding value. It's also a process of deciding which responsibilities you're willing to carry in the future.

The Best Question Isn't "Can We Build It?"

As developers, we naturally enjoy solving technical problems. When someone suggests a useful feature, the first instinct is often to think about how it could be implemented. Modern frameworks, libraries and development tools make building software faster than ever, which means the technical challenge is often smaller than it used to be.

The more interesting question isn't whether something can be built. It's whether it deserves to become part of the product.

Some ideas solve edge cases that affect very few people. Others introduce configuration screens that make the interface harder to understand. Some require new dependencies, increase testing effort or create maintenance work that continues long after the original problem has been forgotten.

A feature can be technically successful while still making the product worse.

Building Convertim Meant Rejecting Good Ideas

While building Convertim, there were plenty of ideas that looked genuinely useful. Some would have added flexibility, others would have supported additional workflows, and a few would probably have looked impressive on a feature list.

We still decided not to build them.

Not because they were impossible, but because they moved the application away from its main purpose. Convertim was designed to be a simple, local-first image conversion tool. Every feature that doesn't reinforce that goal has to justify the complexity it introduces, and many perfectly reasonable ideas simply couldn't pass that test.

Saying "no" isn't about limiting the product. It's about protecting it from gradually becoming something it was never intended to be.

Simplicity Doesn't Happen By Accident

Software naturally becomes more complex over time. Every new option, every additional workflow and every extra dependency increases the number of decisions both developers and users have to make. Left unchecked, complexity accumulates almost automatically.

Simplicity works differently.

A simple product is usually the result of dozens of conscious decisions to leave things out. Those decisions often happen long before users ever download the application, and they're rarely visible from the outside. Users don't know which features were rejected during development, but they do notice when a tool feels focused, predictable and easy to understand.

That's why simplicity should never be confused with a lack of effort. In many cases, it's the result of much more discipline.

Think Beyond The Next Release

It's tempting to evaluate features based on how exciting they are today. They make a roadmap look more impressive and provide something new to announce. The problem is that software doesn't stop evolving after the next release. Every decision becomes part of the foundation that future versions have to build upon.

One mindset that has helped me is to imagine maintaining today's decisions a year from now. If a feature still feels worthwhile after considering future updates, bug fixes and ongoing maintenance, it's probably a good investment. If its long-term value is difficult to justify, adding it simply because it's possible is rarely the right answer.

Thinking that way doesn't slow development down. It keeps the product moving in the right direction.

Final Thoughts

A product isn't defined only by what it includes. It's also defined by everything its creators intentionally leave out.

Users rarely ask whether a feature was difficult to build, but they immediately notice when an application feels focused, coherent and easy to use. Those qualities don't appear by chance. They're usually the result of hundreds of small decisions, many of which involve saying "no" to ideas that seemed perfectly reasonable at the time.

Sometimes the best feature isn't the next one you add.

It's the one you decide not to build.

Why Software Friction Matters

Christian • ancer — Sat, 18 Jul 2026 16:00:00 +0000

When we talk about improving software, the first idea is usually to add something new: another feature, another option, another way to customize the experience.

But many times, the biggest improvements come from the opposite direction. Removing unnecessary steps, reducing decisions users should not have to make, and making common actions feel simpler.

That is where software friction appears.

Friction is everything that creates distance between the user and the result they want to achieve. It can be an extra step repeated hundreds of times, a confusing setting, a slow process, or a workflow that forces people to adapt to the tool instead of helping them complete their task.

Individually, these problems usually look small. One extra click does not seem important. Waiting a few more seconds feels acceptable. Manually repeating an action once is not a big issue.

But software is built around repetition, and small moments of friction become much more noticeable over time.

Reducing friction is not only a design problem. It is also an engineering decision.

A simple experience often depends on things users never directly see: how the application is structured, how workflows are designed, which defaults are selected, and which features are intentionally kept simple.

The goal is not always to add more possibilities. Sometimes the better decision is making the existing workflow clearer, faster, and easier to understand.

Good software does not just solve a problem. It removes everything unnecessary between the user and that solution.

What is a small improvement in a tool that completely changed your experience using it?