Open-Sourcing Today I Learned
Before we introduced Today I Learned, it was a small Rails application with a handful of posts. Few people within the company had even seen it.
Here is a screenshot of the site, pre-Hashrocket makeover:
We've decided to open-source the codebase. In this post, we'll cover the rationale behind this decision, as well as the steps we took to prepare. I hope it helps people who are considering open-sourcing their own work.
Open-sourcing a private project is a decision that deserves some serious thought. We've gotten a lot of requests to publish this code, so it was on our mind from the beginning. The application has even been impressively reverse-engineered in the meantime.
The idea was always intriguing because open-source is a core idea at Hashrocket. Our tools are mostly open-source, and we try to give back to that community.
A second argument was that some of the features of TIL are pretty nice— it is well-designed, includes Slack and Twitter integration, has an RSS feed, and features a very simple, useful post creation page. We wanted to share the implementation of those features.
That somebody else might contribute, including aspiring Rocketeers and junior developers trying to get into open source, won the day. If somebody used this repo as inspiration to build something new, that would be awesome. If that's your intention, fire away!
Step 1: Create Pivotal Chore
Because we used Pivotal Tracker to build this site, building a Pivotal chore to track the progress toward public release was our first step.
Here is our TIL Pivotal project:
Having something to attach commits to increases transparency. By adding
#[<Git SHA>] to each commit message, combined with a Github integration hook, all our progress could be tracked in the Pivotal story.
Step 2: Generalize Documentation
The TIL README was targeted at Rocketeers; generalizing it included:
- Adding generalized setup instructions and language
- Moving as many Hashrocket-specific variables into environmental variables as possible
- Adding contributing guidelines
- Adding a license
- Adding a changelog
- Tagging v1.0.0 via Semantic Versioning
Step 3: Cross Link
Synergy Alert! We wanted people to be able to find the repository from the site, so we added a link in the footer. We wanted people to be able to find the site from the repository, so we added a link in the Github repo.
Step 4: Scan the Repo
As a security precaution, we did a general audit of the site, upgraded to latest versions of Rails and Ruby, and ran Brakeman against it.
We also scanned the code for usernames, passwords, and API keys, removing a few files that were no longer relevant. This is pretty simple if you think about security from the first commit. If you do encounter a file in your repo you shouldn't have checked in, change your passwords and keys immediately, then follow this guide:
Step 5: Add Metrics
An open source project should have transparent metrics, so we added Circle CI, SimpleCov, and Code Climate to help evaluate our builds.
Step 6: Release
You are here. After completing all the other steps, we tagged the last commit and clicked 'Make this repository public' on the Github repo's settings page.
Today we covered why we open-sourced TIL and the steps we took to get there.
Thank you to everybody who helped build this application and its content. Thank you to our readers and retweeters. I hope people find the code interesting, consider building their own TIL or contributing to ours, and continue learning and communicating every day.