Building a JavaScript library - part 3: open-sourcing

This is the third in a series of posts that discuss the steps taken to publish our library. Our previous post showed how we automated repetitive tasks. This post describes how we open-sourced our library.

Why open-source?

Before we’ll describe how we made our library open-source, let’s first ask: why ? What exactly are the benefits of making code open-source?

As it turns out, open-sourcing code has several advantages:

• You don’t have to do everything yourself. People all over the world can contribute (e.g. node.js has over 700 contributors). This means the software can be developed faster and cheaper.
• You benefit from the knowledge of others. They will find bugs you didn’t and come up with new ideas. Furthermore, they will help you improve your code, making you a better programmer.
• Your code becomes part of your CV. Not only does it demonstrate your skills as a programmer, it also implies you are passionate about developing software. Recruiters also actively scan open-source projects for potential candidates.
• You use open-source software everyday (even without knowing it), why not give back to the community? It is the right thing to do.
• It forces you to think on how to setup your project. If the code is difficult to work with or hard to build, you won’t find many people helping you.
• It is fun! Collaboratively developing software is one of my greatest joys in programming.

Of course there are also disadvantages to open-sourcing your code:

• People expect you to actively maintain your code. Not only will they expect you to fix bugs, but also to add new features.
• You can mistakenly publish sensitive data (more on that later).
• You can get into license trouble (more on this later too).
• Monetizing your software becomes harder.

We feel the advantages overwhelmingly outweigh the disadvantages, which is why we chose to open-source our library.

Preparing for open-sourcing code

Before we’ll actually open-source our code, there are some things left to do.

Write documentation

Although open-source code allows people to inspect the code to find out how it works, you should still write documentation. If you are not convinced of the benefits of writing documentation, try using a new library without reading any of its documentation. ;)

The documentation should at least specify:

• What functionality the library offers.
• How to use the library, preferrably using examples showing common use cases.
• How to install the library.

For open-source projects, the documentation should also contain:

• The license the code is released under.
• A description on how people can contribute.

A README file containing this minimal documentation should be stored alongside your source code for easy access. Note that this documentation file should be relatively small, people should be able to read it quickly.

Separate documentation website

If you feel that the minimal README file cannot describe your library in enough detail, you should consider creating a separate documentation website. The Hangfire library does precisely this, with a compact README to get you started but also a separate documentation website that goes into far more detail.

Documentation tools

There are many tools for writing documentation, such as Jekyll (used on getbootstrap.com) and Sphinx (used on docs.asp.net). One benefit of Sphinx is that readthedocs.org provides free hosting for your documentation!

To make things really open, you can also open-source your documentation! This is done by the aforementioned docs.asp.net, which contents are hosted on GitHub.

Note: some people use documentation generators like JSDoc or Doxygen, which generate documentation by parsing source code. While this is a convenient way to quickly “write” some documentation, it should only be used in addition to hand-written documentation.

Demos

A great way to show how to use your library is to create one or more demos. There are several websites where you can create HTML demo applications for free, but we particularly like:

• JS Bin
• JSFiddle

Of course, you should link to any demo applications from your README.

Note: there are also “Fiddle” sites for other languages/platforms:

• .NET fiddle (C#, F# and VB)
• Scala fiddle
• SQL fiddle
• Regex fiddle

You can find a comprehensive list of “Fiddle” sites at fiddles.io.

Choosing a license

When code is open-source, it is important for other people to know what they are allowed to do with it. This is defined by a license. If you need help choosing a license, check out choosealicense.com.

For our library, we chose the Apache 2 license, which lets other people freely use our code. The main difference with the popular MIT license is that the Apache license has better protection against patent issues. You should probably also choose the Apache license if you want to raise venture capital.

You should mention the license in both your source code and the README file, as well as include it in a separate LICENSE file.

Cleaning up

At this point, you should clean-up your code. As you are making your code public, why not make it as nice as you can? Note that if you have written tests, you should be able to safely refactor your code.

Having cleaned-up code is also in your best interest, as people are less likely to contribute code to your library if the code is hard to read or maintain.

Removing sensitive data

As part of the clean-up, please make sure that your code does not contain sensitive data like SSH keys or passwords. Even though GitHub has a page dedicated to dealing with sensitive data, a simple GitHub search shows that many repositories still contain sensitive data.

Due to the distributed nature of open-source software (anyone could have a copy of your code), published sensitive data must be considered compromised, so make sure to remove sensitive data from your code before open-sourcing it.

Hosting

Our last task is to decide where to host our code. As we use Git as our version control system, we are looking for websites that can host Git code. Luckily, there are several such websites:

• GitHub
• Bitbucket
• Codeplex
• Google Code (will be shutdown in 2016)

Hosting open-source code is completely free on all four websites. We chose GitHub mainly for its great collaboration options:

• Contributing code through through pull-requests.
• Keeping track of issues through the built-in issue tracker.

There are other benefits of using GitHub:

• As most open-source projects are hosted on GitHub, most open-source contributors are also on GitHub.
• An easy to setup wiki.
• Free website hosting.

Having chosen GitHub to host our code, we then created a repository for our library’s code. If you need help creating a GitHub repository, check out this tutorial.

Publishing

Finally, we are ready to open-source our code! As our code already was in a local Git repository, we just add our GitHub repository’s URL as a remote and push to it:

# Link our local Git repository
git remote add origin git@github.com:ErikSchierboom/knockout-paging.git

# Push local commits to GitHub
git push origin master

And with that, our code has been open-sourced.

Conclusion

Open-sourcing code is easy: just pick an online host and push your code to it. However, to create a great open-source project, you should write documentation, choose a license and clean-up your code. Although these tasks may seem like chores, they will give your project a much better chance at reaping the main benefit of open-sourcing code: getting help from others.

Our next post examines how we allowed our library to be installed through package managers.