Open Source Project Advice

On August 9, 2013, in General Development, by Jim Cowart

Recently, David Neal – a friend and very talented developer – asked this question:

I’ve been mulling this question over myself. I’ve been involved in several OSS projects – many of which I’ve started. I can’t speak to the realities of running a project as large as something like jQuery, or Apache Cordova – since my projects have been a bit smaller. But I told David I’d think it over and write my thoughts down.

1.) Invoke Wheaton’s Law and Follow It Adamantly

I’m a former musician who happened into development and fell in love with writing software. I used to think that my knowledge was swiss cheese compared to many colleagues, but soon discovered that *everyone* has gaps in what they know. Each OSS project – no matter how large or small – will have a culture associated with it. Be patient with people who might not know what they need to know, but are asking questions. Be patient with know-it-alls who ignore Wheaton’s Law. Jerks don’t control your project, YOU do. Don’t cede control of culture, attitude or architecture to people who don’t display the character of a decent and humble human being. Period.

When you build a culture that has love of learning, love of creative innovation & humility as core traits – you’ve created a space for people at any level to come and safely learn and mentor. Some of the best friendships I’ve forged as a developer have come from people treating me with this kind of respect (looking at you Alex Robson, Nicholas Cloud, Doug Neiner and Elijah Manor), and it’s become my goal to treat others this way as well. It’s a huge honor to have a part in someone’s journey towards learning new things and being passionate about them.

2.) Choose a Permissive License

My go-to license is MIT. You can dual-license projects, if necessary. Check out http://choosealicense.com/, and of course read over license specifics at opensource.org.

3.) Don’t Rush to Version 1.0 status

You’re going to want and need the space to iterate, improve, refactor and change. We’re all adults here. If someone uses your library at v0.2.3, then they have judged the risk as acceptable (hopefully), even though the project is young. You can remind people in your README or other documentation that the project is experimental and subject to change. While we all know that slapping the label “version 1.0″ on something doesn’t make it production ready, there’s still a large number of developers who will perceive it that way. Not rushing your project to that place will help you manage the next piece of advice.

4.) Don’t Be Afraid to Break APIs (but do so responsibly)

I made a huge mistake early on with one of my projects (postal.js) – by not moving the API in the direction I wanted it to go. I was trying to be sensitive to a user of the library (not a bad thing). However, in hindsight, I feel it stalled the direction and maturity of the project for a couple of versions. When I finally made the breaking API changes, I felt like the project had new life in it, and ideas I’d had for extending it began to flow much more easily. I took the time to solicit feedback from people using the library – using gists to get their input, for example. This is important not only for you to learn from those using your code in-the-trenches, but it helps educate them on what the changes are & includes them in that process. Being included in the loop when breaking changes hit lowers the resistance and frustration level that would otherwise be directed at you.

5.) Don’t Be Afraid to Say:  ”No”, “Please Submit Tests”, “Please fix {x}”, etc.

Sometimes you’ll get pull requests that are terrible ideas. Sometimes, it’s a great idea, but doesn’t really belong in the library – maybe it should be a plugin, or maybe you should start a contrib project to act as a potential feature funnel. Sometimes you get PRs that don’t have tests. These are all situations where you will need to say “No” in some way. Remember rule #1 when you do this. Most developers will appreciate you explaining your reasoning in a respectful way. Closing it with “No.” as the only comment is NOT a good way to handle it. You can still have strong opinions (I certainly do), but it’s the mark of a real human being to have strong opinions and still be capable of respectful, rational discourse.

If you say “No” because they didn’t include tests, then you’d better have tests of your own.  If you have a specific formatting style (tabs, spaces, whatever), explain it in your README. Noisy commits due to whitespace changes are something you want to avoid, trust me.

6.) Choose Partners Wisely

If your project grows to the point to where you really need extra help beyond people submitting pull requests, etc. – then consider bringing on other developers as fellow project owners and/or maintainers. Choose these people wisely, though. You want good partnerships, of course. Figure how (and if) your visions for the project align. No one will think exactly like you – and that’s a good thing. But there needs to be enough overlap in vision for a foundation of unity on direction. No matter how knowledgeable or popular someone is, if they are a dick (see # 1 above), DO NOT LET THEM BECOME AN OWNER. The kinds of people you want contributing are people that love what we do, not drama. Toxic political drama in an OSS project is, IMO, the death knell of the project. It’s OK to vary the kinds of control you give to contributors/owners. If a junior developer wants to be involved and help fix bugs – you don’t have to give them ownership-level rights. This is a great way for many people to learn and grow, while also benefitting your project.

7.) Give Credit Where It’s Due – Be Liberal With Praise and Encouragement

Of course – have a thick skin and be an adult if someone doesn’t give you credit. However, it’s a sign of maturity and trustability (is that even a word?!  ) when someone is OK with not taking all the credit. As an OSS author, if someone comes up with a killer idea for your project, praise them publicly and often! Seriously – this alone can do so much to encourage a younger (or less secure) developer – and help fortify them against the inevitable run-in(s) with arrogant jerks. I will admit that if I am working with someone who does not give credit where it’s due (whether it’s due me or someone else) and takes it for themselves instead, I’m far less likely to trust them in most things – not just development.

8.) Don’t Be Afraid to Move On

I’ve started a few projects that I thought were great ideas at the time, and now I’d run from them, screaming. (In fact, I have a blog I need to write at some point about one of them, saying “I was wrong, I’m sorry”!) It’s hard to do this if others still find your project useful. If you’re abandoning it because you’ve learned better approaches, then explain why. If it leads to a new OSS project, then helping others understand how they can migrate to the new library could be nice way to help them out. If you’re abandoning it because you don’t have time, you could reach out and ask if anyone would be willing to take over ownership of the project.

If you deprecate a project that someone’s using, expect them to be frustrated. Unfortunately, that’s reality. But let’s put it into perspective. Before I became an OSS author and consumer, I wrote a lot of the same kinds of utilities for apps, and never generalized them enough to make them re-usable. Instead, those utilities languished and rotted inside a code base that was mostly closed. Finding an OSS library that could’ve managed that particular feature over just 2 or 3 of those apps before it ‘retired’ would have still been a huge time saver.

Overall – Don’t Be Afraid, Period.

OSS is beautiful and dangerous. The large projects at the top of the ladder are not representative examples of what life is like further down. The everyday, in-the-trenches nature of OSS involves endless churn and lots of death and creation. You will find projects that are huge helps – and they could disappear one day in the future – unless you want to pick up the torch and manage it from there. This is why critical thinking, continual growth and creativity as a developer trumps knowledge of a particular API or tool. APIs and tools have brutally short life cycles, don’t let that happen to your knowledge.