Yesterday was a roller coaster ride. I woke up in the morning, fleshed out a quick README file, took a screenshot and a screencast, and launched my very first open source project. The project is called Waldonow, but it released under the name “VimAck”, and it was under that name that it hit the front page of Hacker News.
In the meantime, The repository has 105 watchers, I’ve merged three pull requests, I’ve implemented 2 new features, and also released two new versions. All in the span of 20 hours. Like I said, roller coaster ride.
I’ve had some time to think about my experience overnight, and I’ve already had to learn a bunch of lessons I thought I’d share with you.
Be your own QA department
When I released version 0.1, the search button was labeled “Button”. I had shown the app to 3 friends before releasing it, but everyone assumed I would change it before release. I even took a screenshot/cast with it and even published it live! I wouldn’t have even noticed had it not been for a friend on twitter. Basically, what happened was that I assumed it worked for the simple case I was developing it with and was so focused on getting it to work I forgot to actually change the label.
I’ve gotten better at with version 0.3. Before release, I go through both the installation, setup, and usage process, as well as the upgrade and usage process. The only person you can trust is yourself and that’s the only way you can ensure everything is running smoothly.
Something I do want to work on though, is automated testing. This is my first real Cocoa project and I’m not familiar with how testing is done, and it’s something I have to learn.
Takeaway: Rely on your own tests to ensure that things are running, and do it all before each release.
Choose a name wisely, and stick to it
VimAck, the name I released under, was chosen as a working title, and I was so involved in building the first version and caught up in the feedback it released, I forgot to change it.
It’s a terrible name. I couldn’t ever remember whether it was VimAck or AckVim, there was already a similar vim plugin called ack.vim, and it just sounded bad.
But here’s the problem with renaming a released project: People have already forked the old repository, links all over are pointing to the old repository, and Sparkle has problems updating to a different app name!
I’ve decided to take the hit early, after all, there were only 7 forker and 80 watchers at the time, and it’s better to do it soon rather than get stuck with a terrible name in the long run.
Takeaway: Changing the project’s name is costly, consider and reconsider your project’s name before launch.
Lower the barrier to contribution
In my opinion, one of the most rewarding aspects of open source software is receiving contributions from the community. A pull request is both a validation that you have created something of value to other people, and that you have created an ecosystem that encourages other developers to pitch in.
For example, zef came up with the great idea of auto-installing the vim plugin on launch. That was something I hadn’t thought of myself.ashchan did the work to make Waldo show up as a status menu item. That is something I had wanted to do, but didn’t know how.
However, you can’t expect people to come up with contribution ideas themselves, which is why I added a “Roadmap” section to the READMEon Waldo and outlined the upcoming features. I also commented the most code-heavy files in the project and outlined to people how they can contribute.
Takeaway: Do as much work as you can to streamline the contribution process to your users.
Your first release should be a full package
The first release was really only for me to show off my weekend project. What I didn’t anticipate was 100 people to watch it, and 120 people to download it. The problem with releasing what was essentially a demo, is that it wasn’t a full package. What I mean by package, is that it not only has support for the core set of features, but it also has a mechanism to update, an icon, a web presence, a way for people to contribute, and a way for people to file bugs.
Github takes care of most of those problems. Github is truly one of the best things to happen to open source software. I don’t think it’s hyperbolic to say that the world of open source would look a lot different without it. What I didn’t do, however, was include support forSparkle.framework which meant that for people who wanted to upgrade to VimAck 0.2, they have to know that there’s a new version, and they have to manually download it.
To add insult to injury, the renaming of the project from VimAck to Waldo meant that the upgrade mechanism doesn’t work. Hopefully nobody will face these issues anymore and everything will be smooth sailing from here on forth.
It still doesn’t have an icon, but that’s because I haven’t come up with a good idea for one, but would love to have someone contribute one for me.
Takeaway: Provide a complete package to your users, not just a demo.
Be upfront with your users
The problems with Sparkle and with the renaming caused a lot of headache. For one, a pull requests was broken and was tough to merge, people who forked had bad remote URLs, and people had to upgrade manually from 0.1 to 0.2. As a user, this experience sucks, and there’s no way around it. As the care-taker of the repo, I felt like my trust with the contributors was broken. To amend it, I messaged everyone who submitted a pull request and told them what happened, and I also set up a placeholder README on the old VimAck repo with instructions to people who forked on how to update their repository.
I felt like the communication is especially important in the open source space and it helped people figure out what was happening with the project. Communication is essential since you have people in different parts of the world trying to touch the same codebase and having a clear narrative is essential.
Takeaway: When you make a mistake, ’fess up to it, and provide remedies.
Conclusion
The project is only a day old, and I continue to learn a lot about project management, community building, and communication in general. I hope you can take away a thing or two from my experience with open source. It is incredibly satisfying to see people appreciate and use your software and I thank everyone who helped fork/contribute and those who downloaded!
Majd Taby 