A guide for creating open-source projects

Sorry if this is a duplicate of previous discussions (couldn’t find ones).

Are there any recommended guides about creating open-source projects?
Or rather, do people here wish to share their experience about where to put the attention and care when releasing some code?

This couple of 2013-2014 guides from Clojurewerkz seem wise and useful.

Are there any other recommendations of this kind?


I agree those were good guides. Maybe they were geared towards libraries, bacause I felt that some didn’t apply neatly to my biggest open source project (Calva). A lot depends on what kind of software you are providing, I guess.

And there are tons of ”it depends” in an answer to a question like this. :smile:

As with so many things I think that leveraging ones strengths and doing things the way one enjoys it is key.

The guides were especially good in that it started with stating a bare minimum.That said, I think the minimum might be a bit smaller than that. The amount of time I have spent on trying to instrument the Calva project along a lot of the things that is brought up in those guides is… I don’t want to think about it. Haha. But I have had so much good luck along the way, The project quickly gained attention and encouragement. Working hard with documenting, talking to users, scratching itches, greasing the contributor track, researching how things are done, and, of course, improving the product, all makes more sense when there are users and people wanting you and the project to succeed. So, applying a bit of Lean Startup to it all is good. Put in the work when there is traction.

Listening is maybe the most important thing. Stay super curious about what your users and contributors want. This is easier if it is clear how you are stewarding the project. So consistency and trying to communicate clearly is also good, I think.

I think I could go on about this. Might do later, even. Haha. But to someone wondering about how to steward his or her project, I’d mostly say: Use your empathy. Put yourself in your user’s and your contributor’s shoes. What would you appreciate about the project from their perspective? One way to go about it is to consider open source projects you like, as a user, and as a contributor. What about them do you like? Also consider projects you don’t like. What about them don’t you like? I think you’ll find success if you mix the answers to these questions with yourself, what you are good at and what you think is fun.

Also, if your project is for the Clojure community, you are in luck. It is uniquely friendly and helpful. When I announced Calva (on this site) I clearly stated that I was in over my head, that I didn’t actually know what I was doing. People encouraged the project anyway, maybe even more because of that. It was, and still is, amazing.

To some extent I think that The Tao of Calva is a bit of my answer to this question in general.


@PEZ this is so inspiring and helps so much!


i agree with @daslu, this is awesome! thank you for sharing!


The advice in the articles is good, but assumes you have a ton of users. Getting to that point isn’t a given. I think the main thing is to treat your project like a startup. The biggest mistake companies make is to think that their product has to be perfect before it can be released. That’s a moving target that’s impossible to hit. Minimum Viable Product is a good mantra.

Another good mantra is “shameless self promotion”. There’s a ton of projects out there, most of which are abandoned. The odds of people randomly stumbling upon your work is pretty low. You have to actively let people know what it is, what it does, and that you intend to keep working on it.

1 Like

I always feel bad about it, but you’re right. Even sharing updates periodically in the community channels helps a great deal.

1 Like

I think you as so right about sharing things early.

Some of my important experiences recently have been while sharing incomplete, broken, buggy projects with a group of friends in this community. The kind support, the user comments and the good advice that I got were so important at those stages.