Thoughts on upgrading Hanami 1->2: an open letter to Hanami Core Team

Hanami 2 is such a big rewrite that it feels more like a different framework inspired by Hanami 1 than a next iteration of the same framework. From the perspective of evolving the original idea, it’s a huge step forward but I fear it’s a blow to long term adoption. I’ll explain.

I started using Hanami in March 2017 with the 1.0.0.beta3 version, on a side project. I really like the architectural approach and driving ideas behind Hanami. My experience tells me that the approach taken by Hanami would have an advantage in large applications over the Rails approach.

My app is very small (6 DB tables, 20 HTTP endpoints) but I’ve tracked 13 hours on the upgrade from 1.3 to 2.1 and I’m about 50% done. That’s excluding the time it took to replace hanami-model with pure Sequel models. I didn’t precisely track that but I estimate it at 6-7h. Most of the time was spent understanding how to do the upgrade, due to the lack of an upgrade guide or documentation for Hanami 2. I planned to contribute to the current WIP upgrade guide myself when I finish the migration but it looks like the easiest way to upgrade is to create a fresh Hanami 2.1 app and port the code.

This might come off sounding bitter so I want to emphasise that I don’t put any blame on the Core Team. I don’t regret choosing Hanami and version 2.1 is a very interesting framework with some great technology. I am honestly grateful to the Hanami core team for bringing it to the world.

However, had I built a very large app on Hanami 1, the very kind that it was optimised for, I would be in a world of trouble now, looking at a huge upgrade effort.

If the goal of the Hanami Core team is mainly to explore alternative approaches to web development and use it on your own projects, then this approach makes perfect sense and I applaud you. However, if you also value long term community adoption of Hanami and a few years down the line you’re wondering why it’s not being used more widely then part of the answer might be the upgrade pain caused to early adopters.

The only message I wish you to take is that, if long term adoption is a goal, perhaps this should be the very last big rewrite and it should be just gradual evolution with clear upgrade paths from now.


Hi @radanskoric, thank you for taking the time to write this letter, and for the care you have for Hanami.

Firstly, I’m sorry for the difficulty you encountered in upgrading your app. I’m quite aware that the path we chose for Hanami 2 is the source of these difficulties, and it’s something doesn’t sit comfortably with me. However, I think we had to make these choices for the long-term good of the framework. Given the people and time constraints we had around the development work, and given a desire to move past some of the evolutionary dead-ends of version one, this is just where had to arrive. Otherwise, the entire thing may have just stalled.

At this point I’m happy to immediately reassure you on last concern: this will be the final major breakage between versions. Once we’ve finished rolling out the remainder of the full stack features, all future versions will be iterative, with smoother upgrade paths.

In terms of the upgrade from v1 to v2, I hope that the community can help with upgrade guides, especially once our database support is in place (later this year, with v2.2). @swilgosz has already shared some great notes in Hanami 1.3 -> Hanami 2.0 (I see you’ve replied there already!), and I’m hoping those can expand as time goes on. Perhaps you might be able to share some notes from your own experience there?

Thanks again for sharing your thoughts, and I hope we can continue to gain your trust in the project again as we continue through 2.1, 2.2 and beyond.



Thank you for responding and acknowledging my issue. And also thank you again for your work. I’m happy to hear that there is serious intent in the core team to avoid future big rewrites. :slight_smile:

I really wanted to contribute to the guide but once the approach becomes “Create a new Hanami 2.1. app and port your code over page by page.” there’s not that much to contribute, since the users will be reading the docs for Hanami 2.1. I’ll think about it a bit more and have a look at my (unfinished) changes, maybe there are some lessons.


I think that article how to port application to H2 without downtime, feature by feature, would be very valuable too!

But Yeah, @radanskoric I am upgrading 3 applications, of small, medium and big size (15-20 prs daily).

It is clean to me, that small application can be rewritten, and you can port the code feature by feature to the new stack.

I am not doing it, because

  1. On small applications we can learn steps to tackle larger which we cannot rewrite by any means.
  2. Our learnings can be then adopted to the official guides to help the whole community
  3. Our delivery policy require the gradual upgrades on larger apps to not block development of other teams

The downside is, grinding through this is a marathon. In case of any troubles I can gladly help anyone needing some expertise, and over time I will publish the remaining parts.

We already discovered, that upgrading to rom5, then to Ruby 3 are the necessary first steps, and how to do it on applications of different sizes.

Ascenda also sponsored extending rom-factory by adding missing features that will be crucial for 2.2 applications.

Thanks for writing, I just wish the day could have 48 hours :joy: