How to get started into open source in 5 steps

This post somehow depicts my journey on getting my first 800 stars on GitHub in less than one year.

Disclaimer: This is a very introductory, 101 guide to open source. If you’re familiar with OSS and you’ve been doing it for a while then you can safely leave this page.

One year ago I was desperate to level up my coding game and I knew open source would help me with that. When you stop consuming and start creating software that more developers will use, your coding skills are rocketed to legendary levels. Now that you’re sold on the importance of contributing to open source, you might be wondering how to even start or how to get around all those daunting Git terms. I’m about to break it up for you in just 5 steps.

1. Pick a theme

This is the most difficult part. I know that coming up with a project idea is not an easy task. But, let me take some pressure off you: your first open source project will most likely not change the world in any way. For your first open source contribution you just need momentum, something that gets your engine started. So, don’t be afraid to build something that has already been built a bazillion times before. My first contribution, Notyf, is a dead simple JavaScript plugin to show toasts in a page. At the time of writing it has 434 stars which is more than I ever except for such a mundane thing that has been made 2 trillion times before. So, pick the first simple project that comes to your mind even if it’s been done before, otherwise you won’t get past this step.

Your first open source project will most likely not change the world in any way.

2. Create a project and a repo

This is a pretty basic step. Open up your terminal and run mkdir first-oss to create a folder and then add a simple README running cd first-oss touch README.md. Now go to the Repositories tab of your GitHub account and create a new repo. After setting up the details of your repo you’ll see a screen with some very easy steps to follow in order to have your code (a README file so far) pushed. Your repo will then look similar to this: https://github.com/caroso1222/test.

3. Write actual code

This is where all the magic happens. I can’t go into specific details because it all depends on what you’re trying to achieve. You have to set up the goals of your package, search similar projects and then try to copy as much good standards as you can. Remember we’re not trying to innovate with a complex breakthrough in software. We just want to get started.

If you’re creating a node package then you’ll likely have to expose an ES6 or CommonJS module so that the end user can import/require it and use whatever API you expose. If you’re creating a CSS grid system then you might want to start off by exposing a CSS file with several utility classes and also some sort of src folder with the full source built on .scss partials. If you’re building a python package then you might want to expose a .py with a class and several functions within it. If you’re trying to build an Angular plugin then you’ll have to expose a Module with your components, directives and/or services exported. If you want to build a vanilla JavaScript client side library then you can just set a global variable and expose your API as functions on that global.

If this sounds overwhelming to you, fear not. Bottom line is: most of the time you just really want to expose an API to whatever utility you built. A quick Google search will teach you just exactly how to do this. Just google something like “how to build a Java library”, “how to expose a Python module” or “how to expose a JavaScript plugin” and you’ll be get up and running in no time.

If you want to take just one thing from this post is: visit repos and read a lot (I mean a lot) of code. Reading well structured code from well written libraries will help you understand a bunch of things for your own library. Remember to always give proper credit if you’re taking code from someone else.

4. Write a good documentation

The latest StackOverflow developer survey shows that developers teach themselves through the official documentation of the software they use. This means documentation plays a pretty important role on any piece of code you want to put out there. What you want to do in this step is to edit the README.md to document the API you’re exposing. My biggest recommendation is to visit the libraries you use in your day to day job and check out how they document their projects. Learn from the bests and you’ll be one step closer to be the best.

Make sure you give a brief explanation of what your library does, how to install it, how to import it into a project, and how to actually use the functions/modules/classes you expose in your API. If you’re building some sort of UI library (whether it is for mobile or web) make sure you show a GIF of how the plugin looks like in a real project.

5. Publish to package manager

I remember when I was taking my first steps into development I always wondered how they made the libraries available in things like nmp bower pip gem. It was super obscure to me until I decided to publish something myself and it turned out to be easier than I expected. This is an absolutely mandatory step. If you don’t publish your library to a package manager then it’s very likely your library won’t have a single user. It’s not worth it to go into details about how to publish a package as there are trillions of tutorials online explaining how to do it.

Publish your package and then voilà, you have made your first contribution to open source!

If you follow these simple 5 steps you’ll have a well documented library on GitHub and published in a package manager. You’ve now set the path to become the next open source rockstar.

If you found this useful then hit the damn heart and share. Ping me any time at @caroso1222 and let me know when you create your first OSS project!