loading...
Cover image for How to Start a New Open-Source Project

How to Start a New Open-Source Project

bsoyka profile image Ben Soyka Originally published at Medium ・6 min read

Starting a completely new open-source project is a lot of work, but it's much easier once you know the basics, and it's 100% worth the effort.

This article aims to teach you everything there is to know about starting and maintaining an open-source project, but it is not focused on the programming aspect. Rather, you will learn everything from getting contributors for your project to maintaining it over time.


Why Open Source?

First of all, why should you even share your project's source code in the first place? There are many benefits to open-sourcing your project!

Working together

Great minds think alike, and the only way to attract those great minds is to share your work rather than keeping it under lock and key.

When you invite others to work on your project, your project can improve with the help of more great ideas and code from others.

Transparency

When potential users see that you share your source code, they'll have a certain sense of security. After all, if you aren't afraid to share the source, then it's fairly obvious you aren't hiding anything malicious.

Transparency also means that anyone at all can see how you accomplished your project's goals, and they may even use the same concepts in their own code.

Adding to your résumé

By making your project open-source, you're allowing potential employers (and anyone else) to see how you work.

Showing that you have a great open-source project under your belt can help you get a great job in the future.


What Are You Providing?

Before you even begin work on your project, there are two questions you should ask yourself. The first is, "What will this project accomplish?" Begin with the end in mind and have a clear vision of what your work will actually do.

The second question you need to ask yourself is, "Why do people need this?" Your project should provide some sort of value to others.

Don't just copy

An important part of providing a valuable resource is that it shouldn't be a copy of another project.

If another project with the same general features as your idea already exists, but isn't well maintained or updated, you may still be providing value to your users! The same applies if you want to add or change features to improve on the concept of another similar project.


Laying the Groundwork

You can't expect everyone to understand what you're trying to accomplish without a proper starting point. You have to lay some of the groundwork first if you expect others to be able to contribute.

Choosing a name

The name you pick for your project will represent your work for all to see. It should unique, easy to remember, and related to the project's goal.

For example, Sentry monitors apps for crashes and bugs. The name Sentry is easy to remember and clearly represents what the app does.

It all starts with a README

Start off by making a detailed and concise README file that tells the most important things about your project. Most people who see your project will start with the README, so it's important that you share all you need to share.

You'll know your README is complete when someone is able to use the basic functionality of your project without looking at the code or too much documentation.

The README should include what your project is, what it looks like in action, how to use it, and any other relevant details. Just remember that the README should be as short as it can be without being any shorter. You may also want to add in details on contributing and license information.

The Make a README website has a template you can use to get your README file started.

Getting the code started

It's a good idea to start coding yourself so others know a bit more about your project, what to expect, and if they want to lend a hand.

This also means you'll be able to publish a beta-type version of your project to increase visibility.

Begin with well-formatted code and even throw in some comments. This will help others understand the thinking that went into the code as well as what the purpose of the project is.

Picking a license

Without a license, no one will really be able to contribute to your project. A great resource for choosing a license is the website Choose an open source license by GitHub, which gives you great info on each license option available to you.

The most common licenses used in open-source software are the MIT License, the Apache License 2.0, and the GNU General Public License v3.0. Each license features unique permissions, conditions, and limitations, so it's always best to look carefully for the license that's right for your project.

Contributing guidelines

It's important to establish clear contributing guidelines so that others know how they can help out with your project. This is often placed in a file named CONTRIBUTING or CONTRIBUTING.md in the root directory to make the guidelines easy to find.

You may want to include information telling:

  • How to file a bug report
  • How to request a feature
  • How to set up a development environment and run tests

Your contributing guidelines should be kept short and sweet, while still mentioning everything that needs to be included.

Documenting your work

Even if you don't start off with much code, it's important to document everything you do from the start.

You can even make your documentation part of your project's source code so that other contributors can add to it when they add to the code.

Tools like GitHub Pages and Read the Docs allow you to host documentation on a nice-looking site for no cost at all.


Hosting the Project

Once you have a project ready to share, you'll need a place to share it. The most commonly used site for this is GitHub, although there are many other options such as GitLab or Bitbucket.

All of the sites listed are fairly easy to use, but you'll probably need to learn a bit about Git if you want to start an open-source project. You can take a look at the in-depth article "Getting started with Git and GitHub: the complete beginner's guide" by Anne Bonner for a fantastic tutorial on how to get started with Git and GitHub.


Drawing Attention

A project can only grow if other people want it to. You have to share your idea with the world so you can get a few contributors and users to get your project started.

Once your project gets going, you may want to share the news on Reddit, Hacker News, Quora, or other sites to attract a few users who are interested in what you have to offer.

GitHub issues

One neat feature of GitHub is the Issues section. From GitHub's guide page on Issues:

"Issues are a great way to keep track of tasks, enhancements, and bugs for your projects. They're kind of like email — except they can be shared and discussed with the rest of your team. Most software projects have a bug tracker of some kind. GitHub's tracker is called Issues, and has its own section in every repository."

One advantage of using GitHub Issues is that you can add the "good first issue" and "help wanted" labels to make issues more discoverable.

Sites like Up For Grabs (which is even open-source itself!) even aggregate issues with these labels to encourage others to contribute to new projects. This is one big way to get some collaborators on your project who want to help out.


Continued Maintenance and Development

Once your project picks up more steam, there'll be more to it than just writing code. If all goes well, you'll end up growing a sizable community around your project.

With a large community, you have to be professional and polite at all times. After all, the more people stay enthusiastic about your project, the more contributors you'll get and the more your work will grow. After some time, your project will grow to be the work of an entire community, not just you.

Here's a good guide on "Best Practices for Maintainers."


Conclusion

Starting an maintaining an open-source project can be a lot of work, but it's worth it. By sharing a new project with the world, you could be helping so many people, not just yourself. These projects can then grow to become something bigger and better, and you can get some happiness from knowing that you started something that people can depend on and help with.


Resources

Discussion

pic
Editor guide