The Story of Shipping a Side Project, Told Through Commit Messages

Sixty-some commits into Photo Sweep's history, a pattern is obvious: the good commit messages here don't describe the diff, they describe the decision behind it. You can reconstruct most of the project's real narrative just by reading them in order, without opening a single file.

Every one of these describes a decision, not a diff — that is what makes a commit log worth reading later.

The beginning

Add the Photo Cleaner Nextcloud app
Add the Android client
Fix two bugs found by running the app on a real server

Three commits, and the third one is the most honest of the bunch. It admits directly that the first two didn't survive contact with a real Nextcloud instance — and rather than folding the fixes silently into the original commits, it names what kind of testing actually found the bugs. That's worth more to a future reader than "bugfix" ever would be: it tells you unit tests and manual dev-environment poking weren't enough, and that a real-server integration test was later added to the CI pipeline for exactly this reason.

The identity crisis

Call it Nextcloud Cleaner everywhere
Rename to Photo Sweep: the store forbids Nextcloud in an app name

Two commits, one hard lesson: the app was fully named, its id set, its README written, before anyone checked the app store's trademark rules. The second message doesn't just say "rename" — it says why, in the same breath. Read cold, months later, that one line explains an entire architectural constraint (the app id can never contain the word that gave the project its original identity) without needing to dig up an issue or a PR discussion.

The security hardening arc

Never write the app password out in clear text
Sign against the occ the image actually ships
Stop the Gradle cache hiding the code from CodeQL
Build the client so CodeQL can actually read it
Encrypt the app password without a deprecated library
Stop one dropped packet ending a sign-in

This run is the most interesting stretch in the whole log, because each message names a failure mode, not a feature. "Sign against the occ the image actually ships" tells you a signing step was previously running against the wrong binary — the base image's own occ, not the one that would end up in the released package — a subtle and genuinely dangerous class of bug for a security-signing step to have. "Stop the Gradle cache hiding the code from CodeQL" tells you a security scan was silently passing on stale, cached code rather than the code actually being committed — a false sense of safety that's worse than no scan at all. "Stop one dropped packet ending a sign-in" tells you Login Flow v2's network handling wasn't originally resilient to exactly the kind of flaky connection its own users — people reviewing photos on a train — would hit constantly.

What makes a commit message like this

None of these are long. None of them describe what changed in the diff sense — you'd still have to read the code for that. What they all do is name the problem, in language specific enough that reading the message alone tells you whether it's still relevant to whatever you're currently debugging. "Fix bug in signing" would have told a future reader nothing. "Sign against the occ the image actually ships" tells you immediately whether your current signing issue is the same one or a different one.

A commit log with messages like this is closer to a running incident report than a changelog. It's the kind of documentation you get for free, purely by describing the failure you just fixed instead of the code you just wrote — and it's the reason this whole retrospective could be written without interviewing anyone who worked on the project.

Series: Photo Sweep.