What They Don't Tell You About Maintaining an Open Source Project ~ andrej acevski

home
blog
books
rss

⌘
K

← back to blog

What They Don't Tell You About Maintaining an Open Source Project

2025-11-25 · 9 min read

the beginning
building kaneo was fun. a clean, minimal kanban board. self-hosted. open source. no tracking, no subscriptions, no bullshit.
i shipped v1, posted it on reddit, got some stars on github. people actually used it. that feeling when someone tells you they're using something you built? incredible.
then i learned that shipping is just the beginning.
the documentation challenge
i spent hours writing documentation. setup guides, configuration examples, troubleshooting sections. tried to make it clear and comprehensive.
but here's the thing: people come from different backgrounds. what's obvious to me after building the thing isn't obvious to someone installing it for the first time.
someone opens an issue: "how do i install this?"
my first reaction was frustration. it's in the readme! but then i realized - maybe the readme assumes too much. maybe they're new to docker. maybe they're coming from windows and linux is foreign.
so i improved the docs:

added more examples
created a troubleshooting guide
made a video walkthrough
added a "common issues" section

it's a constant process. documentation is never "done."
support is product development
maintaining kaneo means helping people debug their setups. and honestly? it's taught me more than i expected.
people run kaneo on setups i never imagined:

behind corporate proxies
on raspberry pi clusters
in kubernetes with custom networking
on nas devices with limited resources

each support request reveals an assumption i made. each "it doesn't work" issue (even the ones without details) points to a failure mode i didn't consider.
the challenge is balancing time. i want to help everyone. but i also have a day job. and new features to build. and bugs to fix.
i'm still learning how to set boundaries while being helpful.
feature requests are humbling
people want kaneo to do more. and that's amazing! it means they're actually using it. they care enough to imagine what it could be.
but every feature request is a decision:

does this fit the vision?
can i maintain this long-term?
will this complicate the codebase?
what else won't get built if i build this?

saying no is hard. especially when the request is thoughtful and well-reasoned. especially when someone offers to help implement it.
i've learned to be transparent: "i love this idea, but it's outside kaneo's scope. here's why..."
most people understand. some don't. that's okay.
migrations are terrifying
the database schema needed a refactor. the current design was limiting. the new design would enable features people wanted.
but 200+ people were using kaneo in production. their actual work data. their team's workflows.
if i broke the migration, they'd lose trust. maybe lose data. definitely lose sleep.
so i:

wrote the migration script
tested it on every version going back to v1
wrote detailed upgrade notes
tested edge cases
tested the edge cases of edge cases
added validation checks
added dry-run mode

released it. held my breath.
most migrations went smoothly. a few didn't. not because people didn't read the notes - but because they had setups i couldn't have predicted:

modified databases
custom patches
environments i'd never seen

we debugged together. they were patient. i was grateful.
every migration taught me something new about defensive programming.
contributors are a gift
when someone submits a pr, it's incredible. someone cared enough to spend their time improving kaneo.
but integrating contributions is harder than i expected:

different coding styles
different assumptions about architecture
different ideas about what kaneo should be

sometimes a pr is perfect. sometimes it needs work. sometimes it's solving a problem in a way that'll create more problems later.
i've learned to:

appreciate the effort, always
explain my reasoning when requesting changes
be okay with saying "this doesn't fit, but i appreciate you"
sometimes just fix it myself if it's close

the contributors who stick around? they're amazing. they've made kaneo better than i could alone.
the diversity of environments
self-hosting means people run kaneo everywhere:
# docker on their laptops
docker compose up -d

# kubernetes clusters at work
kubectl apply -f kaneo.yaml

# raspberry pi in their home lab
# (with 1GB of RAM and dreams)

# bare metal on old servers
# (that have been running since 2015)

# nas devices with arm processors
# (that i've never even heard of)
each environment teaches me something. each "it doesn't work on my setup" issue reveals an assumption i made about how systems work.
i can't test every environment. but i can make kaneo more resilient:

better error messages
clearer logs
more graceful failures

the people running kaneo on weird setups? they're often the most helpful. they understand their environment. they provide detailed logs. they test fixes.
we figure it out together.
keeping documentation alive
documentation is never finished. every feature needs docs. every bug fix might need docs. every question reveals a gap in docs.
i've learned to:

update docs in the same pr as code changes
treat "docs are wrong" issues as high priority
appreciate when people submit doc fixes
accept that docs will never be perfect

the goal isn't perfect documentation. it's documentation that helps most people most of the time.
and when it doesn't? that's feedback. that's how it gets better.
the comparison question

"why not just use trello/notion/linear?"

it's a fair question. those tools are great. they have teams of engineers, designers, product managers. they're polished. they're fast. they're feature-rich.
kaneo is different:

them
kaneo

cloud-hosted
self-hosted (your data, your server)

closed source
open source (you can read every line)

feature-rich
minimal (does one thing well)

subscription
free (as in freedom and beer)

it's not better. it's different. for some people, that difference matters.
and honestly? building kaneo taught me more than using those tools ever could.
the emotional reality
maintaining open source is a rollercoaster:
someone stars your repo → feels good
someone opens a detailed bug report with logs and reproduction steps → feels great
someone says "kaneo saved our team" → feels incredible
someone opens an issue titled "this is trash" → hurts more than it should
you spend a weekend implementing a requested feature → crickets
you fix a small bug → three people thank you
you realize you haven't worked on your own roadmap in months → exhausting
someone submits a thoughtful pr → you're not alone
the highs are high. the lows are low. but the people who use kaneo, who contribute, who care? they make it worth it.
what i learned
1. scope is everything
kaneo does one thing: kanban boards. not project management. not time tracking. not team chat.
every feature you add is a feature you maintain forever.
being clear about scope isn't limiting - it's liberating. it lets you focus. it lets you say no without guilt.
2. automate everything you can
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
- run: npm test
security:
- run: npm audit
release:
- run: semantic-release
automation isn't lazy. it's sustainable:

automated tests catch bugs before users do
automated releases mean less manual work
automated security scans give peace of mind
automated dependency updates keep things current

it frees you to focus on what matters.
3. good issue templates help everyone
github issue templates help people provide:

system info
error logs
steps to reproduce

it's not about gatekeeping. it's about making debugging possible. most people want to help you help them. templates make that easier.
4. saying no is an act of respect
you can't build everything. saying yes to everything means doing nothing well.
being honest about what you can and can't do respects everyone's time. including yours.
5. users are collaborators
the people using kaneo aren't just users. they're:

beta testers finding bugs
documentation editors spotting gaps
feature designers sharing ideas
community builders helping each other

they're not demanding. they're engaged. that's a gift.
when someone opens an issue, they're investing time in making kaneo better. even if the issue is unclear, the intent is good.
patience and kindness aren't just nice. they're necessary.
the honest truth
maintaining an open source, self-hosted project is:

more work than building it
different fun than building it
more rewarding than you'd expect
harder than you'd expect
worth it

you learn:

technical skills (migrations, security, scalability)
people skills (communication, patience, boundaries)
product skills (prioritization, scope, vision)
how to appreciate every contribution
how to build something people actually want

my setup (the real one)
┌─────────────────────────────────────┐
│ kaneo infrastructure │
├─────────────────────────────────────┤
│ github │
│ ├─ code + issues │
│ ├─ actions (ci/cd) │
│ └─ container registry │
│ │
│ hetzner ($7/month) │
│ └─ cloud instance │
│ │
│ cloudflare (free) │
│ └─ dns + ddos protection │
│ │
│ plausible │
│ └─ privacy-friendly analytics │
│ │
│ coffee (priceless) │
│ └─ way too much │
└─────────────────────────────────────┘

what i'd tell past me
1. invest in documentation early - good docs reduce support burden and help people succeed. it's time well spent.
2. automate from day one - tests, releases, security scans. automation scales. you don't.
3. be clear about scope - say what your project is AND what it isn't. it helps everyone.
4. migrations are worth the extra effort - test thoroughly. add rollbacks. write clear upgrade notes. your users trust you with their data.
5. it's okay to be slow - you're not a company. you're a person. set expectations. take breaks. protect your energy.
6. celebrate your users - every person using kaneo is amazing. they chose to trust something you built. that's incredible.
7. the community is the product - the code matters, but the people matter more. invest in both.
the conclusion
would i do it again?
absolutely.
kaneo exists because i wanted a simple kanban board that i controlled. but it became something more: a community of people who value privacy, simplicity, and owning their tools.
the maintenance is real work. the migrations are stressful. the support takes time.
but people are using kaneo to:

run their businesses
manage their side projects
organize their teams
learn about self-hosting

they send thank you messages. they submit thoughtful bug reports. they contribute code. they help each other in discussions.
that's not just cool. that's why i do this.

kaneo is open source and free forever. check it out: github.com/usekaneo/kaneo
if you're using it, thank you. if you're contributing, you're amazing. if you're thinking about it, the docs are pretty good.
and if you find a bug? i'll fix it. probably at 11pm. but i'll fix it.

github

·

x

home
→

blog
→

books
→

rss
→

Andrej Acevski’s “What They Don’t Tell You About Maintaining an Open Source Project” offers a candid and insightful look into the realities of sustaining a self-hosted, open-source project. Through his experience with kaneo, a minimal kanban board application, Acevski reveals the surprising complexities and profound rewards that come with product maintenance. The piece isn’t a technical deep-dive, but rather a thoughtful reflection on the multifaceted nature of open-source contribution and the importance of community engagement.

The central theme revolves around the contrast between the initial excitement of building a product and the ongoing, often unanticipated, demands of maintaining it. Acevski initially focused on documentation, recognizing that a well-documented product dramatically reduces the burden of support requests. He emphasizes the need to anticipate different user backgrounds and skill levels, highlighting the importance of clear examples, troubleshooting guides, and accessibility options for various operating systems. This is a critical point, as Acevski illustrates – good documentation is never “done,” but a continuous refinement process.

Beyond documentation, Acevski details the significant time investment involved in migrations. He describes the challenges of updating the database schema for 200+ users while maintaining their work data. The immense responsibility of ensuring data integrity and minimizing disruption underscores the gravity of self-hosting and the need for meticulous planning, rigorous testing, and comprehensive upgrade notes. The detail about adding validation checks and dry-run modes speaks to a proactive approach to risk mitigation.

The piece also brilliantly captures the dynamic interplay between the creator and the user community. The author emphasizes that users are not merely consumers of the product but active collaborators – beta testers, documentation editors, and contributors. He stresses the importance of acknowledging and valuing these contributions, and highlights the opportunity to build a strong, engaged community around a project that, at its core, is about empowering individuals to own their tools. Acevski’s recognition of the emotional rollercoaster—the initial starbursts of excitement, the moments of frustration, the profound gratitude— provides a realistic portrait of the open-source experience. He further reinforces community value through his implementation of automated processes via GitHub Actions, emphasizing the need for scalability and efficient workflow automation.

A key differentiator of this piece is its honesty regarding scope and limitations. Acevski clearly articulates that kaneo is designed for a specific purpose – a minimal kanban board – rather than attempting to be a comprehensive project management solution. This discipline is crucial, preventing feature creep and maintaining focus. He uses this framework to politely decline feature requests, prioritizing the long-term viability and sustainability of the project. Furthermore, he highlights the necessity of setting boundaries and honoring one’s own time, acknowledging the demands of a day job and personal well-being.

Finally, the concluding section, detailed with a modest setup of kaneo’s infrastructure and acknowledging the significant role of coffee (and the price of it), encapsulates the personal journey reflected throughout the article. It solidifies the idea that building and maintaining an open-source project isn’t just a technical endeavor, but a deeply rewarding commitment that requires patience, resilience, and a genuine appreciation for the community that sustains it. Acevski’s openness and vulnerability—he admits to fixing things at 11 pm—adds to the piece’s authenticity and elevates it beyond a simple tutorial.