The Journey to My First 100 GitHub Stars
The article is all about my latest project, espanso, a cross-platform text expander written in Rust. It talks about the story, which started with a simple idea, that led to my first 100 stars on GitHub, with a particular focus on development, website creation, and promotion.
My journey started on a warm evening in September. I was chatting with some friends on Telegram when one of them asked me to stop writing e’ instead of è. You see, the Italian language contains many accented letters, but using a US English keyboard as my daily driver, it wasn’t easy for me to type them. Suddenly, I had an epiphany:
I needed a tool to automatically convert e’ to è while typing.
I started searching on Google for solutions and it turned out to be a common problem, solved by tools known as text expanders. Basically, after configuring them with specific keywords, they replaced the text with something else as soon as you typed the right word.
At that point, the only thing left to do was finding the right text expander.
Soon after, I was disappointed. Most of the available solutions either lacked cross-platform support or forced you into some kinds of subscription. What I wanted was an open-source text expander that worked on Windows, macOS and Linux. Considering I had just finished my exams and I had a free month before the start of the lessons, I thought: let’s build my own.
As with most projects, the first thing to choose was the programming language. Considering the task, espanso had to be efficient, cross-platform and capable of interacting with many native APIs and therefore C++ was a great candidate. However, I had been wanting to learn Rust for a while and this was the perfect opportunity, so I decided to go with it.
Thereafter, I had to deal with the hardest problem known in computer science: choosing the name. Surprisingly, espanso, the Italian word for expanded, stroke into my mind immediately. After a quick Google search to make sure it wasn’t already used, I created the Github repository.
Development
I wanted to make a tool people liked, something to be proud of, and from my experience, jumping right into writing code is a recipe for disaster. Therefore, harnessing the power of pen and paper, I started laying out the basic architecture.
The hardest part was implementing the cross-platform keypress detection mechanism due to the many differences between Windows, Linux, and macOS. For the sake of simplicity, I won’t cover the technical details here, but let me know if you’re interested, it might be the topic of a future article :)
In the meanwhile, I had to deal with another beast, Rust. After reading most of the documentation and designing the architecture, I was ready to start writing some code. Easy right? Well, it turned out to be much harder than expected. Rust was very different from the languages I used to work with previously, such as C++ and Python. In particular, while being very helpful in most cases, the compiler was very picky, especially when dealing with shared data in multi-threaded code. I still remember an afternoon in which I spent hours trying to understand why my code didn’t compile. However, although being daunting at first, this is the price to pay for all the Rust guarantees, and after a couple of weeks, I was decently productive with it. In fact, I even started liking it a lot! :)
Fast forward a few days and my main concern was packaging. If I wanted espanso to take off, I had to make it easy to install on every platform. As it often happens, a simple thing for users hides a fair amount of complexity from the developer’s perspective. For each new release, I had to compile espanso for 3 platforms, create the Windows installer, push the version to different package managers, upload the artifacts, update the website and many other steps. It quickly became clear that automation was crucial to keep things manageable.
At that time, I was new to Continuous Integration. I knew what it was (more or less), but I had absolutely no idea how to use it. Google to the rescue, I started searching for solutions. Most of the early articles discussed a combination of Travis CI and Appveyor, which provided support for Linux, macOS, and Windows respectively. After a couple of wasted hours, I stumbled upon Azure Pipelines, the CI offering by Microsoft. Not only it supported all 3 platforms out of the box, thus saving me from the hassle of setting up two independent pipelines, but they also offered a very generous free tier for open-source projects. The following day, my CI pipeline was ready to do all the packaging for me, at the push of a button. Or rather, at the push of the master branch :)
Building the Website
After about a month in, the alpha version was ready. While being still full of bugs and unpolished, it was time to get some early feedback with a public release. For many projects, a simple GitHub repository with a well-written Readme is usually enough for this purpose, especially in the early stages. However, I really wanted espanso to do well, so I took it one step further and built a website.
At that point, the next decision was all about domains. Initially, I thought about placing it on my personal website as a subfolder, something like federicoterzi.com/espanso. Other than being completely free of costs, this approach would have had the additional plus point of boosting the SEO of my personal website as well. On the other hand, a custom domain would have looked more professional, so I headed to Namecheap.com to evaluate the possible options. Surprisingly, espanso.org was available for just 10$. Full of enthusiasm, I bought the domain and started building the website.
Nowadays, content is just one of the ingredients for a successful website. In my opinion, what many open-source projects lack today is an appealing design, which is crucial to gain the user’s attention in this increasingly distracting world. With that being said, developers often struggle to create good looking designs and I am no exception. Following the suggestions of a talented friend of mine, I started using a tool that can really help in this regard: mockups. Until this discovery, I’ve always designed websites by coding them directly. I was blown away with how easier it was to build great looking pages by designing them first before coding. My tool of choice here was Adobe XD, which surprisingly was completely free to use.
With the design at hand, I was ready to build the actual website. Many years ago, I would have probably gone with Wordpress, but I’ve come to hate it. It’s bloated, slow, vulnerable and, most importantly, requires a database. Therefore, I started searching for alternatives and I stumbled upon the concept of Static Websites. In a nutshell, a static website is a collection of HTML+JS+CSS pages that don’t require any dynamic backend, saving you from the hassle (and cost) of having a database. A tool that really shines in this area is Jekyll, that combined with GitHub Pages, can let you build your own fully-featured website, with blogs and other goodies, for free. After about a week, the website was online.
At this point, the majority of rookie developers would think we’re done. Source code is available on GitHub with a nice Readme and some GIFs explaining the features. Damn, we even have a website! What could be missing now? Unfortunately, one of the most important (and boring) things, documentation. The truth is, users not only appreciate good documentation, they expect it. Ideally, your users should never have to read the source code to understand what to do, as most would get discouraged and leave the project. Consequently, I spent a few (very boring) days writing the documentation on the website.
Finally, it was time to release espanso and get some feedback. I was determined to show the project to a wide audience, but I had to start from somewhere, so I asked a couple of friends to try it out first. As expected, there were some bugs I hadn’t noticed before that took me a couple of days to fix. Thanks to their great help, I was ready to promote the project.
Promotion
Developers usually have many talents. Besides the expected coding expertise, they are also generally good in other skills, such as problem-solving and planning. That said, there’s one particular task in which most are not very well versed: marketing.
Honestly, I find promotion to be one of the most boring things in the world. Ideally, after the long hours spent coding a good project, floods of people would start using it without any marketing. Sadly, this is not the case, especially in the beginning. Therefore, I had to promote espanso, but where to start? Over the years, I came to the realization that to promote an open-source project, there are mainly two options: articles and forums.
Articles are a very powerful way to introduce a project to potential users. They allow you to explain a problem, and how your product can solve it, creating a more intimate bond with them. That said, articles can be tricky. You can’t just shamelessly promote your project, you have to provide value to the reader. Tutorials, guides and even simple stories are a great example, in which your product is not the subject, but a mere accessory.
At this stage, we have to find the right people, the ones interested in the particular niche we are targeting. Forums are a great way to do so, as long as you provide value and avoid spamming. You should engage as much as possible with the community and post relevant content. In fact, articles are one of the best submissions you can make, provided that you stay on topic.
When it comes to Forums, my favorite place is Reddit. Other than being full of interesting posts, it’s amongst the few social networks in which users actually care about content. As a result, the overall quality is pretty high and readers engage in discussions regularly. Moreover, thanks to the many subreddits, it’s possible to find plenty of people interested in your particular niche. That said, there are a few very important things to keep in mind. Reddit is not a place for self-promotion. In fact, you should keep it at a minimum (below the 10% of your posts/comments) and provide value to the community. I’m personally quite active on Reddit, often trying to help people who are starting out with programming on /r/learnpython and /r/learnprogramming.
The first — very naive — thing I did was posting the espanso website on the /r/opensource. As a result, about 20 people starred the GitHub repo, and most importantly, I received some very helpful early feedback. Moreover, it started to create some buzz around espanso, as in the following days a couple of users started opening issues with bug reports and feature suggestions. It may not seem much to you, but for me, it was an incredible sensation. Someone actually liked my work enough to spend some of their time suggesting improvements, a thing which rarely happened before.
I remember a particular story that still brings a smile to my face. On the same day I published the post, a user on Reddit asked me about the possibility to install espanso from AUR, the Arch Linux package repository. I wasn’t practical at all, therefore I opened an issue on GitHub called “Add espanso to AUR”, as a reminder for myself. The following day, one of the users commented on the issue saying “Someone has added it”. I was mindblown! Someone with whom I never spoke before made the effort to publish it on the AUR. I immediately reached out to him expressing my gratitude and asking if he wanted to become the official AUR maintainer. Soon after, espanso had an official maintainer :)
After 3 weeks, I took another small step. As I said before, articles are a great way to promote a project, provided that you bring some value to the reader. One of the things I struggled with when developing espanso was the publishing process on Homebrew, the de-facto macOS package manager. In particular, I couldn’t find any online resource that explained the steps to publish a Rust binary, so I thought it might be a good topic for an article. I then published it on the /r/rust subreddit, starting a couple of great discussions with the users and gaining about 30 stars on GitHub (50 to go!).
At this point, I thought it could be the right time to publish on HackerNews, a great place to hear about the latest tech news and discover tools. The standard format to present a project to the community there is called Show HN and is often a simple link to the GitHub repository. Full of enthusiasm, I published the post and…. nothing.
After 8 hours, the post only got 3 likes and the repository 1 star. The worse thing was the complete lack of discussions, which were always pretty interesting on Reddit. I suppose this failure was due to a combination of bad timing and an average post title.
By pure coincidence, I discovered the great /r/coolgithubprojects subreddit, a place in which users would post interesting GitHub projects. After submitting espanso, I got a wonderful response from the community, started a few very helpful conversations and got almost 50 stars on the repository, finally crossing the 100 stars mark!
Conclusion
This was the beginning of my personal adventure with espanso, my first project to reach 100 stars on GitHub. I hope some of you found this article helpful or even just inspiring, as what I really wanted to achieve was to motivate young developers. Create a project and share it with the world! You may not be successful at first, but eventually, you will build something people like and that’s one of the best feelings ever.
Thank you very much for reading :)
