What I Learned from Building My First Successful Open Source Project

If you are planning to start your first open source project or share some of your existing work to open source, there is plenty of support out there which will help you to get started. However, building a successful open source project requires much more than publishing your code to Github.

In this article, I’m going to share what I learned building a plugin called Serverless DynamoDB Local, which has become the most widely used DynamoDB plugin for the Serverless Framework with 200,000 downloads so far. If you don’t know anything about Serverless Framework or DynamoDB, its totally fine since the learnings I want to share is not specific to the project.

Ok, first of all, it’s important to understand the word ‘Success’ is different from person to person. For me, a successful open source project means, its widely used by others and is used extensively for the problem context. Let’s see some other ways of measuring an open source project success.

• Downloads from source repository or package repository.
• Github stars.
• Github forks.
• Active contributors.
• Active users.
• Community members.
• Usage information.

As you can see, the list goes on and on. Although the strategy in achieving above mentioned factors could deviate slightly, all the successful open source projects are better in most of them. So let’s directly jump into the insights on how to build a successful open source project.

#1 Build something you are using at first

When starting your first open source project, it is important that at least you are going to use it at first. This makes sure the project has a realistic scope and solving a real problem.

Start a project solving a current problem rather a one in future.

From the start keep the code changes in a public source repository like Github so that you can keep on adding improvements and new functionality. This is helpful to use the code from the code repository as a dependency rather keeping multiple copies of the open source project.

Also, make sure you include an appropriate open source license to the project. At the beginning make sure that the code is clean and readable so that it attracts new users and contributors for the project.

In addition, it is also important to evaluate the project’s dependencies not only limiting to code level but also considering the areas more likely to be changed and designed it appropriately.

When building Serverless DynamoDB Local, the initial version of the code was so simple and easy to understand. This was because I have broken it into multiple libraries where one handles the interface with Serverless which is the outer library called Serverless DynamoDB Local and a core library called DynamoDB Localhost which is a NodeJS wrapper around Amazon DynamoDB local Java plugin that includes the complexities. This helped the Serverless DynamoDB Local to evolve easily with the rapid changes introduced with Serverless Framework in its early stage by only requiring to change the interface library while core functionality nearly remained the same throughout.

#2 Documentation and examples are really important

Once the code is published to a repository, it’s important to update the documentation so that anyone viewing the project can understand its intentions and usage. If we take Github, the most common approach is to create a README.md file with basic documentation. You can add the additional documentation to a Wiki space and include the links in the README.md file.

In addition to the documentation having few example codes in the same repository or in another will help them to understand the usage quite fast. Therefore it makes more sense to provide samples not only to reduce the learning curve but also to explain different usage scenarios.

After developing the Serverless DynamoDB Local plugin, I have created the initial documentation and verified with a few people whether it makes sense for a newcomer to use the library only referring the documentation. Apart from that, few Serverless example projects were created which utilizes this plugin to run a Serverless full stack locally.

#3 Stable and free of vulnerabilities

This is one of the areas any open source project should be concerned. Unless the code is stable with adequate quality control, its highly unlikely the project will succeed since the users will be having limited knowledge on the source code in the beginning. It is more likely that some of them will become contributors to solve any future issues of the library after using the code for some time as users.

In addition to functional stability, it is also important to make sure that the code doesn’t have any known vulnerabilities. When using other dependencies it is more likely that you are using components with known vulnerabilities (see this article by WhiteSource on the subject). Therefore it is important to keep the dependencies up to date preventing any potential security issues.

Also, make sure providing guidelines on coding standards and also automated code quality evaluations with unit tests and linters, so that it becomes easy for others to contribute and follow the same standards.

When it comes to Serverless DynamoDB Local, since its a plugin component written in NodeJS, Github itself was helping in identifying and pointing out the vulnerable versions of the dependent plugin which simplified the overhead of finding them manually.

However, even in absence of automated and intelligent tools, it is important that you take additional measures ensuring the security aspects of the open source code so that its comfortable for others to directly using it.

#4 Build the community

This is one of the areas which clearly differentiates a successful open source project from the rest. When I say “community” it’s not only the users who use your code but also new contributors who implement new features, fix any issues and even discuss feature requirements for the sake of improving the project.

You might wonder, why others would put this effort if you have started the project? This is the beauty of open source where even you are the creator of the project you don’t own it. It’s important to accept this reality and facilitate others to involve in discussions and also allowing them to contribute more proactively since some of them might be using the open source project more rigorously compared to you where he/she is able to see a better picture ahead.

One thing you can do from the beginning is to start reporting the issues by yourself in Github issues and fixing them and updating the issue status building a process within the project. This creates a foundation for any new person to follow in reporting an issue or requesting a feature. Also, make sure you respond to all the issues posted by others and also providing fixes or addressing new feature requests timely so that the project evolves naturally.

In addition, make sure you put a contributor guidelines section in your documentation where you show that you are open for others to become a part of the project.

When I look back at Serverless DynamoDB Local, several important things I did in building the community involves setting up the process in reporting issues with labels (bugs, new features & etc.) which others used to follow and building a friendly culture with polite responses to messages and queries so that people are empowered to use the plugin as well as to contribute more often. During the early stages, I have also elevated the privileges of early active contributes in source control where they are able to commit the code as well as review other’s pull requests which provides more sense of ownership. There was a time where the entire library is almost rewritten by contributors to support a newer major version of the Serverless Framework which won’t happen if I was the sole user of it.

#5 Let others know

After you have built a stable open source project it is important that you reach out so that it becomes easier for others to find your project. This can be done in many ways, where you can improve in SEO for the documentation, build a website in pointing towards your project or even reach out to related websites in publishing information about your project.

For Serverless DynamoDB Local I have created an NPM repository which makes it easier for others to download the plugin and also published it into Serverless Framework documentation pages so that it gets visibility directly for the users that this plugin exists. In addition, I also used StackOverflow as a platform to provide answers with guidance to use this plugin to solve some development challenges for the questions people ask related to the Serverless Framework. This has created more awareness of the project around the Serverless community where it helped the evolution of the project.

Conclusion

In addition to all of the above, it is also important to do a background search to find whether there are existing open source project solving a similar problem. If similar one exists, it’s wise to either use it, ask for a feature request (If there are missing features you need) or take a copy and extend it yourself and later contribute back with your change if its useful for others, rather re-inventing the wheel.

If you couldn’t find one, then there is a greater potential for your open source project to succeed by doing the right things at right time. This is what happened to the Serverless DynamoDB Local plugin, which I have started to solve one of the development challenges in emulating Serverless development locally.

If you want to join the open source world, building your first open source project would definitely be a memorable experience. If you don’t have any idea in mind, start contributing to other projects which will give you plenty of experience on how open source ecosystem operates.

I hope this article will be useful for getting started with your first library. Without further due, start your open source project now!