Three Weeks of Maintaining
- open source
- maintenance
I kept a log for three weeks of maintaining my small tools, because I suspected my answer to “how is the side project going” was boring in a dishonest way. I would say things like “mostly triage,” which is both true and completely uninformative. Here is what the log actually says.
The ledger
Roughly 21 hours total, across three projects. Where it went:
- 9 hours reading. Issues, PRs, logs, other people's crontabs, the bug I was sure was in my code being reproducible in an upstream library's changelog from 2023.
- 5 hours writing. Docs, release notes, two README sections that answer questions I had answered in email three times each.
- 4 hours talking. Review comments, a patient thread with someone whose bug report started as a one-star rating, and ended as the best issue of the quarter.
- 2 hours code. Two of those hours were a fix measured in lines. The other two were the CI config, again.
- 1 hour regretting. Re-reading my own code from 2021 and choosing, deliberately, to understand it before touching it.
What surprised me
The ratio. If you had asked me, I would have guessed 50/50 code and everything else. The reality is that code is the garnish. Maintenance is a reading comprehension problem wearing a programming costume.
The other surprise: the highest-value hour of the three weeks was writing two paragraphs into a README — the “when not to use this” section. It has visibly cut down the mismatched-expectation issues, which are the ones that drain you, because you cannot fix them with a commit. You can only fix them with prose, in advance.
The one-star bug report
Worth recording, because I nearly handled it badly. It opened with “doesn't work, garbage tool.” The pull on every maintainers' reflex is to answer with a link to the issue template. I have written that reply; it feels righteous and costs you a user and teaches you nothing.
Instead I asked what they were trying to do. What they were trying to do was reasonable, undocumented, and broken in a way I had never considered — they were running the tool under a read-only filesystem where the lock file could not be created. That is a feature gap, not user error. It took one evening to support, and the thread converted the angriest user I have had into the one who now tests the release candidates.
Rules I wrote for myself afterwards
- Log the hours for one week per quarter. The ratio of reading-to-writing is the honest health metric of a project.
- Every question answered twice by email becomes a documentation paragraph the same week.
- Angry first messages get one question back: “what are you trying to do?” They are usually bug reports wearing armor.
- Re-read before refactoring. Especially your own old code, where familiarity lies hardest.
- When a release is blocked on CI, time-box the yak to one hour and then shave it instead.
Why publish this
Because “maintenance” has a PR problem. It sounds like nothing, it photographs as nothing — there is no screenshot of nine hours of reading — and yet it is the entire reason software is usable in year three. The next time someone asks how the side project is going, I am going to send them this post, and then get back to the interesting part, which is reading.