Skip to content

Seven patch releases in one night

Moving this site's documentation onto a folder of Markdown found seven bugs in one night: sorting, filtering, counting and a time zone nobody asked for. Each became its own patch release.

Mahfuz Shaikh2 min read

Seven version chips from 0.14.1 to 0.14.7 arched under a moon

There's a stretch in the changelog where the version goes 0.14.1, 0.14.2, 0.14.3 and so on up to 0.14.7, all in one night. I didn't plan that. It's what happened when this site's own documentation started living in a folder of Markdown and I clicked around it properly.

Every release, newest first

Dogfooding finds the edges

A collection written as files is a lovely idea until you use it for real. The docs here are dozens of pages in nested folders, and every corner that a test fixture with three files never touched got touched.

  • Sorting. A collection ordered by a number sorted it as text, so 10 came before 2. Sorting by published_at and position needed fixing again for folder-backed collections.

  • Filtering. where and not in a view's query didn't narrow a folder-backed collection at all.

  • Counting. A blueprint didn't count the pages that used it, because those pages weren't rows.

  • Writing. The Control Plane offered to edit pages that live in a file. It shouldn't: two sources of truth for the same page is a bug waiting for a deadline. Now it shows them read-only and names the file.

The time zone nobody chose

My favourite find: Nibble ran on one fixed time zone, wherever in the world a site was, set in a file a site couldn't own. Scheduled publishing went by it and the Control Plane showed dates in it. Now a site picks its own clock, and with nothing set, Rails' default (UTC) stands.

A release that refuses should leave no mess

One patch was about the release script itself. When it refused to cut a release, because the checks failed, it left the version bumped and the changelog half-edited. Now a refusal puts every file back as it found it. A tool that says no shouldn't leave work behind for you to clean up.

Seven releases in a night sounds chaotic. It felt the opposite. Each fix was small, each shipped with its test, and each one made the next bug easier to see.

Content written as files

How a folder becomes a collection, and what stays read-only.

Content as files