Maintaining Gitlint

7 min read

My experience maintaining a small open source project

Back in 2015, out of frustration with poor git commit messages I kept seeing, I wrote a bash script to enforce some standards, based of community best practices and guidelines I thought were important.

After porting the script to Python, putting it up on github and a mention on reddit, it started getting some attention. A few years and hundreds of hours of effort later, Gitlint now has a small but strong user-base with regular community contributions and releases.

Time for some reflection

The Good 😃

• Uptake: the fact that people care about something you created, to the extent they depend on it for their projects is a pretty great feeling. I get a kick out of receiving a genuine thank you, seeing gitlint being downloaded hundreds of thousands of times a year, or being used by some really big open-source projects like zulip or zephyr or pre-commit support.

• Technical Reference: having a public code-base I can easily grab pieces from for other projects or refer others to as an example of a specific implementation or technical work-around has been pretty useful over the past years.
• Skill Development: I’ve undeniably become a better Python programmer and build a deeper understanding of each of the different steps of development (plan, develop, test, build, release, docs, etc) by having to be hands-on with all of them. The fact it happens all in the open, has been a strong incentive for me to put in extra effort to do it well and not cut corners.
• Giving back: Like everyone, I use a ton of open-source software on a daily basis, created by thousands of volunteers around the world. I’m a strong believer in the open, collaborative and enabling aspects of open-source, so it’s been great to be able to give back a bit and use my skills for good.
• Resume building: having build something out in the open you can use as a reference to proof your technical, communication and project management skills is pretty useful. Every so often, I get some recruiter interest solely based of gitlint.

The Bad 🙁

• Overhead: These days, the amount of overhead wrt project management (e.g. issue triage, code review, releases), testing and documentation far exceeds the amount of time implementing actual features. While this is widely understood as normal in a professional context, for a hobby it can be very tedious at times.
• No longer a user: Since I haven’t coded professionally on a daily basis for several years now, I’ve had much less use for gitlint myself. In practice this means I feel less motivated to work on gitlint and also much less likely to identify bugs or improvement areas as a result of daily usage.
• Pressure of expectations: real or not, I perceive pressure to answer incoming requests quickly, welcomingly and comprehensively. This is especially true when people have spend time writing detailed bug reports or implementing features. While I know I don’t owe anyone anything, it feels ungrateful and disrepectful to not respond appropriately.

The Ugly 🤢

• Python 2.x, Windows, Unicode: I’m sure there’s folks who understand this very well and think it’s easy peasy (counter-argument exhibits: A, B), but I’ve spend A LOT of time getting Unicode to work properly across different OSes and Python versions. Hugely time-consuming.
• Toxic contributors: I’ve been lucky to only have experienced this a few times, and only in the form of rudeness or entitlement (no trolls 🤞), but this is really off-putting and demotivating. From what I’ve read, this unfortunately get’s worse as your project grows.

Some other observations

Turns out, cliches hold truth!

• Docs matter: I’ve spend a lot of time on writing extensive and good looking documentation. I’m convinced this has saved me a lot of user-support work and has attracted more users ("it looks professional, so it must be good!").
• Extensibility FTW: If the tool can’t do it itself, let users customize/extend the tool. Gitlint has user-defined rules to accomplish exactly this and it’s one of the most used features.
• Testing and CI provide peace-of-mind: While it can be frustrating to spend a lot of time writing tests, they provide an enormous reassurance when only working on a project intermittently and changing code you haven’t touched in a long time. It’s also a super useful tool for gating community contributed code which often only focusses on implementing business logic.

Time-boxing to the rescue

Maintaining gitlint has been a mixed bag. On the one hand it’s been very satisfying to be able to develop open-source software being used by so many others, and I’ve learned a ton from it. On the other hand, as the project has matured and my personal use has decreased, its maintance has sometimes started to feel more like a chore than a hobby. I’m not alone in this, the Internet is full of similar stories. For a very thoughtful perspective - I highly recommend My FOSS Story on BurntSushi (Andrew Gallant)’s blog.

Yet, giving up on it is out of the question as of now - there’s too much personal attachment and a form of pride involved. While parts of this post might suggest differently, the pros still outweigh the cons.

The way I’ve dealt with this is by time-boxing gitlint development: I do most of the development in 2-3 sprints a year, and then take a pause for a few months (other than replying to some issues). This has worked fairly well to alleviate pressure and allow me to also work on other projects (and you know, have family and relaxation time).

Conclusion

Being a succesful open-source maintainer is something many software engineers long for - I definitely did and still do. Having had a very small taste of what that’s like, I feel both grateful but also wiser: it’s not all rainbows and unicorns. Do I still recommend it? Absolutely. Just know that it’s not super glorious, it’s mostly hard work!