How to Run a Successful Open Source Project Image

How to Run a Successful Open Source Project

Determine the goals

Every open source project solves a specific problem. Talk with colleagues, chats, forums, and share your idea. It all helps you on the first steps to understand important things, like which solutions already exist, and to hear criticism. Talk with people who already have open source projects. They can give you very valuable advice, so don’t be afraid to ask and take the initiative.

One important bit of advice which I got at that stage is to pay attention in the first place on the documentation of the project. You can have a very good project, but no one will spend the time to understand how it works.

The most important aspect, without which further steps are impossible, is motivation. The idea of the project should inspire you primarily. Most often people get used to the tools with which they work and fall into a comfort zone, so external opinions may be ambiguous.

Planning

The choice of a certain task manager is a matter of taste. It should have a clear picture of the tasks and stages of your project.

Divide tasks into sub-tasks. Ideally, if one task does not take more than 3–4 hours, it is important to enjoy the implementation of small tasks. This will help to avoid burnout and loss of motivation.

I use pivotal tracker. The main advantage is a free version for open source projects where you can sort tasks by type (feature, bug, chore, release), and group them into releases and determined deadlines.

Documentation

Every open source project should contain these things:

  • README
  • Open Source license
  • Contributing guidelines
  • Changelog

The README file not only explains how to use your project, but also the purpose of your project. If you do not know how to properly write a README file, you can look at other known open source projects or use a template.

The license guarantees that others can use, copy and modify the source code of the project. You need to add this file to each repository with your open source project. MIT and Apache 2.0 GPLv3 are the most popular licenses for open source projects. If you are not sure what to choose, you can use this convenient service.

The CONTRIBUTING file will help other developers contribute to the project. At the first steps of the project, it is not necessary to pay close attention to this file. You can use the already prepared template from another project.

Changelog contains a supported, chronologically-ordered list of significant changes for each version. As with the CONTRIBUTING file, I do not advise paying special attention to this at an early stage.

Versioning

To track important changes for users and contributors, there is a semantic version. The version number contains numbers and adheres to the following pattern X.Y.Z.

  • X major release
  • Y minor release
  • Z patch release

Continuous integration / Continuous delivery

To automatically run tests and build, I use Travis CI. It’s also a good idea to add badges to display the successful assembly of the build in the wizard, the test coverage (Codecov), and the documentation (Inch CI).

How to Run a Successful Open Source Project Image

After each new commit or merge in the master, I automatically have a deploy on Heroku (very convenient integration with GitHub). All tools are absolutely free for an open source project.

My mistakes

To analyze the initial stage, I had an idea, but there was no clear plan. I decided that I wanted to do this without having a clear idea of how much time it would take or a specific representation of the functions that would be in the first version of the library. I had just a lot of desire and lack of a clear plan.

Also, after reading the history of other projects (not only open source), I noticed that at an early stage, some plans are too optimistic. They need a reassessment of their strengths and capabilities. But it’s not easy to find time each day to write a new feature in the project. Most of the tasks eventually had to be weeded out, leaving the necessary minimum for MVP.

At the moment my simple-admin project is in the alpha version. Further plans include creating a separate version of the library for Hanami.

 Put an accent on quality

Most developers work in closed-source projects. Except for your teammates, most likely a few developers are going to read your code.

But the situation is different when your code is opened for everyone.

The truth is a lot of open source code is not the best quality. Nobody wants to depend on code that is difficult to understand, unstable and full of bugs.

In this regards a good way to increase trust and demonstrate the quality of your open source project is testing it. You might need to have at least 80% of code coverage.

You can even go further and put some badges on README.md to demonstrate that the codebase is fully tested.

The readability of the source is also an important aspect. If you want at later stages to attract more contributors, the code must be readable and well structured.

Additionally, the open source tool will only benefit from implementing non-functional requirements:

  • Have an intuitive, configurable and extensible API
  • Support a wide range of environments (cross-platform, cross-browser, etc)
  • Provide the possibility to cherry-pick functionality
  • Have few but ideally no dependencies
  • Have small build size

Excellent README.md and documentation

Ok, you followed my advice, found a decent problem and implemented a relatively good solution. Is it enough?

Unfortunately, only half of the job is done…

README.md file is the entry point of the project. And if you struggle to explain concisely and exactly what the project does, people will hardly understand its mission and will bounce-off.

In case if README.md lacks details, you might think that developers are going to dive into implementation details and find by themselves how to use the tool. Usually, that’s not going to happen because nobody likes deciphering code.

What everyone expects is to understand what problem your tool solves and how to use it. That’s all.

Conclusion

A successful open source project requires a lot of time and commitment.

First of all the project must solve a problem, and solve it good. Developers are searching for good solutions for their problems.

You must invest about 50% of the time into creating quality README.md and detailed documentation. Tool usage should be effortless as much as possible for the user.

Having a decent code coverage builds trust in the quality of your code. Do not forget to invest in non-functional requirements also, like supporting many environments and have few dependencies.

Similar Posts

0 Comments

No Comment.