Justin French on Maintaining a Wildly Popular Open Source Plugin

by Justin French & Natasha Postolovski.

Justin French heads up the Design & UX team at Envato. In addition to being a product mastermind, Justin is an accomplished Rails developer, passionate contributor to open source, and frequent wearer of black T-shirts. In the open source community he is best known as the creator of Formtastic, a super popular plugin for the Ruby on Rails framework that helps Rails developers build better forms faster, with less boiler plate code. The repository has more than 4,400 stars in Github, and over 180 contributors.

In this post we'll delve into Justin's experiences creating Formtastic, from idea to public release. We'll also learn about what it takes to maintain and grow a popular open source project.

NP: Why did you initially decide to create Formtastic?

JF: There were a few key things happening at the same time that pushed me towards it.

I was working on a new product with a lot of data entry screens — it was a core part of the experience, so I was intensely focused on designing and building these forms every day, thinking about this stuff a lot, and getting frustrated.

The built-in form helpers in Rails are powerful, but they’re also quite basic building blocks. It makes for nice neat demos, but when you start building fully-featured and well-designed forms you quickly find yourself adding a lot of structural code. Building forms in Rails was better than any other web framework I’d tried, but writing all that repetitive code got really old, really fast.

I started digging into the Rails code and discovered that it was written with this in mind. Rails came with a default form builder, but you could write an alternative form builder that suited your application. None of the existing examples in the wild suited my needs, but I now knew what was possible, and that there was a supported place in Rails.

Then Aaron Gustafson gave a talk at Web Directions called Learning to Love Forms. He showed us a way to use semantic mark-up and existing CSS layout techniques to achieve semantically rich, accessible and beautiful forms without resorting to tables or other hacks. This was way back before Bootstrap, Foundation or any other CSS framework, so I also viewed Aaron’s work like a proposal for a standard — an opinion about how forms should be marked-up and styled that didn’t already exist.

This was way back before Bootstrap, Foundation or any other CSS framework, so I also viewed Aaron’s work like a proposal for a standard — an opinion about how forms should be marked-up and styled that didn’t already exist.

I sat down and designed the syntax I’d like to use to achieve that mark-up inside a Rails app. I wrote a few lines of code, which lead to a few more and a few more — the rest is history.

NP: How long did it take to build the initial version?

JF: I have no idea! I think I had a really rough proof of concept within a few days, and I think we were using it internally straight away. There was a 5 month gap between Aaron’s talk and the first public commit, so I guess it took a couple of months of occasional work to get it to the point where I was prepared to extract and share it.

Looking at the commit logs and tags, things got pretty stable and interesting in October 2009 when we shipped v0.9.0, but it looks like it took a long time to finally ship 1.0 in August 2010. The reality is that so many people were using it in real-world apps we should have shipped 1.0 much much earlier, but this is what happens with side projects!

NP: Did it start as a personal project, or did you always plan to release it as a plugin?

JF: It did start out as something reusable and portable (like a gem or a plugin), but this was never a personal project. From day one, the code was attached to the realities of a real production application with a real team, real requirements and tight deadlines. Much like Rails itself, Formtastic wasn’t an academic exercise with imagined requirements — it was built alongside and extracted out of real working software. I think this is crucial to the success of a library or framework.

Much like Rails itself, Formtastic wasn’t an academic exercise with imagined requirements — it was built alongside and extracted out of real working software. I think this is crucial to the success of a library or framework.

By the time I extracted the code to a separate repository and made the first public commit on Github, I knew I’d use it in multiple projects, and I hoped it might be useful for others. We converted it to a gem when Rails started embracing gems for its plugin architecture.

NP: Formtastic now has more than 4.4k stars on GitHub. What would you suggest other developers can do to help their open source projects get more attention?

JF: Most importantly, I think Formtastic solved a real problem or pain point for a lot of Rails developers — especially those with less experience designing and building forms.

Formtastic was opinionated from the beginning, and offered you a great boost in productivity if you had no idea what you were doing, or if you liked the trade-offs and decisions we made for you. For my own projects, I was building new, fully-featured, production-ready forms in minutes instead of hours. It felt great to be shipping features faster and more consistently, so I can only imagine this is what other Formtastic users felt.

I also treated and marketed Formtastic like a real product. If you look way back to the README from the first public commit, I was selling benefits instead of features. I focused on what Formtastic meant to Rails developers — how much better it could be for them. I spoke at local Ruby meet-ups, I did some private coaching and consulting to onboard teams, I blogged, I offered help on Twitter and kept focusing on what Formtastic meant to developers — the benefits and even the downsides they would have from using it. The README itself was one of the first things I wrote. I spent a lot of timing thinking about how I would want to build forms and the way I would explain it to my co-workers. There’s a whole movement around README Driven Development these days, but it was novel for me at the time.

I also treated and marketed Formtastic like a real product. If you look way back to the README from the first public commit, I was selling benefits instead of features.

When we talk about “attention” I guess we’re also talking about adoption a bit as well. For adoption, I think it was important that we didn’t modify Rails’ default behaviour in any way. This made it really easy to try it out in a new or existing application with very little risk or downside. It was also important to be really open to contributions. Quality can drop and you have to make more compromises, but when people are ready and willing to help, you have to let them run with it as much as possible.

There’s probably a lot more to it that was out of my control, like luck, timing, being featured in blogs, podcasts, tutorials, etc.

NP: In the gem docs, you mention that over 180 developers have contributed to Formtastic. What are your tips for managing such a wide variety of contributors? How do you ensure the process is as smooth as possible?

JF: Github’s pull request feature and the “Github Workflow" is the real enabler here — it’s a pretty consistent process for contributing to almost all Github projects, and I just had to make sure developers knew their contributions were welcome, and what we expected in terms of documentation and testing. The big challenge is in curation. Many people are willing to contribute a quick patch, but they can lose energy and momentum quickly if their patches aren’t accepted right away, or if changes are required.

Many people are willing to contribute a quick patch, but they can lose energy and momentum quickly if their patches aren’t accepted right away, or if changes are required.

I’ve definitely struggled with this, and it’s a tough balance to get right. Holding out for perfect patches often leads to a lot of waste and unfinished work, which obviously isn’t great. On the other hand, accepting everything leads to bad design decisions, a drop in quality, missing documentation, and features that have to be supported for a long time.

Well-structured, approachable code helps too — I haven’t looked at the hard numbers, but it feels like we lost a lot of momentum in the middle, but it picked up again after the big rewrite where we focused on maintainability, extensibility and clarity.

NP: How has being open-source benefited Formtastic?

JF: Without extracting Formtastic to a plugin, the code would never have made it outside the original Rails app. Without an open source public release, the code would still be stuck inside that first company, so I would no longer have access to it. When Rails or Ruby released a major new version that needed us to make changes, the community was there to help and I didn’t need to be the expert on every tiny change. When HTML5 introduced a whole bunch of new form inputs, the community pitched in.

There’s no way Formtastic would be as fully featured, well tested or complete today without those. Progress would have been much slower, quality would have dropped and development would have stalled.

NP: What would you suggest every developer include with any plugin they plan to publicly release?

  • Start with README Driven Development: showing the syntax, describing how developers would use it, and what the benefits are.
  • Extract it from a real world application that’s proven the need and only accept features driven out of other real-world use cases.
  • Use Semantic Versioning to communicate the significance of the changes to your users and tie-in nicely with gem dependency resolutions.
  • Have some automated testing in place to ensure no bugs are introduced.
  • Use Continuous Integration. With Formtastic, Travis CI runs our suite of 1500+ tests against the 27 combinations of Ruby and Rails versions that we currently support every time a new pull request is proposed or merged.
  • Include instructions for how to contribute - usually just a few lines at the bottom of the README.

A big thanks to Justin (@justinfrench) for sharing his insights!

comments powered by Disqus