DEV Community

Cover image for How I grew my open-source project to 1k stars 🌟
Max Shen
Max Shen

Posted on • Originally published at m4xshen.dev

How I grew my open-source project to 1k stars 🌟

Recently, my open-source Neovim plugin hardtime.nvim reached 1k stars on GitHub!

hardtime.nvim reaches 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:

README example

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:

GitHub Repo Table of Content

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

CONTRUBUTIN example

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:

Reddit post introducing hardtime.nvim

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:

Reddit comment introducing hardtime.nvim

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:

Hacktoberfest pull requests

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:

Reddit post introducing update of hardtime.nvim

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!

Follow on X

Top comments (12)

Collapse
 
litlyx profile image
Antonio | CEO at Litlyx.com

Congrats for real! I will share my open-source project here too! Maybe somebody can share some love to us too!

Open Repo on Github

Still congrats and great community you created!

Antonio, CEO & Founder at Litlyx

Collapse
 
mayor profile image
Mayowa • Edited

I just shared you some love on github :)

Collapse
 
litlyx profile image
Antonio | CEO at Litlyx.com

Thanks a lot!

Collapse
 
bladearya profile image
Amit Kumar Rout

Congrats on 1k starsπŸŽ‰

Collapse
 
m4xshen profile image
Max Shen

Thanks Amit!

Collapse
 
martinbaun profile image
Martin Baun

You said not to be shy so I'll share Goleko, the best project management tool in the world! He he :)
Also, big congrats on 1k stars! Curious to see how Hardtime does in a year. All the best mate :)

Collapse
 
dev_kiran profile image
Kiran Naragund

Congratulations πŸŽ‰
Btw nice article!

Collapse
 
m4xshen profile image
Max Shen

Thank you Kiran!

Collapse
 
alxwnth profile image
Alex

I’d also add that a step β€œzero” is making a useful project. Not much sense in promoting something that already exists or doesn’t have value.

Collapse
 
tankala profile image
Tankala Ashok

Congrats!!! I hope you soon you reach 5K stars and share your learnings with all of us.

Collapse
 
shricodev profile image
Shrijal Acharya

You've earned my like and a GH star 🌟. Great job with this plugin. I'm trying it out!

Collapse
 
tablepad profile image
Tablepad

Cool