Free as in Puppy — Open Sourcing Your JavaScript Code

It’s Open Source Week at SitePoint! All week we’re publishing articles focused on everything Open Source, Free Software and Community, so keep checking the OSW tag for the latest updates.

This article is by guest authors Christian Heilmann and Rita Zhang. SitePoint guest posts aim to bring you engaging content from prominent writers and speakers of the JavaScript community.

Open Source is much more than making something available to the public. It is not only about your code, it is also about licenses, understanding participation and herding cats a.k.a. dealing with community issues. In this article we will briefly look at the benefits of open sourcing your code and the pitfalls to avoid.

Open Source is probably the most exciting thing that happened to our market and is responsible for the explosive growth of the web. Most of our servers are open source technology, a lot of browser code is, and even our editors are written in JavaScript these days. It is our duty to treat Open Source with respect and release quality instead of chucking code over the wall and hoping that magic happens.

Open Source Is Free — as in Puppy

What follows are ideals and advice to follow. You might not have time or desire to follow all of it. That’s fine. What’s not fine is trying to play in an open world and be dogmatic about it. Open Source has mushroomed into a huge part of our world and people make mistakes. Let’s be as open as the code we release. Let’s deal with mistakes like we deal with bugs: collaboratively make them vanish.

Getting a free puppy is great but it also comes with responsibilities. You need to feed it, take it out for walks, groom it and play with it — even when you’re busy. The way you treat the puppy defines what kind of dog it will become. How much it trusts humans, how easy it is to play with, how protective and helpful towards humans it is. The same applies to releasing and consuming open source code. With one small difference: puppies are very forgiving. The open source community less so. There is a lot of tension to be aware of. We’ll cover some of that here, but first let’s point out an important thing when it comes to JavaScript and Open Source.

Javascript Has Always Been Available — but That’s Not Open

Just because something is available doesn’t mean it is free or open. If I forget to lock my bike, you’re not invited to ride it. If I put a sign on it saying “community bike, feel free to ride, but please keep it clean and fix it” we are getting closer to what open and free means in terms of software. The great thing about software is that it can be copied without losing quality. The great thing about JavaScript on the web is that anyone can see it. Many luminaries of JavaScript learned their craft by looking through other people’s code. That doesn’t mean though that you can copy and paste it and call it yours – unless its license explicitly allows you to. I’ve spent far too much time in conversations with clients where they asked me how to protect JavaScript from being seen by others. That’s like asking for water that isn’t wet. JavaScript is a great candidate language for releasing open source code. You are already visible; you may as well make it legal to re-use.

Benefits of Open Sourcing Your Code

Now, why would you bother to share your code with the world when you could become a millionaire by keeping it all to yourself? Well, there are quite a few benefits:

• Other people have good ideas, too. A lot of my code has been greatly improved by allowing people to contribute. They came up with solutions I hadn’t thought of. They helped me write terser, easier to understand code. They found issues I hadn’t considered. And I didn’t have to pay for any of that!
• It is a litmus test of your code. People have different environments than me and can test my code for me, inform me of issues, or — even better — fix them for me. It is impossible to hide sloppy code in plain sight. Knowing that I make my code available makes me worry more about code quality and thus a better developer.
• You become part of something bigger. Your code being used in other projects is a very exciting (and at times scary) thing. It is a great feeling to empower others to build things that they on their own couldn’t have built. As is seeing your work being used by people you thought were much better than you.
• Your work lives on — no matter what. If you’re unable or unwilling to keep maintaining your code and you want to move on, having open sourced it means you’re in luck. You share the responsibility with a community and they benefit from your initial work.
• You find like minded people to collaborate with. One of the huge benefits of open sourcing your code is that you find people who are willing to work with you on something you’re excited about. This is invaluable for finding new jobs, hiring exactly the right people or having a foot in the door of another company when you want to reach them. As a larger corporation, open sourcing your code means you can pick new hires from the contributing community. These are people who are already in the know and excited about your product. This cuts down on months of on-boarding and thus means a lot of money saved.
• You learn about tools of the trade. Releasing a JavaScript project these days has become much more complex than offering a zip of your script. There are all kinds of preset files for different editors, package managers and ways to automatically test your scripts. If you don’t want to get into all of that yourself, you can ask contributors to help you out. No need to get into the nitty-gritty of solutions you’re not comfortable with when you can share responsibilities.

As you can already see, a lot of these benefits are not related to writing code. They come from dealing with other people in a respectful and professional manner.

Things to Prepare Yourself for When Open Sourcing Your Code

Whilst this all sounds great, there are also niggles with Open Source to consider. You’re making your work and subsequently yourself open to the public. This means you need to prepare for a few things that may be hard to deal with at first.

• Strong opinions voiced badly. A lot of initial feedback you tend to get when you open source your products can be — to put it mildly — harsh and overly abbreviated. There are many people who have very defined and limited opinions on “how things should be done, or it is not proper Open Source” and get a kick out of pointing these out wherever they can. Don’t get disheartened by that. Look these people up and if you’re just one of many to get the same brutal response you know there is a different agenda at play here.
• Everybody has an opinion. There isn’t shortage on any open source project of comments, issues tracked or pull requests telling you that something should be done differently. The art here is not to give in to all of them. This is sometimes actually impossible. The trick is to throw it out to the vote and only apply them when enough people agree or disagree. Don’t chase after constant change — it will be a time sink you can’t get out of.
• It’s not about you any more. It is tough to let go of your work and see it going in different directions than you might have planned. Yes, directions – plural. That’s what forking is for. For the good of the project, you might have to give in to the wisdom of the masses. If changing how some part of your project works or is maintained yields lots of good contributors, it is worth it. Remember that by open sourcing something, you future proof it. If you’re not there for the project any longer, others need to take over. That may mean that you need to be OK with the project working differently than your initial approach.
• You will code less and write more. Once your project kicks off, you will spend more time answering issues and comments and looking over pull requests than coding. Your responsibility starts moving from writing great code to reviewing contributions ensuring that what gets added doesn’t include security or maintenance issues. Instead of battling a parser and VM, you start dealing with human agendas in exchange for code.
• You won’t do everything. Try as early as possible to delegate and trust people to do parts of the project without your supervision or control. This is tough at first but frees you to do much more later. If you start the project as a team, have defined roles and stick to them.
• This is no place for jealousy. One thing that can happen a lot is that your product will be used in other people’s products and they become a great success. It can even happen that a fork of what you did with a direction you disagree with becomes a much bigger success. In the worst case someone will make a lot of money with a commercial product based on your work. Or create something that will be bought by another company for a lot of money. Don’t get discouraged by that. There is a lot of randomness in this and it is not your mistake that made that happen. Stay in touch, be happy for the success of other people and good things will come back to you.

Licensing Matters

Regarding that last point, there is a very important part of open sourcing your products. And it is the toughest, most vehemently discussed and confusing part: licensing your code.

As a developer, most of us see laws, licenses and agreements as something we want to stay as far away from as possible. However, licensing your open source code matters in many ways:

• You protect yourself. A clear license doesn’t only make sure that people can’t use your code in ways you didn’t intend. It also means that a security breach based on your software doesn’t land you in jail, as this is clearly covered in the license.
• You define the level of re-use. Depending on the license, you define if people can build commercial products based on your work or not. You define if people need to list you as a contributor to their projects or not. You make sure that some uses of your code are illegal, whereas others are perfectly fine.
• You give a clear message who can contribute. Hard-core contributors of Open Source won’t work on projects with a certain license. Commercial users of open source projects can’t use code unless it has a license that allows them to. By picking the right license you limit or extend who can work on your project. It also protects you from other people getting rich with your work without getting a share.

Luckily, the plight of picking the correct license has been a constant discussion in the open source community. There are a lot of great resources to work from, like http://choosealicense.com, https://tldrlegal.com or https://tldrlicense.com. Be sure to choose wisely as changing a license later is tough, and sometimes impossible.

Being a Great Open Source Publisher

If some of this sounds daunting, don’t despair. It is not as tough as it sounds, I just wanted you to be prepared for what’s coming your way. And I wanted to ensure that releasing something open source is not about making it available. It is not you giving the world a gift. It is you sharing your work with the world and being open to changing it in the process.

That way I wanted to ensure that in order to be great open source publisher, you can add some extra work to your initial release to make sure that people can help you and you don’t run into some very obvious mistakes that result in discouraging initial feedback. A lot is about answering questions before they come up. So here goes:

Planning for Contribution

With GitHub, we get an incredible tool to release open source software these days. Not only do we get Git, a tool to contribute code safely without overriding each other’s work. We also get an issue tracker, a Wiki to explain and write docs and GitHub Pages to show an executable version of your code right where the source lives.

In order to make it as easy as possible for people to contribute, it makes sense to have a few things in place:

• A great README. This is the first thing people look at. Explain early on what the project does and who it is for. Point to all the other parts listed here and make sure to keep it up-to-date with the latest information.
• Information on how to run it. Most developers won’t contribute to a project they can’t run themselves. Make sure you define how to try the project yourself, listing all dependencies and environment setup necessary.
• Have a sensible changelog. It shows how you fixed issues, added features and the overall cadence of the project.
• Code guidelines. Describe briefly how you coded the product, what your settings and environments are to ensure that code contributed complies with this. This may spark some discussion, but it makes sure the final product is much easier to maintain.
• Tests. Have ways to automatically test your code and run a series of tests before contributing. This makes sure that contributors have an extra step to take before submitting code that breaks the whole project.
• Feedback channels. Give people a chance to contact you outside of the normal development flow. This gives them a chance to report bad behaviour of others, ask you about commercial agreements, or just say “thank you” without adding to the noise of already busy communication channels.
• Contribution guidelines. Explain how to write a pull request or issue that is most likely to cause the community (which initially is just you) to deal with them as painlessly and quickly as possible. There is nothing worse than an issue that lies unanswered or with lots of “we need more info”. The less unanswered issues, the more inviting your project is.
• Beginner bugs / features. If you have a way to flag up simple problems as “beginner bugs”, do so. This is a great way for someone new to join the project and learn about it whilst fixing a small issue. It feels good to get into a group by removing an obstacle — however trivial. Much more than just trying to find a foothold and being overwhelmed by how great everybody else is.
• Consider a contributor code of conduct. This may sound over the top but defining what you expect and not expect people to say to one another is a good start to get a healthy and creative community. It also allows admins to block people from contributing without any drama as there is a clear guideline.

Not all these are strictly necessary and sometimes are overkill. They are a great help though for your project to scale and grow. If you want to see a great example repository with all these things in place, check out Microsoft’s Visual Studio Code on GitHub. If you’re thinking about a Code of Conduct, the TODO group offers a template.

Scaling for Commercial Use

It is great to see your product used in a commercial product. If someone like Google, Facebook or Microsoft uses your script, it is quite the boost. However, this also means you need to ensure that certain things are in place, or there is no way for this to happen. These are generally great things to have, but they are a show-stopper for commercial users unless you provide them.

• Make sure your product supports internationalisation. Have a way to translate strings, make sure the layout can shift from left to right to right to left. Allow for support of non-ASCII input.
• Make sure your product is accessible with various input devices. Accessibility is a legal requirement for large corporations and it will get audited.
• Make sure your product is not fixed to one environment. Sometimes a big player would love to use your product, but can’t as you developed it for your computer, not the world at large.
• Make sure your product has a license that allows for commercial use. This should be obvious, but many products can’t be re-used because of an initial license that is too strict.

If you want to learn more about this, there is a great talk by Chris Dias at Enterprise JS about how Microsoft built Visual Studio Code on top of open source projects and the problems that caused.

Open Source Is Communication

With all that out of the way, I hope you are still up for releasing your work as Open Source. It is not only good for your code; it is also great for you to grow as a contributor to our market.

Releasing Open Source means you get known and take on more responsibility. Having a successful open source project is a stepping stone into great jobs with more responsibilities. You show that you care and that you want to do more. Herding a community around your project and dealing with feedback and contributions is great exercise for a role of lead developer, team lead or department head. You push yourself to be more of a human developer than just a code developer. When I hire developers who worked on Open Source, I look how they interacted with others. I prefer hiring those who work well with others to those who created the most amazing contributions. Scalable teams need people to work with each other. This is a great way to work on that skill.

But what about you? Are you contributing to Open Source already? If not, what’s stopping you? Let me know in the comments below.