& Continuous Learning

Open Sourcing Software

I’ve been using open source software for many years, but I’ve never open sourced my own project. This blog is a record of my experience as I start this journey. The resulting project can be found at http://beanoh.org.

Where

First I had to decide where to store the code. There are several popular (Comparison of open source software hosting) open source hosting options. I chose GitHub (github.com) because I already had an account and I’m comfortable using Git. Furthermore, GitHub provides intuitive tools that make it easy to manage a project. I can setup an organization so multiple Source Allies employees can have commit rights on this project.  GitHub also has an integrated issue and feature tracking system that connects commits with tickets.Overall I am very impressed with GitHub.

License

Before I push my code into GitHub I need to choose a liscense. This seems very overwhelming. I’m not a lawyer so how can I understand what each license provides? I started by searching for comparison charts. Out of these results I found the following comparisons helpful:

• Comparison of free software licenses
• Open Source License Comparison
• open source licenses for dummies

I feel like I understand the differences a little better, but I would like to know what other open source projects are using. I found a list of the “Top 20 Most Commonly Used Licenses in Open Source Projects" (http://www.blackducksoftware.com/oss/licenses). With the comparisons and the ranking I am leaning towards the GNU General Public License (GPL) and the GNU Lesser General Public License (LGPL).

I went to ‘gnu.org’ to research these licenses and I stumbled across a page called Why you shouldn’t use the Lesser GPL for your next library. It says, “The choice of license makes a big difference: using the Lesser GPL permits use of the library in proprietary programs; using the ordinary GPL for a library makes it available only for free programs." In my mind this is a reason to use the “Lesser" license. I want to provide an open source project that can be used in any product. The “Lesser" license provides more to the community.  In all fairness it is worth mentioning that the ordinary GPL is designed to encourage developers to open source the software that uses these libraries. In my case I want to make my library available to anyone.

Now that I have decided on the license I am going to put the following disclaimer at the top of every file:

Copyright (c) 2011 Source Allies

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; version 3.0.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, visit http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt".

I also need to include a license.txt file at the root of my project that contains the full text of the LGPL.

Make sure you get the license in place before you start distributing or using the jar with third party organizations. In the case of consulting the partner may end up owning the product if it is not licensed properly. Why go to so much trouble to open source code just to have the right lost to a third party organization?

Setup GitHub

I already have a GitHub account, but I want to setup an organization to manage a team of developers. I am able to create an organization under my personal ‘Account Settings’ under ‘Organizations’. I clicked the ‘Create Organization’ button and followed the wizard. For more information visit https://github.com/blog/674-introducing-organizations.

Collaboration

I am curious how open source projects manage changes from non-committers. I found a great article at GitHub that explains how most teams collaborate within their site (http://help.github.com/pull-requests). In short, contributors outside of the core development team submit “Pull Requests". The project administrator(s) review these requests and decide if they want to merge them back into the code base. In my experience Git merging is fairly painless. This model allows anyone in the world the opportunity to contribute, while preserving the owners right to control the flow of changes. Too many chefs in the kitchen will ruin the food.

U-turn I started looking for “How To" open source software articles and books. I didn’t find very many resources. Everyone talks about how to use open source, but very few people talk about how to effectively open source your own software. Eventually I ran across “Producing Open Source Software: How to Run a Successful Free Software Project" by Karl Fogel (https://web.archive.org/web/20120117012129/http://producingoss.com/producingoss.pdf). This book is a collection of insights from a major contributor to the open source project Subversion (http://subversion.apache.org). I gravitated to this book because it is free.  Apparently Karl believes software and books should be available at no charge .

In the first chapter Fogel suggests that 90 to 95% of all open source projects fail. As the founding committer of Subversion, Karl has a little bit of experience leading a wildly successful open source project. “This book is about avoiding failure. It examines not only how to do things right, but how to do them wrong, so you can recognize and correct problems early." (p. 10) So it is time to look at my mistakes so far.

First, I have not selected a “good name" (p. 21-22). So what does “good" mean. The project names that I talk about are the ones that I remember. I am drawn to word plays like Mockito (mockito.org) which is a play on the drink Mojito. When I heard it I remembered two things, the punny name and it’s purpose of mocking.

Second, I need to develop a “clear mission" (p. 22 - 23). I have to admit that this idea of a mission statement is overwhelming to me. In order to put myself to sleep I googled a few corporate mission statements. Without referring back to their statements I would not be able to tell you what they were.  Ultimately they stated that they were super awesome organizations focused on making money. Nevertheless, what is a good and useful mission statement? Karl describes it as a “quick description".  A statement that helps the customer decide in 30 seconds if they are interested in your project.  He recommends that this statement be “prominently placed on the front page, preferably right under the project’s name." (p.22)  If we take a look at Mockito again they  state, right under their name, that it is “simpler & better mocking" (mockito.org). Traditionally I would consider this a tagline and not a mission statement.  Nevertheless, I know several company’s taglines but I don’t know a single “mission statement". So what the heck, why split hairs?

While it seems strange, the third thing is to “state that the project is free". (p. 22-23). I had to visit several open source project homepages to find an example of this.  I did find the phrase “open source’ in the first two sentences at http://subversion.apache.org. This does not seem to be a common practice, but it doesn’t take much effort to put the words “open source" in the description of the project.

Fourth, I need to take time to create clear documentation (p. 26-29). This just takes time. The obvious first step is a Getting Started page.   What’s more difficult is writing this from the perspective of someone that knows nothing about my product.  Fogel suggests that you do not have to wait until you have comprehensive documentation.  On the other hand, just write down some basic information. It does not matter if it is incomplete. Focus on helping new users get your product running.

New Direction

After reading this I need to slow down and make sure that we put our best foot forward.  We need a good name, logo, and well designed website. I need to clearly state what this software does. I need to put together some basic documentation that is easy to read and understand.

After some discussion we decided to setup a logo contest on https://99designs.com. This was very easy to setup and we got some amazing designs. I also went through every class and added javadocs. I put together some short screen casts with Camtasia (http://www.techsmith.com/camtasia/). This took a few tries, but the results were well worth it. Now I’m working on integrating all of this documentation into an intuitive and effective website design.

As a software developer it is easy for me to focus on the technical aspects of my software and neglect the presentation. While this may not be my initial focus I found that as a consumer I evaluate other projects in a few seconds based on how their websites looks. If I feel like it is interesting I start click through their site. If I don’t “get it" in a few clicks I move on. This evaluation period is extended if I have a recommendation from a friend or colleague. Nevertheless, I make snap judgments on aesthetics, not on the substance of the project.

If I know this about myself, then I need to make a reasonable investment in the initial presentation of this software. Even though our project will be distributed freely, we decided to spend money on the design to make sure our presentation matches the quality of our software.  Unfortunately it costs money to provide a quality open source product.

Conclusions

I have to admit that I have been avoiding this journey for quite a while. Between the licensing and the project administration I felt a bit overwhelmed.  Nevertheless, I am starting with a small pilot project that has focused and limited functionality.  I’m sure that there will be a lessons learned blog that will emerge out of this experience as time goes on.  Until then have fun sharing your code with the world and check out Source Allies newest open source project at beanoh.org.