Lessons learned from a popular open source project

Since its release in late 2011, Bootbox.js has grown to become by far the most popular open source repository I have on GitHub with over 1,150 ‘stargazers’ (formerly watchers) and over 200 forks. Let’s put this in perspective immediately: such numbers are a drop in the ocean and are in no small part due to the explosive popularity of Twitter’s Bootstrap framework, but they do provide enough of a critical mass—and a community—whereby it becomes important to keep things in order. This article discusses a few things I’ve learnt in the past year and a half which make managing the project that little bit easier.

Have a dedicated demo page

Whilst GitHub et al have made accessing your project quicker and easier than ever, there’s still no substitute for an instant-access demo page—or even better, a full on dedicated site showcasing what your project is and why it’s useful. Bootbox has evolved into needing (or at least benefiting from) its own dedicated domain: bootboxjs.com, which is linked to from the GitHub project’s description and again straight away in its README. This demo page immediately gets to the point of what the project does, why it exists and demonstrates its behaviour as quickly as possible. Simple stuff, but immeasurably useful and saves answering a great deal of basic questions.

Whilst you may feel like a domain is overkill for each project you host, bear in mind that GitHub offer the utterly fantastic ability to host a static site for each of your projects, completely for free. Out of the box you'll get a URL of the format username.github.com/project, at which point it’s trivial to point your own domain at it instead. This is all Bootbox does: feel free to peruse its gh-pages branch to learn more.

Adopt a versioning mechanism

Once you start offering code for public consumption you must have a way of controlling changes to it to make sure that your users know what to expect when they use any given version of it, and to make sure that they don’t accidentally upgrade to a newer, non backwardly-compatible version of it. Assuming you’re using some form of version control you do of course already have this, but git style commit hashes or SVN revision numbers are no substitute for your own versioning layer—they can provide the technical implementation of it (by use of tags and branches) but it’s up to you to manage release versions, alphas, betas and deciding which upgrades are ‘safe’ or not.

Bootbox adheres to a convention known as Semantic Versioning, proposed by GitHub’s co-founder, Tom Preston-Werner. This convention is both easy to follow and easy to implement and is as good as any—versioning is typically something you want to spend as little time as necessary worrying about, so in the absence of any preferred system SemVer is a decent bet. As a bonus if your project is typically used by developers they’ll already have an idea of what your version numbers mean.

Have a test suite

In the same way that versioning lets your users know about changes to your project, an automated test suite lets you know when that version needs to change. Fixed a bug and not affected any other tests? Bump the patch version. Added some new functionality but not broken any existing tests? Bump the minor version. Introduced something new and had to modify existing tests to make them pass? Bump the major version. Simple.

Of course, an automated test suite provides much more than an indication of compatibility—but in the context of how it benefits open source software this is a useful perk. Another major benefit is that anyone hoping to contribute to the project can make sure they haven’t broken anything along the way—or if they have, they can fix it. Nothing takes the stress out of reviewing a pull request than seeing tests covering the new proposed functionality, merging the changes in and verifying the test suite still passes.

There’s no excuse not to have a test suite (if the nature of your project allows it to have one), and you’ll immediately benefit from a more stable project and better quality contributions.

Let people know how they can contribute

Whilst rash, thin-on-the-ground bug reports are inevitable, you’ll generally find that people want to be as helpful as possible when submitting issues or opening pull requests. It helps everyone—not least you as the repository owner—if there is some written guidance on how to do so, even if it’s a few short lines in your project’s README file. If you’re using GitHub then you’re in even more luck: simply add a CONTRIBUTING file to your repository and it’ll prompt people to read it when submitting new issues.

Keep on top of your dependencies

Dependency management is a huge topic and one that in the web world is not particularly well solved yet (certainly not ubiquitously) despite recent efforts, but if you have any external dependencies then you must keep track of them. Towards the end of the 2.x.x series of Bootbox releases this is something which began to rear its head with increasing frequency—the dependency on which Bootstrap version people could use was far too lenient, leading to a spate of hard to investigate bug reports as users upgraded to newer, incompatible Bootstrap versions (some of which introduced their own bugs which cascaded into Bootbox). As of the 3.0.0 Bootbox release dependencies have been far more explicitly tracked and indeed have their very own section on the Bootbox website.

Don't be afraid to say no…

Receiving pull requests, issues and ideas is incredibly exciting and rewarding—ultimately it’s usually exactly what you’re after when exposing your lovingly-crafted project to the world, but that doesn’t mean you have to accept every request or implement every idea. At first this is something I found particularly hard to do for fear of causing offence, but it’s important to weigh up each suggestion and decide whether it fits your project’s roadmap or not. Rejecting a pull request can feel particularly galling but at least the author’s work can live on in a fork if they believe it has a real purpose. As long as you’re polite and make at least some effort to explain your reasoning, people will generally take it on the chin better than you might expect.

…but don't be too stubborn to listen

Similarly, when I first started receiving requests for functionality which I didn’t believe were suitable, I was perhaps a bit too quick to want to stick to my guns. I’m honestly not sure if this was a case of initial over-protectiveness or stubbornness, but either way it’s always worth taking the time to properly evaluate suggestions, even if your initial knee-jerk reaction is ‘no’. In wildly popular repositories with a team of core contributors this is less of an issue as functionality is decided in a more democratic manner, but in a typical smaller repository with one gatekeeper it’s worth trying to see every angle before making a decision.

Generally speaking

Keep your house in order. Granted much of the above can evolve as and when required, but once a project is out in the wild and open to contribution don’t be surprised when it comes, and know how to handle it when it does. Now go forth and open source!

Related Articles


There are currently no comments.

Comments are now closed.