When you work with open-source software, you sometimes need to deal with projects that have stalled. How do you handle it? What do you do?

Background

As I mentioned a few weeks ago, I recently completed an upgrade of the software running this blog.

Since I launched in January, 2013, I’d been running Octopress 2. It was working well, but I was starting to run into a few issues. The biggest one was an inability to upgrade the syntax highlighting plugin to support new languages (like Swift) or new variants of languages (like the latest versions of JavaScript).

I’d been following along as Brandon Mathis and Parker Moore worked on a completely new structure for Octopress that was eventually released as Octopress 3. I was really excited about their work and couldn’t wait to try it out.

The new structure is essentially a suite of Ruby gems that provide a command-line interface, theming system, and plugin suite that sits on top of Jekyll.

I was finally able to carve out some time this year to perform the upgrade. Some weeks I wasn’t able to work on it at all, while others I was able to put a fair bit of time in.

As I started on the upgrade, I found that Octopress was in a bit of strange state. The theming part, Octopress Ink, wasn’t quite finished. Many of the gems didn’t yet support Jekyll 3. The base Octopress gem had a commit and version bump for Jekyll 3, but that version had never been officially published.

Most critically, none of the gems had seen any commit activity for almost a year. There were pull requests that fixed many of the issues that I ran into, but they hadn’t been merged or released yet.

I was at a crossroads. It looked like Octopress development had stalled.

What Do I Do Now?

Do I push through with Octopress 3, trying to piece together a functional system by pulling in specific pull request versions of the gems I needed?

Do I fall back to raw Jekyll and use it directly without Octopress?

Do I find another solution entirely?

I had to factor in how much time it would take me to convert to an entirely new system. I have more than three years’ worth of content here, and there are a lot of links that I didn’t want to break. Could I make that happen with an entirely new platform?

I looked briefly at Hexo, since it promises compatibility with most Octopress plugins.

In the end, I decided that being based on Jekyll was a good decision. It is still very popular and actively maintained, and also gave me the shortest path forward for migration.

With that decision made, I had to decide whether to fall back to raw Jekyll or to press forward with Octopress 3. The more I looked at the work that Brandon and Parker had done, the more impressed I was. They’ve done a really nice job, even if it’s not quite finished yet. The Octopress command-line interface is wonderful to work with. I can use stock Jekyll plugins when there isn’t an Octopress version available.

I decided to press forward. I submitted a few pull requests to fix issues I found, and I managed to get versions of the pieces I needed to work together.

I wasn’t able to get Octopress Ink fully working, so I ended up bringing my theme directly into the blog. This wasn’t ideal, but it worked.

In the end, I was able to deploy the updated blog on Octopress 3 a couple of weeks ago. There were a few little hiccups, but nothing too major.

How Should You Handle a Stalled Dependency?

I decided to press forward. But what should you do in a similar situation?

Every project is different, but here are some questions to consider:

How likely is the project to be permanently stalled?

Is the maintainer temporarily dealing with other issues? Or have they given up on the project entirely?

In my case, I have no idea if the project is permanently stalled or not, although Parker has recently released new versions of a couple of the Octopress-related gems.

How big is the community around it?

The bigger the community, the more people there are who can step up and contribute to keep the project alive.

I don’t think the Octopress community is huge, and I think a number of people have given up on the project due to the stall.

Can you make it do what you need in its current state?

If you can get the project working without too much effort, that might be a way forward. Most packaging systems allow you to reference packages that live outside the packaging system. For example, both Bundler in Ruby and npm in JavaScript allow you to reference projects that live in git repositories or on GitHub.

I was able to make Octopress do what I needed with a bit of additional work, and this became my solution of choice.

Can you help?

Can you offer to jump in and bring the project back to life? Many maintainers will welcome the help. Maybe you can go through and triage the open issues and pull requests. Maybe the maintainer will even give you access to merge pull requests and release new versions.

Worst case, if the maintainer is not in a position to accept this kind of help, there is always the option of forking the project. That’s not usually an ideal situation, but is sometimes necessary.

I have seriously considered offering to help maintain Octopress. There’s so much nice work in Octopress 3 and I’d hate to see it die and go to waste. But I also have to evaluate this option against my other time commitments and goals. For now, I’ve decided that I really can’t afford to put a significant amount of time into this project.

A Word of Caution

The main thing you SHOULDN’T do in the face of a stalled dependency is to be a jerk.

There is no call for shaming the maintainers of the project, or being rude to them. They’ve put in a lot of work for free to give something valuable to the community. That is always worthy of respect.

Too many open-source maintainers burn out when they have to constantly deal with spoiled, entitled people who think that the maintainer owes them something.

In my case, I have absolutely no ill will for Brandon and Parker. They’ve done a wonderful job getting the project to where it is. I have no idea what they’ve got going on that makes them unable to or unwilling to put more time into Octopress right now, and it’s none of my business.

I’m completely grateful that I have this option to choose from and that I was able to launch my blog upgrade with very few issues.

Conclusion

Open-source projects rise and fall. Sometimes they move forward in fits and starts. The next time one of your dependencies has stalled, ask yourself some of these questions to help you decide what to do.

Afterword

In case you’re someone who’s also been trying to get Octopress 3 to work, here’s the current version of my Gemfile. Maybe it can help you get up and running. As I mentioned, Parker has recently released new versions of some of these gems, but I haven’t yet made the time to try the new versions.

Octopress 3 Gemfile
source 'https://rubygems.org'

 
# Unpublished 3.1

gem 'octopress', git: 'https://github.com/octopress/octopress', ref: 'c98fd39'

 
group :jekyll_plugins do

  gem 'jekyll-archives', '~> 2.1'

  gem 'jekyll-sitemap', '~> 0.11.0'

  gem 'octopress-codeblock', '~> 1.0'

  gem 'octopress-date-format',

      github: 'ryanoglesby08/date-format',

      branch: 'fix-jekyll-hooks-integration',

      ref: 'bad275b'

  gem 'octopress-feeds', github: 'octopress/feeds', ref: 'acae1cb'

  gem 'octopress-hooks', github: 'octopress/hooks'

  gem 'octopress-image-tag', '~> 1.1'

  gem 'octopress-ink', github: 'randycoulman/ink', branch: 'jekyll-3'

  gem 'octopress-paginate', github: 'mshick/paginate', branch: 'jekyll3'

  gem 'octopress-social', '~> 1.4'

end