What They Don't Tell You About Maintaining an Open Source Project
54 points by ficd
54 points by ficd
be clear about scope - say what your project is AND what it isn't. it helps everyone
Really felt this one. Whenever I come across documentation that explains when you should not use it, my trust in the project immediately goes up. I also really appreciate when there's a detailed writeup of why the project exists; I've done this in my own project: https://fennel-lang.org/rationale
Whenever I come across documentation that explains when you should not use it, my trust in the project immediately goes up.
Totally agreed. It's the sign of a developer that knows the limits of their own work.
explains when you should not use it
Myself, I don't trust the projects about use cases — in either direction. I want composable tools that tell what they will and won't do, and keep their word about not doing something, and preferably do something well-defined enough that «when not to use it» can't be more specific «when the things the tool does is not the right thing».
i can't test every environment. but i can make kaneo more resilient:
better error messages
clearer logs
more graceful failures
One rule that I try to follow in all code that people may run in environments I know nothing about and can't access is that logs and error messages should be detailed enough that enabling debug mode would allow me to diagnose the problem without access to the program's source code.
For a shorter version, "if it was closed-source and I was an end user, would I be able to diagnose the problem from its output?". It's not easy but when I did that, there were cases when it helped me fix my own setup problems or realize where exactly a bug was without source-level debugging.