Recently, my open-source Neovim plugin hardtime.nvim reached 1k stars on GitHub!
I think it’s a good time to share what I have learned about promoting an open-source project. I break down the process into three stages: preparation, promotion, and maintenance. Let’s dive in!
Preparation
Before promoting your project, make sure it’s ready for the public. Here are some things you should prepare:
1. README
README is the first thing people see when they visit your project. Make sure it’s clear and concise. At a minimum, it should include:
One-sentence description of the project
Demo GIF or screenshot
Features of this project
Installation guide
Usage guide
The first two are the most important. They make people quickly understand what your project is about and how it looks like so that they are more likely to continue reading the rest of the README. Here’s an example from my project:
For the rest of the README, it might be difficult to write a good one from scratch. Don’t worry! You can look at other popular projects in the same domain to get inspiration.
For example, I am inspired a lot by the README of lazy.nvim. Learning from other’s success is a good way to improve your project.
It is also important to separate the content into sections using markdown headers. GitHub will automatically generate a table of content, which makes it easier for people to navigate:
2. Contribution guide
If you want people to contribute to your project, you need to provide a contribution guide. It should include:
How to set up the development environment
The coding style of this project
The format of the commit message
What issues are good for beginners
3. Issue template
When people start using your project, they might encounter bugs or have feature requests. To make it easier for them to report issues, you should provide an issue template.
You can create an issue template by following this GitHub docs.
This ensures users provide enough information for you to reproduce the issue and fix it, which makes your later maintenance work easier.
Promotion
After preparing your project, it’s time to share it! Here are some strategies you can use:
1. Share with the community
You can share your project on the platform where your target community is active. For example, the Neovim community is pretty active on Reddit, so I shared my project on the r/neovim:
When it comes to sharing on social media, it is crucial to provide a visual element. People are more likely to click on a post with a GIF or image than a plain text post.
For the detail explanation of your project, you can post it in the comment section:
Also remember to engage with the community. If someone asks a question or gives feedback no matter it’s positive or negative, make sure to respond to them. This shows that you care about the users and are willing to improve the project.
2. Write articles
When I say write articles, I don’t mean you have to write a post about your project. Often, people are not interested in reading a post that is just a promotion of a project. Instead, you can write articles related to the problem your project solves and mention your project in the article.
For example, I wrote an article about practical Vim command workflow. In the article, I share my experience of using Vim operators and motions and how they help me become more productive. At the end of the article, I mention hardtime.nvim as a tool to help establish good command workflow.
In this way you provide value to the readers and promote your project at the same time.
3. Hacktoberfest
Apart from actively promoting your project, you can also leverage events like Hacktoberfest to attract contributors. Hacktoberfest is an annual event that encourages people to contribute to open source throughout October.
By tagging your project with hacktoberfest and providing issues that are good for beginners, you can attract more contributors to your project. Here is an example of the pull requests I received during Hacktoberfest:
Maintenance
Building an open-source project is not a one-time thing. You need to maintain it to keep it alive. User feedback, bug reports, and feature requests will keep coming in, and you need to handle them properly.
Using issue labels can help you organize the issues. For example, you can use bug, enhancement, good first issue, etc., to categorize the issues. This makes it easier for you to prioritize and work on them.
After a while, your project might develop more features or even release a major version. You can then get back to the promotion stage and share the updates with the community.
For example, after my first post about hardtime.nvim, I worked on the users’ feedback and added some new features. I then wrote a new post few months later to share the updates:
Just make sure the update are valuable to the users. You don’t want to spam the community with minor updates that don’t bring much value.
Conclusion
That’s pretty much it! I hope you find these tips helpful for promoting your open-source project. Remember, building an open-source project is not just about writing code. A good project is useless if no one knows about it. So don’t be shy, share your project with the world!
If you like this kind of content and want to see more of it in the future, consider following my X to get notified when I post new content!
