I Ghosted My Own Codebase for 90 Days: Notes From a One-Man Bus Factor Experiment
Photo: SmashingIt99, CC0, via Wikimedia Commons
Every developer has that one repo. The one you built at 11 p.m. on a Tuesday because the tool didn't exist, and now it quietly runs some part of your life — or worse, someone else's. Mine is a little Python service that scrapes my utility provider's website and texts me when my electric bill spikes. Six hundred stars on GitHub, a few hundred people running it, and exactly one person on Earth who understands it: me.
That last number is the problem. The industry calls it bus factor — the count of people who'd need to get hit by a bus before the project is in trouble. For most side projects, that number is one. So I ran an experiment: document the project like I was leaving the company, hand the "reins" to a fictional successor, then go dark for 90 days. No commits, no issue triage, no peeking at the logs.
The Setup: Write Docs for a Stranger
The first weekend was humbling. I sat down to write an onboarding doc and realized I couldn't explain why half the code exists. There's a retry loop with a magic 37-second delay. Why 37? I genuinely don't remember. I had to bisect through three years of commit history to reconstruct the reasoning, and by then the commit messages had degraded into archaeology: "fix stuff," "ugh," and my personal favorite, "final fix for real this time."
I wrote everything I could reconstruct into a HANDOVER.md: architecture, gotchas, the mystery constants, and a map of which files I was ashamed of. Then I set a calendar reminder for 90 days out and walked away.
What Broke While I Was Gone
Day 19: the scraping broke. The utility company redesigned their login page, and without a maintainer, the issue tracker filled up with people pasting stack traces at each other. A community member named Marcus actually figured out the fix and opened a PR — but it sat unmerged for a month because, well, there was no one to merge it. Forks started appearing like weeds.
Day 31: the API key for my SMS provider expired. Nobody, including me-in-the-future, knew where the credentials lived or how to rotate them. The renewal email went to an address I only check during tax season.
Day 44: someone tried to run the test suite on a fresh machine and discovered the setup instructions assumed a 2021-era version of Python and a Postgres config that existed only in my head. The README claimed installation was "straightforward." The README was lying.
Day 60: a genuinely good contributor gave up and left a comment I think about constantly: "Seems like this project is unmaintained. The code is good but there's no way to tell what's intentional and what's abandoned."
That last one stung because it's true of almost everything I've ever written. The difference between a maintained project and an abandoned one isn't activity — it's legibility. Could a stranger tell the difference between a deliberate choice and a fossil?
The Results, Honestly Scored
When I came back after 90 days, I graded the project like a stranger would:
- Could someone build it from the README? No. Two undocumented environment variables, one required config file format mentioned nowhere.
- Could someone understand the architecture? Mostly yes, after the handover doc. The doc was worth roughly ten times its weight in effort.
- Could someone safely change it? No. The tests covered the happy path and nothing else. The magic constants were still unexplained in the code itself.
- Did the project survive? Barely. Marcus's fork had more recent activity than the original.
The Survivability Checklist
The whole exercise distilled into a checklist I now run on every repo before I consider it "done":
- The stranger test: Hand your README to a colleague and watch them set it up. Say nothing. Take notes.
- Explain the weird numbers: Every magic constant gets a comment with why, or a link to the issue that produced it.
- Rotate-able secrets: Credentials live somewhere a successor can find, rotate, and re-deploy without you.
- Commit messages as letters to the future: Write them like the reader is competent but knows nothing about your context. Because eventually, that reader is you.
- Name a backup maintainer: Even a fictional one. Knowing someone might read this changes how you write it.
The uncomfortable takeaway is that bus factor isn't a staffing problem — it's a writing problem. My code was fine. My communication was the single point of failure. The bill-alert service survived its orphanhood because one stranger cared enough to read past my mess. The next project won't get that lucky, so now it gets the checklist instead.