DEV Community: Ernesto Tagwerker (he/him)

What We Check Before Migrating Off Heroku

Ernesto Tagwerker (he/him) — Tue, 03 Nov 2026 05:00:00 +0000

We recently moved a client’s Ruby on Rails app off Heroku: a Rails API with Sidekiq workers and several services around it. Before we changed anything, we spent about a week on discovery. We had a kickoff call with the client’s team on a Monday, and then two of us paired for the rest of the week to map the infrastructure and draft a migration plan.

Nothing about that app followed one pattern. Its services were deployed in different ways, and some of the things that mattered most for the migration, like the tools outside Heroku that read from the database and the service that promoted code to production, didn’t show up in the Heroku dashboard at all.

In this article, you will learn what we inventory before moving an app off Heroku, where to look beyond what Heroku shows you, and what our own discovery missed. Almost none of it depends on where you are going: it applies whether your target is Render, Fly.io, AWS, or something else.

Start with the people, then verify

We started with a kickoff call where the client’s team gave us an overview of the pieces: the main app, the services around it, and the tools they relied on. It was a high-level conversation, and after it the details were up to us. We went through each repo and each dyno on Heroku ourselves to find out what actually runs where. People describe what they think about every day, and the pieces they don’t think about are often the ones that break a migration.

Some of what you need to know, Heroku can’t tell you. We worked out part of it ourselves and asked the client’s team about the rest. Before planning any downtime, it helps to know who the customers are, where they are located, and whether there are known peak events, so you can pick a window that will hurt the least.

Who wrote what is something you can mostly find out on your own: we looked through the commit history of the repos to see who had worked on which part, so we knew who to send questions to later. Why the architecture looks the way it does is a question only the team can answer. Some choices are constraints you need to keep, and others are leftovers you can drop, and you want to know which is which before you rebuild them somewhere else.

It’s also worth asking whether the app has a maintenance page, and which jobs run on a schedule on staging and on production, since those keep running during a cutover unless someone pauses or moves them.

A few third-party tools also came up, and it wasn’t obvious at first how each one connected to the app. We ended up sorting every tool that came up into three groups:

Tools that run on Heroku, which we move.
Tools that run elsewhere but depend on something we move, which the client’s team updates.
Tools the migration doesn’t touch.

The second group needs the most attention, because those tools stop working if nobody updates them after the move. For us, that was an ETL sync and an AI code-review bot, both reading from the database. The client’s team wanted to update them themselves, which was fine, but we still had to find out how each one connected so everyone knew who owned what before cutover day.

What Heroku tells you

Once we knew what to look for, we went through every app in the Heroku dashboard, on both staging and production: the add-ons attached to each one, its config vars, and its dynos with their process types and sizes.

During discovery, we only listed the config vars. They turned into an audit later, when we were getting ready to move each service. For each variable, we searched the codebase to see whether anything still used it, and confirmed with the client’s team when the code didn’t make it clear. Only the variables that were still in use had to be set on the new platform. Compare them between staging and production while you’re at it, since some may be set differently in each environment.

We did the same with the dynos: we looked at their types and sizes during discovery, and confirmed them when each service moved, so that it would have roughly the same resources on the new platform as it had on Heroku.

If you have more than a couple of apps, or you’d rather keep a copy of what you found, the Heroku CLI shows the same information. heroku addons lists what is attached to an app, heroku config lists its config vars, heroku ps shows its process types with the size and number of dynos for each one, and heroku pg:info shows the Postgres version, plan, and data size:

heroku addons -a your-app-production
heroku config -a your-app-production
heroku ps -a your-app-production
heroku pg:info -a your-app-production

Looping over heroku pg:info is also a quick way to check the Postgres version of every app you have.

Config vars hold secrets, so be careful about where that output ends up. If you only need the names, for a checklist or to compare environments, you can print the keys and diff them:

diff <(heroku config --json -a your-app-staging | jq -r 'keys[]' | sort) \
     <(heroku config --json -a your-app-production | jq -r 'keys[]' | sort)

Every component is its own migration

Heroku shows you what runs there, but not how each piece got there. On our project, the services weren’t all deployed the same way. The image proxy, for example, ran straight from an upstream container image, with only configuration on top, while other services had build steps of their own. On Heroku they all look like any other process type, and nothing there tells you which one depends on someone else’s image and which one depends on a build you will have to reproduce.

That difference decides what the move looks like. For a service that runs from an upstream image, you need to know where the image comes from and whether the new platform can pull it. For a service with its own build, whether that’s a Dockerfile, a buildpack, or a shell script, you need to read it, because it is often the only place where the build is written down.

Reading the code is part of discovery, so we went through each repo. The YAML config files described the services they deployed, and they answered many of our questions about how each one was built. When something in them didn’t make sense, that became a question for the client’s team.

Treat each component as a small migration of its own, with its own build step, config, and move order, instead of assuming that what works for the main app will work for everything around it.

Add-ons, workers, and scheduled jobs

For most add-ons, moving means provisioning the equivalent service on the new platform and changing a URL in the config vars. The ones to look for are add-ons with no direct equivalent. Ours was a Memcached add-on, which many platforms don’t offer as a managed service, so we replaced it with a Redis cache.

During a migration, there is usually a period where both platforms can run the app. Web processes and workers can run on both for a while, as long as they talk to the same Redis, but scheduled jobs should run on exactly one platform at a time. List everything that runs on a schedule, whether it’s Heroku Scheduler, a clock process in the Procfile, or a gem like sidekiq-cron, and decide where each one runs during the transition. Check, too, which jobs must never run twice at once and whether anything in the code prevents it, since two copies of a job that calls a rate-limited API can use up a quota that one was designed to stay under.

Deploys, DNS, and alerting

Check how code reaches production. The Heroku pipeline showed a staging app and a production app, but promotion between them was handled outside Heroku, by a third-party automation that promoted a commit from staging after a set period. The client’s team also relied on review apps, so those went on our list of things to rebuild.

Find out who controls DNS. The client’s domains were at a third-party registrar, pointing at Heroku’s DNS targets, and the client’s team made the change at cutover. Lower the TTL on every record you’ll change, and do it well ahead of the window: at least as far ahead as the record’s current TTL. Resolvers can keep serving the old value for that long, so with a 24-hour TTL, you’d lower it at least a day before.

Finally, look at alerting and traffic. The client’s alerts went to Slack and PagerDuty, so decide which triggers to pause during each window and who turns them back on. We used the app’s tracing and database metrics to find the hours with the least traffic, then confirmed those traffic cycles with the client’s team.

What discovery missed

A week of discovery didn’t find everything. Two things got past us, and for each of them there was a check that would have caught it earlier.

Extensions in a different schema in production

The first one was in the database. Between August 2022 and mid-2023, Heroku installed Postgres extensions into its own heroku_ext schema, and extensions created during that time are still there unless someone asked Heroku Support to move them. On this app, production’s hstore, cube, and earthdistance extensions lived in heroku_ext, while staging’s lived in public, and nobody knew the two environments differed. The staging rehearsal went smoothly because staging had nothing in heroku_ext, but once we moved the production database, the app failed at runtime with this error:

permission denied for schema heroku_ext

What would have caught it is comparing the two databases before moving either one. In psql, \dx lists the installed extensions with their versions and schemas, and \dn+ lists the schemas with their access privileges. Running both on staging and on production and comparing the output would have shown the difference in a few minutes.

Redis connections from Heroku timing out

The second one was Redis. We initially planned to move Redis to the new platform during the database downtime, while the web app was still running on Heroku. That meant the app had to reach the new Redis instances from Heroku over external connections, and it errored while waiting on the AUTH response, because the default timeout is one second.

We were moving to Render, and the cause was specific to how Render Key Value, its Redis-compatible service, handles connections from outside Render. Key Value only accepts internal connections by default. Once you allow external ones, each new connection has to log in with AUTH before it can do anything else. Normal commands were fast, but AUTH took between one and four seconds, longer than the client’s one-second timeout, and the app kept just under 400 connections open at any given time. The client treats AUTH like any other command, so the only fix on the app’s side was a longer timeout for every command, which would also make real Redis problems slower to surface. Moving only part of the data wasn’t an option either: Redis held the Sidekiq job state and the GraphQL subscriptions, and every instance of the app had to use the same Redis.

So we changed the plan: move the full app first, keep using Heroku’s Redis for a bit after the move, and then take a short downtime to move Redis as well. The check that would have caught this earlier is connecting from the app’s own Redis client, with its own config, over the network path it will actually use during the transition, before you plan a window around it.

What discovery should leave you with

By the end of discovery, you want a written answer for every component: how it runs today, what it connects to, and what replaces it on the new platform. A table is the simplest way to keep that in one place. For the app we moved, it looks something like this:

Component	How it runs today	Connected to	Replacement on the new platform
Postgres	Heroku Postgres	web, workers, ETL sync	managed Postgres
Web (Rails API)	Heroku buildpack	DNS, alerting	container image built in CI
Workers and cron	Heroku buildpack	Redis	same image as web
Redis	two attached add-ons	web, workers	managed Redis
Cache	Memcached add-on	web	Redis cache
Image proxy	upstream container image	web	the same upstream image
ETL sync	owned by the client’s team	Postgres	updated by the client’s team

Once we had answers for every component, we were free to propose the order of the migration, and the table pointed to it. We moved both databases first, staging and then production. Next came the supporting services on staging, the telemetry pieces and the image proxy, and then the staging web app and workers together with Redis.

Production followed a similar pattern: the telemetry pieces and the image proxy first, then the web app and workers, which we brought up on Render independently of what was running on Heroku while DNS still pointed there and the app kept using Heroku’s Redis. The last step was a second cutover, where the client’s team changed DNS and we migrated Redis.

That order held up. The one time the order itself caused a problem was when we tried to move Redis early, during the database downtime.

Conclusion

In this article, we went through what we inventory before moving an app off Heroku. Heroku’s dashboard and CLI only cover part of that inventory. The things that mattered most on our migration lived in other repos, at the DNS registrar, in tools outside Heroku that read from the database, and in the workflow that promoted code to production. Sorting out early who owns each of those, and giving every component a row in the table, is what let us propose the migration order with confidence.

Not every app needs a week. If yours is a web process and a database, the move can take about an hour. Even our week of discovery missed two things. A staging rehearsal catches a lot, but only for what staging and production actually share, so compare the two before you trust the rehearsal.

Planning a move off Heroku? Take a look at how we approach Heroku migrations, and send us a message!

Making AI Agents Safe to Retry

Ernesto Tagwerker (he/him) — Tue, 27 Oct 2026 13:39:27 +0000

Over in the OmbuLabs.ai blog, our post on the ReAct pattern in Ruby walked through building an agent that reasons about a task, calls tools, and acts on the results, all inside a single Ruby script. That’s fine for a command-line experiment. It’s a different story once that same agent needs to run inside a Rails app, triggered by a web request, where a multi-step reasoning loop can easily take longer than any request should stay open.

The obvious fix is to move the agent into a background job. Sidekiq already handles work that takes a while, so an agent’s loop of thinking, searching, and acting should fit right in. It does, mostly, but a job’s retry semantics were built around retrying a database write, not a chain of API calls that has real, sometimes irreversible, side effects.

In this article, you’ll learn why an agent’s reasoning loop doesn’t survive a naive move into a background job, how to make its side effects idempotent against Sidekiq retries, and how to stream its progress to the user while it runs.

Why Agents Don’t Belong in the Request Cycle

Picture a support ticket coming into a Rails app. A reasonable first instinct is to trigger an agent right there in the controller: it reads the ticket, searches internal docs for anything relevant, drafts a reply, and tags the ticket before the response ever renders. Each of those is a step in the ReAct loop, thought, action, observation, repeated until the agent decides it’s done.

The trouble is that each step is also a network call to an LLM provider, plus whatever tool it decides to use. One search, one draft, one tag isn’t so bad. A ticket that needs two rounds of searching before the agent has enough context to draft a reply is a different story, and there’s no way to know in advance how many rounds a given ticket will need. On Heroku, a web request has 30 seconds before the router gives up and returns an H12 timeout, and that’s an optimistic budget for a loop whose length depends on what the model decides to do next.

Holding a web worker open for that long is also just wasteful. Puma has a fixed number of worker threads, and every request stuck waiting on an agent is a thread that isn’t serving anyone else. This is the same argument that’s applied to slow jobs since long before agents existed: a 10,000+ row CSV upload was enough to time out a browser. It’s just that an agent’s loop is often slower and less predictable than a fixed-size file.

Sidekiq is the obvious place to put this kind of work: queue a job, return a response immediately, let the ticket update once the job finishes. The rest of this article is about what happens once you actually do that.

Moving the Agent into a Sidekiq Job

We’ll build on the same shape as the ReAct pattern post: an agent with a few tools, looping through thought, action, and observation until it’s done. Here, the tools are specific to ticket triage, searching internal docs, drafting a reply, and tagging the ticket:

# app/services/ticket_triage/tools.rb
module TicketTriage
  class Tools
    def initialize(ticket)
      @ticket = ticket
    end

    def search_docs(query)
      InternalDocs.search(query).map(&:summary).join("\n\n")
    rescue InternalDocs::Error => e
      "Search failed: #{e.message}"
    end

    def draft_reply(content)
      @ticket.update!(draft_reply: content, status: "drafted")
      "Draft saved."
    end

    def tag_ticket(tags)
      @ticket.update!(tags: tags)
      "Tagged with #{tags.join(", ")}."
    end
  end
end

The function definitions follow the same JSON shape Claude expects, one per tool:

FUNCTION_DEFINITIONS = [
  {
    name: "search_docs",
    description: "Search internal documentation for relevant context",
    input_schema: {
      type: "object",
      properties: { query: { type: "string", description: "What to search for" } },
      required: ["query"]
    }
  },
  {
    name: "draft_reply",
    description: "Save a draft reply to the ticket",
    input_schema: {
      type: "object",
      properties: { content: { type: "string", description: "The drafted reply text" } },
      required: ["content"]
    }
  },
  {
    name: "tag_ticket",
    description: "Apply tags to the ticket for routing",
    input_schema: {
      type: "object",
      properties: { tags: { type: "array", items: { type: "string" } } },
      required: ["tags"]
    }
  }
].freeze

The agent itself is close to the ReActAgent class from the earlier post, adapted to work on a single ticket instead of a blog topic:

# app/services/ticket_triage/agent.rb
module TicketTriage
  class Agent
    def initialize(ticket)
      @ticket = ticket
      @tools = Tools.new(ticket)
      @messages = []
    end

    def run
      @messages << {
        role: "user",
        content: [{ type: "text", text: "Triage this ticket:\n\n#{@ticket.body}" }]
      }

      loop do
        response = complete
        break if response.content.all? { |block| block[:type] == :text }

        @messages << { role: "assistant", content: response.content }

        response.content.each do |block|
          next unless block[:type] == :tool_use

          result = dispatch(block[:name], block[:input])
          @messages << {
            role: "user",
            content: [{ type: "tool_result", tool_use_id: block[:id], content: result.to_s }]
          }
        end
      end
    end

    private

    def dispatch(tool_name, params)
      case tool_name
      when "search_docs" then @tools.search_docs(params[:query])
      when "draft_reply" then @tools.draft_reply(params[:content])
      when "tag_ticket" then @tools.tag_ticket(params[:tags])
      else "Unknown tool"
      end
    end

    def complete
      client.messages.create(
        model: "claude-sonnet-5",
        max_tokens: 1024,
        system: SYSTEM_PROMPT,
        messages: @messages,
        tools: FUNCTION_DEFINITIONS
      )
    end

    def client
      @client ||= Anthropic::Client.new(api_key: ENV.fetch("ANTHROPIC_API_KEY"))
    end
  end
end

Wrapping this in a job is, at first, almost anticlimactic:

# app/jobs/ticket_triage_job.rb
class TicketTriageJob < ApplicationJob
  queue_as :default

  def perform(ticket_id)
    ticket = Ticket.find(ticket_id)
    TicketTriage::Agent.new(ticket).run
  end
end

And the call site, wherever a ticket gets created:

def create
  @ticket = Ticket.create!(ticket_params)
  TicketTriageJob.perform_later(@ticket.id)
  redirect_to @ticket
end

The controller returns right away, the agent does its work on a Sidekiq worker, and the ticket’s draft_reply and tags show up whenever the job finishes. This is the version that works when everything goes right. The next section is about what happens when it doesn’t.

Retries Replay the Whole Loop

Sidekiq’s default behavior on an unhandled exception is to re-enqueue the job and try again later, with a backoff, up to 25 times unless you configure otherwise. This works well for the kind of job Sidekiq was originally built around: something like resizing an uploaded image or writing a row, where the whole method is safe to run again from the top, or already guards itself with a find_or_create_by or a unique index.

TicketTriageJob#perform doesn’t have that property, because Sidekiq has no idea what happened inside the agent’s loop. It only knows whether perform raised or returned. If the database connection drops while tagging the ticket, after the agent has already searched the docs and drafted a reply, the job as a whole raises, and Sidekiq schedules a full retry of perform, not a retry of “just that last step.”

Here’s roughly what that looks like across the two attempts:

Attempt 1:
💬 Thought: Let me search for relevant documentation first.
🔧 Action: search_docs({query: "refund policy digital goods"})
📝 Observation: Refunds are issued within 14 days...

💬 Thought: I have enough context to draft a reply.
🔧 Action: draft_reply({content: "Thanks for reaching out! Per our..."})
📝 Observation: Draft saved.

💬 Thought: This looks like a billing issue, let me tag it.
🔧 Action: tag_ticket({tags: ["billing", "refund"]})
📝 Observation: ActiveRecord::ConnectionTimeoutError: could not obtain a database connection within 5.000 seconds
[job raises, Sidekiq schedules a retry]

Attempt 2:
💬 Thought: Let me search for relevant documentation first.
🔧 Action: search_docs({query: "refund policy digital goods"})
📝 Observation: Refunds are issued within 14 days...

💬 Thought: I have enough context to draft a reply.
🔧 Action: draft_reply({content: "Hi there, thank you for contacting us..."})
📝 Observation: Draft saved.

Two things went wrong here that would be easy to miss in a quick look at the logs. The search happened twice, which is a wasted API call and a few cents, not a disaster on its own. The draft happened twice, and because the model isn’t deterministic between calls, the second draft isn’t the same text as the first, it just quietly replaced it. If draft_reply had gone one step further and actually sent the reply to the customer instead of just saving it, attempt two would have sent a second, different email for the same ticket.

None of this is a Sidekiq bug. Sidekiq is doing exactly what it promises: retrying the job. The mismatch is that “the job” here is a loop with several external, stateful side effects glued together, and retrying it as one unit assumes every step inside is either free to repeat or already protects itself. Neither is true yet in this version.

Making the Agent’s Side Effects Idempotent

The fix isn’t to stop Sidekiq from retrying, it’s to make each side-effecting tool check whether it already did its job before doing it again. search_docs doesn’t need this, it only reads, so repeating it wastes a little time and a little API budget but changes nothing. draft_reply and tag_ticket do need it, because each one writes something that a second, different write would silently clobber or duplicate:

# app/services/ticket_triage/tools.rb
module TicketTriage
  class Tools
    def initialize(ticket)
      @ticket = ticket
    end

    def search_docs(query)
      InternalDocs.search(query).map(&:summary).join("\n\n")
    rescue InternalDocs::Error => e
      "Search failed: #{e.message}"
    end

    def draft_reply(content)
      return "Already drafted, skipping." if @ticket.draft_reply.present?

      @ticket.update!(draft_reply: content, status: "drafted")
      "Draft saved."
    end

    def tag_ticket(tags)
      return "Already tagged, skipping." if @ticket.tags.present?

      @ticket.update!(tags: tags)
      "Tagged with #{tags.join(", ")}."
    end
  end
end

The guard clause in each method reads the ticket’s own state as the record of what already happened, rather than adding a separate idempotency-key table. This works here because the ticket’s fields double as their own completion markers: a draft_reply isn’t just an input to the next step, it’s proof the step already ran. A job whose side effects don’t leave that kind of trace on an existing record, sending a Slack message with no corresponding column to check, say, would need something more explicit, like a processed_steps array on the ticket, or a Redis key set right before the external call.

The short string each guard returns matters as much as the guard itself. It goes back into the agent’s message history as a normal tool result, so the model reads “Already drafted, skipping.” the same way it would read “Draft saved.”, and moves on to the next step instead of getting stuck or trying the same action again. Replaying attempt two from the earlier trace with these guards in place, the search still runs twice (harmless), the draft short-circuits on the second attempt (no second, different email going out), and the tag, which is what actually failed the first time, gets a real chance to succeed.

Streaming Progress to the User

The agent is now safe to retry, but from the ticket page it’s invisible. Someone looking at the ticket while the job runs sees nothing change for however long the loop takes, then the draft reply and tags appear all at once. That’s a worse experience than the synchronous version was, even though it’s more robust underneath.

Turbo Streams can close that gap without adding a polling endpoint or a websocket layer of our own. The usual Hotwire pattern broadcasts from an ActiveRecord callback, and broadcasting directly from a job used to be the trickier path when we first tried it. What’s different here is that TicketTriageJob runs once and finishes, it isn’t a self-rescheduling poller broadcasting on every tick indefinitely, so calling Turbo::StreamsChannel.broadcast_append_to directly from the agent, the way we do below, stays simple for this bounded sequence of steps. We broadcast a small update at each step of the loop:

# app/services/ticket_triage/agent.rb
module TicketTriage
  class Agent
    def run
      broadcast_step("Starting triage...")

      @messages << {
        role: "user",
        content: [{ type: "text", text: "Triage this ticket:\n\n#{@ticket.body}" }]
      }

      loop do
        response = complete
        break if response.content.all? { |block| block[:type] == :text }

        @messages << { role: "assistant", content: response.content }

        response.content.each do |block|
          next unless block[:type] == :tool_use

          broadcast_step("Calling #{block[:name]}...")
          result = dispatch(block[:name], block[:input])
          broadcast_step(result.to_s)

          @messages << {
            role: "user",
            content: [{ type: "tool_result", tool_use_id: block[:id], content: result.to_s }]
          }
        end
      end

      broadcast_step("Triage complete.")
    end

    private

    def broadcast_step(text)
      Turbo::StreamsChannel.broadcast_append_to(
        @ticket,
        target: "agent_activity",
        partial: "tickets/agent_step",
        locals: { text: text }
      )
    end

    # dispatch, complete, and client stay as they were
  end
end

The partial being appended is about as plain as a Turbo Stream target gets:

<%# app/views/tickets/_agent_step.html.erb %>
<p class="agent-step"><%= text %></p>

And the ticket’s show page just needs to subscribe to the stream and give the broadcasts somewhere to land:

<%= turbo_stream_from @ticket %>

<div id="agent_activity">
  <!-- agent steps get appended here as the job runs -->
</div>

Whoever has the ticket open watches the activity fill in step by step instead of staring at an unchanged page. One thing worth deciding deliberately rather than by default: result.to_s broadcasts whatever the tool returned, including the full text of a drafted reply. That’s fine for an internal support queue, but if this pattern gets reused somewhere a customer might see the stream, broadcast a short status (“Draft ready for review”) instead of the tool’s raw output.

That covers live progress for whoever has the ticket open, which is a different need from knowing what each step cost after the fact. If you also want to track token usage, latency, and dollar cost per call, see Tracking LLM Latency & Cost with Rails Events, which wires that up with the Rails 8.1 Event Reporter.

Conclusion

Getting an agent out of the request cycle and into Sidekiq was the easy part, and it’s also the part that looks finished before it actually is. The TicketTriageJob from the second section runs, and runs correctly, right up until something fails partway through and Sidekiq does exactly what it’s supposed to do: retry the whole thing. Making that safe meant treating the ticket’s own fields as a record of which steps already happened, so a retried loop skips what’s done instead of repeating it. Making it visible meant broadcasting each step over Turbo Streams as it happens, since a job that’s safe to retry silently is still a bad experience if it looks frozen for a minute at a time.

None of this is free complexity. A tool that only reads, or an agent that makes a single classification call and returns, doesn’t need idempotency guards because there’s nothing stateful to duplicate. These patterns earn their keep specifically when an agent’s loop can run more than once, touches something outside the database, and takes long enough that a user is watching it happen, which describes more production agent work than not, but not all of it. It’s also worth confirming an agent is the right feature for the job in the first place, before any of this gets built, and we’ve covered how to prioritize which AI features to build in a Rails app elsewhere. Streaming progress to the user, as covered here, is also a different problem from tracing what an agent did for your own debugging after the fact, we’ve written separately about why LLM applications need that kind of observability too.

Running agents in production and hitting failure modes like these? Let’s talk about it.

Irish Chess Union Upgrades to Rails 8.1

Ernesto Tagwerker (he/him) — Thu, 17 Sep 2026 04:00:00 +0000

Founded in 1912, the Irish Chess Union (ICU) is the governing body for chess across the island of Ireland. It has about 2,500 members and run entirely by volunteers.

Its website, icu.ie, has been maintained by webmaster Jonathan O’Connor since 2015. Earlier this year, Jonathan reached out to us. He wanted help taking the ICU’s Rails application from 7.0 to 8.1.

We used Claude Code and our open source Claude Code Rails Upgrade Skill to get it done. We also recorded the sessions as a video series, so other teams could see the methodology in practice.

In this article, we’ll walk through the upgrade, one version at a time, and share what Jonathan thought of the process.

Here was our challenge

The ICU’s application was built and is maintained by professionals, just not on the clock. Everyone involved works on it nights and weekends, as volunteers. It was written mostly by Mark Orr, a ratings officer who had just retired and wanted to give back to the community.

That project became learning Ruby on Rails and building the ICU a website from scratch. He wrote about 90% of the code that’s still running today. Jonathan took over as webmaster in 2015.

He’d learned Ruby a few years earlier, on a six-week trip to Rwanda building credit card payment systems. Rails’ conventions weren’t as disorienting to him as they are to developers who come to it cold.

He kept the application current on his own for a while. When he upgraded it from Rails 3 to 5, he did it the patient way: bumping the Gemfile one patch version at a time, running the test suite, and fixing whatever the deprecation warnings in the logs pointed at.

His colleague Ben Murray later carried it from 5.0 to 7.0. Then Jonathan tried to take it from 7.0 to 7.1 by himself. The same approach that had worked for years stopped working.

He’d been away from daily Rails work since 2016. The deprecation warnings piled up faster than he could make sense of them.

“It was a lot harder,” he said. Eventually it became impossible to tell which warnings actually mattered.

Here’s how we solved it

We used the same methodology we’ve documented for years: dual-boot the app with the next_rails gem, and upgrade one minor Rails version at a time, never skipping a hop.

For the ICU, that meant an unhurried climb from 7.0 to 7.1, then 7.2, then 8.0, and finally 8.1. Each hop got its own pull request. Each one had a green test suite against both Rails versions before we merged it and moved to the next.

Here’s what that looks like under the hood, for anyone who hasn’t dual-booted a Ruby app before:

Before we touched the Rails version at all, we spent some time on groundwork.

We set up GitHub Actions, so the ICU had CI for the first time. We patched the Docker configuration, so the app could build against either Gemfile.

That kind of scaffolding is easy to underestimate. It’s usually what makes the rest of the upgrade boring, in a good way.

This was also a great opportunity to share with the community how we leverage our open source Claude Code Rails Upgrade Skill, instead of just publishing it and hoping people would try it themselves. In 3 different pairing sessions, we drove Claude to use the skill to handle the mechanical work that happens in every upgrade project.

Claude handled a lot of the mechanical work in each hop: previewing what rails app:update would change, running the test suite against both Gemfiles, and flagging deprecation warnings before they piled up.

Our engineers, Henrique Medeiros, Ariel Juodziukynas, Aysan Isayo, and Juan Vasquez, made the judgment calls the skill is deliberately not built to make on its own.

One of those calls was a small shim in the ICU’s codebase. Even Jonathan, after nearly a decade of maintaining the app, said he never would have found it on his own.

“There’s one thing I would never have found, even if I kept working at trying to figure out how to do the upgrade myself, and that was this shim in our code,” Jonathan said. “I think that’s one of the places where you earn your keep, because these are tricks that people won’t know, since they’re not doing upgrades every day.”

Part of why the rest of the upgrade went smoothly is that the ICU’s codebase is, in Jonathan’s own words, unusually well-behaved.

No monkeypatches. No reopened core classes. No weird code in weird places.

And on top of that: A real test suite with both model and integration coverage.

None of that is guaranteed for an application built by a single volunteer. But Mark Orr and Jonathan had both stuck close to the Rails way, and it showed in how predictable each hop turned out to be.

The ICU never had to pause its own work, either.

Jonathan’s small team of volunteer contributors kept shipping features throughout the upgrade. The app’s Stripe integration, the dependency that worried us most going in since it handles ICU’s membership payments, never broke stride.

See the results

Now the ICU is current on Rails 8.1.

“I didn’t notice any issues at all. There were no breakages at all. You made maybe seven or eight pull requests, probably thirty or forty commits over that time, and they just fitted seamlessly into all our changes. Nothing ever broke. And thank you so much for setting up our Docker, because now we have our tests running on GitHub, which is brilliant.”

Jonathan O’Connor, Webmaster, Irish Chess Union

Here’s one of those pull requests, upgrading the app to Rails 7.2:

Eight pull requests, somewhere around thirty to forty commits, and zero breakages.

That’s not a coincidence. It’s what a sequential, dual-booted upgrade against a clean codebase and a stable test suite looks like when it goes right.

There’s also a quieter story here, about who can afford this kind of work.

A volunteer-run federation with no engineering budget to speak of got a five-version Rails upgrade done. Not because the work got easier, but because one senior engineer driving Claude Code and our upgrade skill can now get much closer to what it used to take two.

This is a real shift we’re seeing across our upgrade engagements, and it’s a big part of why an organization like the ICU can now afford this kind of work at all.

If you’re trying to make this case internally, here’s some advice on how to pitch a Rails upgrade to your boss.

Watch the pairing sessions

We recorded four sessions from this project, so you can watch the actual pairing work instead of just reading about it.

Part 1: Setting up CI

Henrique Medeiros and I spend about an hour setting up CI for the ICU’s application: wiring up GitHub Actions and using Claude Code to work through the setup issues that came up along the way:

Part 2: Dual booting and API compatibility

Henrique and I dig into dual booting and the API differences between Rails 7.0 and 7.1.

We set up next_rails and a Gemfile symlink strategy, chase down a few gem compatibility issues using RailsBump.org, and configure GitHub Actions and Docker to run the test suite against both Rails versions:

Part 3: Upgrading to Rails 7.2, and getting ready for 8.0

Juan Vasquez and I carry the app from Rails 7.1 to 7.2, while preparing the codebase for Rails 8.0.

We walk through how the upgrade skill checks the current patch version, confirms dual boot is set up, and generates an upgrade report, then track down a Capybara and Selenium WebDriver compatibility issue that turns out to have nothing to do with Rails itself:

Recap: A quick recap of the entire upgrade project

Jonathan and I talk about the project end to end: the ICU’s volunteer culture, why the upgrade stalled at Rails 7.1, the results, and Jonathan’s own take on where AI helps and where he still won’t let it near ICU’s data.

Keep an eye out for the Easter egg: a shim in the ICU’s codebase that Jonathan says he’d never have thought of himself.

Conclusion

The ICU’s upgrade worked because the methodology did the heavy lifting, not the AI on its own. Our AI tooling certainly help speed things up! 🚀

Dual booting, sequential hops, a deprecation-first approach: none of that is new.

What’s new is that Claude Code, guided by a skill that encodes those opinions, can now execute most of it, while our engineers focus on the handful of judgment calls, like that one shim, that still need a human who’s done this before.

It’s worth saying plainly: this went smoothly in part because the ICU’s codebase was clean and well-tested.

A messier application, full of monkeypatches and flaky tests, would have taken longer.

Has your team been putting off a Rails upgrade? Let’s talk and get your up to the latest stable versions of Ruby and Rails!

References

All of the pull requests below were merged into the ICU’s master branch, and the full history is public:

You can find the ICU’s full application source code at github.com/irishchessunion/icu_www_app, and our own upgrade skill at github.com/ombulabs/claude-code_rails-upgrade-skill.

If you want the version-by-version details behind each hop, our Rails Upgrade Series covers every jump from 2.3 onward.

Fortify Rails - Defending Your Ruby on Rails Applications from Bad Actors

Ernesto Tagwerker (he/him) — Mon, 26 Jun 2023 12:34:56 +0000

On Monday June 12th, 2023, FastRuby.io partnered with Expedited Security to talk about how to secure your Ruby on Rails application.

In this free webinar Ernesto Tagwerker (FastRuby.io) and Mike Buckbee (Expedited Security) discussed topics of interest related to Rails security (exploitable ActiveRecord code, vulnerable dependencies, botnets, DDoS, a breakdown of common threats, and more).

You’ll also get a sneak peak of Wafris, an Open Source service to prevent attackers and dark traffic to your application and of our new Rails Security Audit, a service to detect vulnerabilities and exploitable code in your app!

Check out the recording of the Fortify Rails webinar here: https://www.youtube.com/embed/KkXTw7UDR9w

Here are the slides on exploitable code and insecure dependencies: https://speakerdeck.com/etagwerker/fortify-rails-webinar

If you want to read more about Ruby and Rails security tooling check out this article: 4 Essential Security Tools To Level Up Your Rails Security

Need a trusted third party to give you a prioritized list of security issues? Check out our Rails Security Audit service.

Power Home Remodeling Increases Server Speed by 40% with FastRuby.io’s Tune Report

Ernesto Tagwerker (he/him) — Fri, 02 Jun 2023 10:10:59 +0000

Power Home Remodeling (Power) is the nation’s largest full-service exterior home remodeler and a top workplace.

Headquartered in Chester, Pennsylvania with offices in 18 territories across the United States, the award-winning company’s primary product line includes windows, siding, doors, roofing, solar roofing panels, and attic insulation.

In this article we will share how our Tune Report helped Power speed up their application by reducing their average page load time from 5 to 3 seconds.

Our Challenge

Power provides homeowners with top-rated customer service, and quality, energy-efficient products that help upgrade their home’s exterior. While a home remodeling company at its core, Power has also become a leader in workplace culture, leadership development, and technology.

Behind the scenes, Power’s unique, state-of-the-art collaborative intelligence platform—known as Nitro—enables seamless, real-time communication across the business.

The company’s technologists are responsible for developing and delivering Nitro’s software through continuous integration, as well as the three data centers that manage it.

According to Wade Winningham, Principal Developer, “We don’t use third-party applications for our sales, lead generation, tracking, and fulfillment. We’ve built everything ourselves and we’re proud that we operate our own platforms and technology without much reliance on an outside cloud.”

Wade, who helps set standards for the entire department, is always on the alert for ways to enhance and refresh their technology infrastructure. For the past six years, they have reached out to us anytime they needed support with Ruby on Rails maintenance, development, and upgrades.

Several years ago, the Ruby on Rails version underlying Power’s software was getting stale, but due to the size of their application, it was going to be a daunting task to handle internally.

We were hired to help with the upgrade from Rails 3.2 to 4.0. “OmbuLabs/FastRuby.io is an expert in Ruby and Rails, and we knew it was going to be in our best interest to hire them,” explained Wade.

“The Rails upgrade project was a huge success. The developers were top notch, knew what they were doing, understood our internal application, and helped us through it.” We collaborated with Power’s team to get them all the way to Rails 6.0 and then they continued their upgrade journey.

Our next challenge was to find ways for our clients to identify optimization opportunities within their Rails applications.

The Solution: Tune Report

Recently, in partnership with Nate Berkopec from Speedshop, we launched our new Tune Report, which helps our clients accelerate their Ruby applications, reach a higher level of performance, and reduce server costs.

We shared our new service with Wade and his team, and they immediately saw the benefits. “We thought it would be great to have an outside perspective of our application. The Tune Report would look at areas that we weren’t focusing on or even aware of having potential issues.”

See the results:

Our first step was to meet with everyone involved. The business technology team provided access to their repositories, internal hardware statistics, application metrics, and codebase to monitor and observe the application.

After we had a chance to explore, read, and analyze the source code, we delivered our Tune Report, which provided a list of key areas that could be immediately addressed and others that could be improved upon over time.

Doing More with Less: Improved Server Performance Results in Reduced Costs

Power’s applications run in a containerized environment. Their theory was that if they had more server instances and fewer processes running in those servers spread out over a wide area, that their application would be more resilient.

However, our Tune Report revealed an excessive amount of memory available, compared to the amount of CPU they were able to use within their servers.

Our recommendation was to reduce the number of server instances and increase the number of processes that each server executed.

For example, instead of having 60 servers with 2 processes, it would be far more efficient to have 20 servers with 6 to 8 processes each.

With more processes per server, there is less chance of one of those being busy when a request arrives. By making this adjustment, we were able to drive down the wait time from an average of 20-50 milliseconds to almost 0 milliseconds.

With this, and all other changes made so far from the report, page loads were reduced from 5 seconds to below 3 seconds.

“This was a huge win for us because we were able to size our application accordingly across multiple server instances,” said Wade. “It only took a few days to test this and verify that they were right.”

By running fewer server instances, hardware is freed up and computational power can be reallocated; ultimately, this results in cost savings and increased speed using half the server capacity.

We also found ways to improve query performance by adding indexes in the database. “These were simple for us to add and immediately improved performance across our application,” said Wade.

The Importance of Regular Checkups

For Wade, the Tune Report was like another set of eyes on areas they may not have thought to look at.

“It was great to have OmbuLabs/FastRuby.io’ insights. They came in, showed us where we could make improvements, and it was easy to implement their suggestions.”

Our team delivered a report that enabled Power to show noticeable results to non-technical stakeholders:

“Our executives were thrilled with the report,” shared Wade. “They liked the fact that we could take action immediately to experience an almost instantaneous impact, and recommended that we invest in a Tune Report on a regular basis.”

Wade felt the Tune Report was well worth the time and effort of getting an outside perspective and said:

“I was shocked that we were able to do so much in a short amount of time and to show that kind of return on investment. The Tune Report came at a really great time and showed us how beneficial it was to do—not just once, but routinely. It’s like taking your application to the auto mechanic for a checkup.”

“I really enjoy working with OmbuLabs/FastRuby.io. They’re experts at what they do, and I’ve always been impressed with their skill, professionalism, and knowledge,” concluded Wade. “They are also very involved in the Ruby community which just adds to their credibility.”

Summary

The collaboration between Power and OmbuLabs/FastRuby.io exemplifies how external experts can bolster in-house technological capabilities. The Tune Report proved an invaluable resource in optimizing Power’s Nitro platform, leading to improved performance and cost savings.

The success of this collaboration underscores the importance of regular performance audits and the value they bring in terms of enhancing user experience, reducing costs, and maintaining a competitive edge in a technology-driven world.

The Tune Report, product of a collaboration between FastRuby.io and Speedshop, proved instrumental in identifying optimization opportunities, leading to a significant decrease in average page load time, from 5 to 3 seconds.

One of the key recommendations, reducing the number of server instances and increasing the number of processes per server, resulted in a drop in wait time from 20-50 milliseconds to almost 0.

If you are interested in hearing more about our Ruby/Rails performance audits, send us a quick message.

WHO WE ARE:

OmbuLabs is Philadelphia's lean software boutique. Specializing in Ruby, Ruby/Rails Upgrades (FastRuby.io), JavaScript, JavaScript Upgrades (UpgradeJS.com), minimum viable product development, and reducing technical debt, we help companies (from startups to Fortune 500 companies) build and improve their digital products.

Founded in 2011 and headquartered in Philadelphia, Pennsylvania, our experienced and diverse team of developers is ready to do whatever it takes to help your business grow.

To learn more, visit us at OmbuLabs.com.

4 Essential Security Tools To Level Up Your Rails Security

Ernesto Tagwerker (he/him) — Wed, 31 May 2023 11:23:45 +0000

At FastRuby.io we love Ruby on Rails because it is so powerful: You can quickly create an application that is feature complete, stable, and secure

Unfortunately, maintaining a Rails application up to date and secure takes some effort.

In this blog post, we will cover a few Ruby gems and best practices that you can use to stay on top of your security, reliability, and stability needs.

Before we dive into 4 different Ruby gems you can use to improve your security support, let’s start with some of the security goodies that already come with Rails.

Rails’ Native Security Features

The good news is that Rails comes with a ton of security support, here are a few features that you are probably already using in your application:

Forcing SSL

You can easily secure your authentication by enabling TLS in your configuration:

# config/environments/production.rb
# Force all access to the app over SSL,
# use Strict-Transport-Security,
# and use secure cookies
config.force_ssl = true

If your web server (e.g. nginx) doesn’t force SSL, your Rails application will.

CSRF (Cross Site Request Forgery)

Some of these security features are enabled by default. For instance: CSRF. Ruby on Rails has specific, built-in support for CSRF tokens.

If you see this line in your application_controller.rb, you know that you are including Rails’ protection against cross site request forgery:

class ApplicationController < ActionController::Base
  protect_from_forgery
  # ...

CORS (Cross Origin Resource Sharing)

Occasionally, a need arises to share resources with another domain. For example, a file-upload function that sends data via an AJAX request to another domain.

In these cases, the same-origin rules followed by web browsers must be sent. Modern browsers, in compliance with HTML5 standards, will allow this to occur but in order to do this; some precaution must be taken.

For this, you can use the rack-cors gem:

gem 'rack-cors', :require => 'rack/cors'

You can configure it as a middleware like this:

# config/application.rb:

module Sample
  class Application < Rails::Application
    config.middleware.use Rack::Cors do
      allow do
        origins 'audit.fastruby.io'
        resource %r{/users/\d+.json},
        :headers => ['Origin', 'Accept', 'Content-Type'],
        :methods => [:post, :get]
      end
    end
  end
end

Filtering Parameters

To make sure sensitive request parameters aren’t logged to your log files, you can set up your application like this:

Rails.application.config.filter_parameters += [
  :credit_card_number,
  :password,
  :social_security_number
]

Values for these parameters will now show up as "[FILTERED]" in your log files.

Now that we have covered some of the key security features in Rails , let’s look at 4 gems that can help you level up your security best practices:

Bundler Audit
Brakeman
Rack::Attack
Secure Headers

Bundler Audit

This Ruby gem is quite useful for detecting versions of gems that are known to be vulnerable to security issues. bundler-audit uses an open database of vulnerable gems called ruby-advisory-db and compares it to the versions that show up in your Gemfile.lock.

You can install it and run it like this:

gem install bundler-audit
bundle-audit

If there are vulnerable versions in your Gemfile.lock it will show you something like this:

If everything looks good, it will show you something like this:

A few years ago we built a small, open source, web application to make it easier for us to share these vulnerabilities reports with our clients. You can find it and use it over here:

Bundler Audit Tool

It usually looks like this:

bundler-audit relies on ruby-advisory-db, a community-maintained database of known security vulnerabilities. While this is a great approach, it may also lead to gaps in coverage if a vulnerability is not yet documented in the database or if the database becomes outdated.

If you want to make sure that bundler-audit is running with the latest version of the ruby-advisory-db, you should always call it like this:

bundle-audit check --update

Brakeman

brakeman is another useful Ruby gem that is a static analysis security vulnerability scanner for Ruby on Rails applications.

You can quickly run it like this:

cd path/to/rails-app
gem install brakeman
brakeman

This will run a battery of “checks” against your source code and report any potential security issues:

Loading scanner...
Processing application in /Users/etagwerker/Projects/ombulabs/foobar
Processing gems...
[Notice] Detected Rails 6 application
Processing configuration...
[Notice] Escaping HTML by default
Parsing files...
Detecting file types...
Processing initializers...
Processing libs...
Processing routes...
Processing templates...
Processing data flow in templates...
Processing models...
Processing controllers...
Processing data flow in controllers...
Indexing call sites...
Running checks in parallel...
 - CheckBasicAuth
 ...
 - CheckYAMLParsing
Checks finished, collecting results...
Generating report...

== Brakeman Report ==

Application Path: /Users/etagwerker/Projects/ombulabs/foobar
Rails Version: 6.1.4
Brakeman Version: 5.4.1
Scan Date: 2023-05-02 15:18:55 -0400
Duration: 0.430032 seconds
Checks Run: BasicAuth, ..., YAMLParsing

== Overview ==

Controllers: 3
Models: 2
Templates: 15
Errors: 0
Security Warnings: 2

== Warning Types ==

Cross-Site Scripting: 1
Unmaintained Dependency: 1

== Warnings ==

Confidence: High
Category: Unmaintained Dependency
Check: EOLRuby
Message: Support for Ruby 2.7.2 ended on 2023-03-31
File: .ruby-version
Line: 1

Confidence: Weak
Category: Cross-Site Scripting
Check: SanitizeConfigCve
Message: rails-html-sanitizer 1.3.0 is vulnerable to cross-site scripting when `select` and `style` tags are allowed (CVE-2022-32209). Upgrade to 1.4.3 or newer
File: Gemfile.lock
Line: 194

To see a complete list of checks ran by Brakeman, you can find them over here: List of Brakeman Checks

This sample application is in pretty good shape, but it does report two warnings:

High: I’m using Rails 6.1 with Ruby 2.7.2. Security support for Ruby 2.7.x ended on March 31st, 2023.
Weak: I’m using a version of rails-html-sanitizer that is known to be vulnerable.

One of them is quite easy to fix: bundle update rails-html-sanitizer and the warning goes away. We can safely deploy this to production with a small pull request.

The other warning might be harder to accomplish: We need to upgrade from Ruby 2.7 to 3.0.

Just like any other static analysis tool, brakeman may generate false positives or negatives. This means that it might report issues that aren’t actually problems or fail to detect actual vulnerabilities. We need to be cautious when interpreting the results and not rely solely on these tools for ensuring security.

Rack::Attack

rack-attack is a middleware that can be used in your Rails application (and any rack-based Ruby applications!) to protect it from bad clients.

Rack::Attack lets you easily decide when to allow, block and throttle based on properties of the request.

Here are some of its key features:

Safelisting / Blocklisting

You can quickly allow an IP like this:

# config/initializers/rack_attack.rb (for rails app)
Rack::Attack.safelist_ip("5.6.7.0/24")

This could be useful if you want to allowlist your development team’s IP addresses.

You could quickly block an IP like this:

# config/initializers/rack_attack.rb (for rails apps)
Rack::Attack.blocklist_ip("1.2.3.4")

It’s a powerful combination to combine rack-attack with environment variables like this:

# config/initializers/rack-attack.rb

bad_ips = ENV["BLOCKLIST_IPS"].split(",") # to be blocked

Rack::Attack.blocklist "blocklist bad IP address" do |req|
  bad_ips.include?(req.ip)
end

good_ips = ENV["SAFELIST_IPS"].split(",") # to be safelisted

Rack::Attack.safelist "safelisted good IP address" do |req|
  good_ips.include?(req.ip)
end

Throttling

This would be a good way to slow down an attacker who is trying to sign in to a user account using a brute force attack:

# Throttle login attempts for a given email parameter to 6 reqs/minute
# Return the *normalized* email as a discriminator on POST /login requests
Rack::Attack.throttle('limit logins per email', limit: 6, period: 60) do |req|
  if req.path == '/login' && req.post?
    # Normalize the email, using the same logic as your authentication process, to
    # protect against rate limit bypasses.
    req.params['email'].to_s.downcase.gsub(/\s+/, "")
  end
end

Additionally, you could have a more broad criteria for limiting the number of requests per minute:

# config/initializers/rack_attack.rb (for rails apps)

Rack::Attack.throttle("requests by ip", limit: 5, period: 2) do |request|
  request.ip
end

Based on the IP of the user, this configuration would limit their rate to 5 requests every 2 seconds.

You can combine rack-attack and Cloudflare as a good way to prevent DDoS attacks. Just because you are using rack-attack, it doesn’t mean that you should not use a tool like Cloudflare.

Secure Headers

The secure_headers gem will automatically apply several headers that are related to security. This includes:

Content Security Policy (CSP) - Helps detect/prevent XSS, mixed-content, and other classes of attack. Default value: default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'
HTTP Strict Transport Security (HSTS) - Protects from SSLStrip/Firesheep attacks. Default value: max-age=631138519
X-Frame-Options (XFO) - Prevents your content from being framed and potentially clickjacked. Default value: sameorigin
X-XSS-Protection - Cross site scripting heuristic filter for IE/Chrome. Default value: 1; mode=block
X-Content-Type-Options - Prevent content type sniffing. Default value: nosniff
X-Download-Options - Prevent file downloads opening. Default value: noopen
X-Permitted-Cross-Domain-Policies - Restrict Adobe Flash Player’s access to data. Default value: none

While secure_headers provides sensible safe default settings, it is essential to tailor them to your application’s specific needs.

Additional Resources

If you’re interested in reading more about securing your Rails applications, here is a list of useful resources:

Conclusion

While Rails provides a lot of security features, there are at least 4 ways to level up your application’s security with these great tools:

bundler-audit to find dependencies that are known to have vulnerabilities
brakeman to find idioms/calls that could be dangerous for your application
rack-attack to defend your application against bad, abusive clients
secure_headers to quickly apply several security headers to all your responses

This list is by no means exhaustive but it shows some of the key tools you can use to stay on top of potential security issues.

Although tools like bundler-audit and brakeman are helpful in identifying potential vulnerabilities, they should not be solely relied upon.

As a team, you should define a comprehensive security strategy which includes regular code audits, code reviews, and penetration testing.

Happy hacking!

PS: Need a code security audit? Contact us!

Introduction to Rails Engines

Ernesto Tagwerker (he/him) — Tue, 23 May 2023 18:58:06 +0000

Rails Engines are an architectural pattern that can be used to modularize a Rails application. They are self-contained applications that can be mounted within a larger Rails application. In this post, we will dive into the world of Rails Engines and explore what they are, how to create them, how to use them, when to use them, and why they are important.

What are Rails Engines?

Rails Engines are essentially mini-applications that can be plugged into a larger Rails application. They allow you to modularize your code and keep it separate from the core application. This makes it easier to maintain and update the codebase as a whole.

Engines can include models, controllers, views, and assets, and they can also have their own routes and configurations. For example Devise, an engine that provides authentication for a host application, has its own views, controllers, routes and configurations.

It is worth mentioning that Rails Engines are similar to Railities.

However, they differ in that Railities are simple Ruby modules that includes various hooks into the Rails initialization process, such as configuring middleware or adding new generators, whereas a Rails Engine has a more complex directory structure and includes everything needed to function as a standalone application, such as controllers, models, and views.

How to Create a Rails Engine

Creating a Rails engine is a relatively simple process. To create a new engine, run the following command in the terminal:

rails plugin new payments --mountable

This will create a new Rails engine in the payments directory with the --mountable option, which means that the engine can be mounted within another Rails application. Please note that the --mountable option is very important as running the above command without it will create a typical plugin which is not mountable. Below are the files generated by the above command:

$ bin/rails plugin new payments --mountable
      create  
      create README.md
      create Rakefile
      create payments.gemspec
      create .gitignore
      create Gemfile
         run git init from "."
Initialized empty Git repository in /ombulabs.com/payments/.git/
      create app
      create app/controllers/payments/application_controller.rb
      create app/helpers/payments/application_helper.rb
      create app/jobs/payments/application_job.rb
      create app/mailers/payments/application_mailer.rb
      create app/models/payments/application_record.rb
      create app/views/layouts/payments/application.html.erb
      create app/assets/images/payments
      create app/assets/images/payments/.keep
      create app/models/concerns
      create app/models/concerns/.keep
      create app/controllers/concerns
      create app/controllers/concerns/.keep
      create config/routes.rb
      create lib/payments.rb
      create lib/tasks/payments_tasks.rake
      create lib/payments/version.rb
      create lib/payments/engine.rb
      create app/assets/config/payments_manifest.js
      create app/assets/stylesheets/payments/application.css
      create bin/rails
      create test/test_helper.rb
      create test/payments_test.rb
      create test/fixtures/files
      create test/fixtures/files/.keep
      create test/controllers
      create test/controllers/.keep
      create test/mailers
      create test/mailers/.keep
      create test/models
      create test/models/.keep
      create test/integration
      create test/integration/.keep
      create test/helpers
      create test/helpers/.keep
      create test/integration/navigation_test.rb
  vendor_app test/dummy
      append /ombulabs.com/Gemfile

Once you have created your engine, you can add models, controllers, views, and assets just like you would in a regular Rails application. You can also define your own routes and configurations within the engine.

How to Use Rails Engines

Using a Rails Engine is also straightforward. The engine needs to be specified inside the Gemfile and run bundle install:

gem 'payments', path: 'payments'

To make our Payments engine’s functionality accessible from within our application, we need to mount it in the host application’s config/routes.rb file. However, it is not always the case as we can use the engine functionality without mounting it:

mount Payments::Engine, at: "/payments"

This will mount our Payments engine at the specified path within your application. You can now use the models, controllers, views, and assets from the engine just like you would in a regular Rails application.

When to Use Rails Engines

Rails Engines are particularly useful when you want to modularize your codebase and keep it separate from the core application. This is especially helpful when you are working on a large project with multiple developers, as it allows you to separate responsibilities and avoid conflicts.

Engines can also be used to create reusable components that can be shared across multiple applications. For example, in an e-commerce context, you could use Rails Engines to build separate modules for different aspects of the site, such as product catalog, shopping cart, payment gateway, and order management.

Each module could be developed and tested independently and then mounted within the main Rails application. This approach would allow you to scale each module independently as needed, and also make it easier to reuse the code across different e-commerce sites.

Why Rails Engines are Important

Rails Engines are important because they provide a modular way to organize and share code within a larger Rails application. Here are a few key benefits of using Rails engines:

Code Reuse: Rails engines allow you to extract reusable code into separate modules, making it easier to share code across multiple projects. This can save time and effort in development, as you can develop and test functionality once and then reuse it in different contexts.
Modularity: By breaking up your Rails application into smaller, self-contained modules, you can make your codebase more manageable and easier to maintain. Each engine can be developed and tested independently, allowing you to focus on specific areas of functionality without worrying about breaking changes in the rest of the application.
Encapsulation: Engines provide a way to encapsulate functionality within a well-defined interface. This makes it easier to reason about the code and reduces the risk of introducing bugs or breaking changes in other parts of the application.
Scalability: Engines can be used to scale your application horizontally by allowing you to add or remove functionality as needed. This can help you to adapt your application to changing business requirements and user needs without having to make major changes to the overall architecture.
Customization: Rails engines can be customized to meet the specific needs of different projects or clients. This can be particularly useful in agency or consultancy contexts, where you may need to develop similar functionality across multiple projects but with slight variations in requirements.

By keeping your code organized and modularized, you can improve the overall quality and maintainability of your application.

Conclusion

In conclusion, Rails engines provide a powerful way to organize and share code within a larger Rails application. By breaking up your application into smaller, self-contained modules, you can make your codebase more manageable and easier to maintain. Engines allow you to extract reusable code, encapsulate functionality, and scale your application horizontally by adding or removing functionality as needed. Additionally, engines can be customized to meet the specific needs of different projects or clients.

While Rails engines may not be appropriate for every project or context, they can be a valuable tool for developers looking to create more modular, maintainable, and scalable applications. Whether you’re building an HR management system, an e-commerce site, or a content management system, Rails engines can help you to develop and reuse functionality in a more efficient and effective way.

For further reading you can go through the Rails guide for Engines.

Need help modularising your Rails application? Contact us and have the FastRuby.io experts help you with it!

Fixed-cost, Monthly Maintenance Services

Ernesto Tagwerker (he/him) — Tue, 23 May 2023 10:23:45 +0000

Ever since we started offering productized Ruby and Rails upgrade services and upgrade roadmaps, we’ve been interested in helping as many people and companies as possible.

Unfortunately, in the past we’ve had to turn down companies who wanted to work with us but couldn’t secure the minimum monthly budget to work with our experts.

I’m pleased to announce that we’re now offering new opportunities for startups and small businesses to work alongside our team.

In this article, I will share a few new options to collaborate with our team of experts who specialize in technical debt remediation.

Why

Recently I had the opportunity to connect with a lot of SaaS founders at MicroConf ‘23 which made me realize that there are many entrepreneurs, startups, and small businesses out there that want to pay off technical debt by investing a small amount of money per month.

While teams understand the need to remediate their technical debt, this very often loses priority to shipping features, releasing patches, and addressing other tasks prioritized in their product roadmaps.

Although everybody would like to upgrade their app as fast as possible, sometimes that’s just not in the budget. Instead, a good alternative can be to gradually work through your technical debt with a slower-paced retainer model.

What's included in our monthly maintenance services

Our fixed-cost, monthly retainer will include services to gradually reduce the technical debt in your application. Our services will include:

Ruby Upgrades
Rails Upgrades
Dependency Management
Performance Monitoring
Tech Debt Management
Security Patches

Ruby Upgrades

If your application could use a Ruby upgrade, we will submit a pull request that looks like this:

(Source: Upgrade to Ruby 3.2 on Points)

If your application is not properly configured to dual boot with next_rails, we will submit a PR that looks like this:

(Source: Set up dual booting on Benchmark.fyi)

This will be the basis of our work around dependency management.

We will make sure that your application can run with both versions of Ruby. If you are on Ruby 2.7, we will make sure that your test suite works with both Ruby 2.7 and 3.0.

Once we fix all the errors in your test suite, we will make sure that your staging environment works with the next version of Ruby. If anything goes wrong, we will make sure we patch all issues before we deploy the change to production.

Rails Upgrades

Similarly, we will gradually tackle Rails upgrade projects. We will use our years of experience to submit many, tiny pull requests that will upgrade your application taking baby steps.

We will make sure that your application can run with both versions of Rails. If you are on Rails 5.2, we will make sure that your test suite works with both Rails 5.2 and 6.0.

Once we fix all the errors in your test suite, we will make sure that your staging environment works with the next version of Rails. If anything goes wrong, we will make sure we patch all issues before we deploy the change to production.

If you are curious about the dual booting technique, we have been running the Rails upgrade workshop at RailsConf since 2019. Here is a recording of the workshop we delivered at RailsConf 2021

Dependency Management

While there are great tools out there that can quickly help you upgrade minor versions of your dependencies (e.g. Depfu), there seems to be a missing link between what we do (Ruby/Rails Upgrades) and what they do (shipping automated pull requests, upgrading one minor version at a time).

That’s where we come in. We will work on minor and major version upgrades (according to semver) for all of your dependencies.

We will submit one PR at a time. This will give us the opportunity to properly test, deploy, and monitor any issues in production.

Performance Monitoring

If your application is not currently using an Application Performance Monitoring (APM) service (e.g. New Relic), we will set one up for you. We’ll consider your needs and budget, to make the best recommendation.

Once your APM is up and running, we will keep track of low performance and high memory load issues. We will share a monthly report with the top issues we noticed as Ruby and Rails performance experts.

If you want a more in-depth analysis of your application’s performance, we can deliver our highly-rate and always insightful Tune Report.

While the Tune Report is not included in any of the monthly plans, our clients have found that they can recover their investment in about 3 months.

Tech Debt Management

As open source maintainers of technical debt projects like RubyCritic and Skunk we know how important it is to keep track of your code complexity, churn, and code coverage metrics.

On top of that, we know how difficult it is to communicate the problems with consistently increasing technical debt:

Reduced development velocity
Constant regressions
Undesired side effects when deploying small changes

We can help with that! Every month you will get a report on your technical debt, not just on the codebase, but also in your development workflow, infrastructure, and best practices.

In this report we will include any changes that were made to simplify complex code structures, enhance your development workflow, or anything else that was shipped to make your codebase easier to maintain.

Our goal is to gradually improve code quality without disrupting your development team’s operations.

If you don’t have a shared understanding of what “code quality” really is, we can help you define one that works for your team. After that we can help you “codify” your code quality definition with tools like reek, rubocop, andrubycritic.

Security Patches

Picture this: On day one of our engagement our team will perform a quick security assessment of your codebase. This will give us an idea of the work to be done to secure your application from known exploits and potential attack vectors.

Every month we will make security patches that will level up the security standards for your Rails application. Depending on the severity of the issues we find, we might prioritize this topic on day one.

Pricing

Are you ready to make your application more maintainable?

Considering our 10+ years of experience upgrading applications, and more than 20,000 developer hours paying off technical debt, we believe we can offer meaningful updates to your codebase starting at $1,000 per month:

Shito : $1,000 per month
Shohin : $2,000 per month
Komono : $3,000 per month

Each package includes a maximum number of hours per month that we can invest in your application. When naming these packages, we decided to go with Bonsai types because we see a lot of similarities between pruning Bonsai trees and gradually paying off technical debt. 🌳

Shito

This is a great package for organizations and companies that either don’t have a lot of technical debt or want to go slow.

Their test suite might be well-written, their Rails application might be a small monolith, or their development team would be overwhelmed with more than 2 pull requests per month.

Shohin

This is a great package for organizations and companies that have some technical debt, know they need to fix it, and are ready to review from 2 to 4 pull requests per month.

Their test suite might need some attention, their Rails application might have between 50 and 150 models, or they’re one or two versions behind the latest stable release of Ruby and Rails.

Komono

This is a great package for organizations and companies that are ready to ship 3x more than if they had chosen the Shito package.

Usually their Rails application is rather large, their main dependencies (Ruby and Rails) are a few versions behind, their test suite is flaky, or they need to move fast and upgrade things.

Depending on the plan that you pick, we will invest from 5 to 20 hours per month remediating technical debt in your application/s.

Strategic Projects

We know that every now and then our clients will have one-off, strategic projects they will want to ship as soon as possible and we want to be able to help.

When that happens, we can offer our services on an hourly basis to ship value in the form of features, infrastructure upgrades, bug fixes, or anything that will make a difference in our clients’ businesses.

Rescue Services

Our monthly packages don’t include rescue services. If your application needs to be rescued, we can certainly help! We’ve done this many times in the past and we are happy to get you out of a thorny situation.

For these projects, we need to start with a short, one-week retainer to kickstart the rescue project. This will give us time to assess the situation, come up with a rescue plan, and start executing it.

How does it work?

We are used to working with teams of all sizes. From engineering teams of one to teams of 50+ software engineers, we see every engagement as a successful collaboration between our team and your team.

We thrive when we collaborate with our clients’ engineering team on a daily basis, so we will have a channel to communicate asynchronously. If you need to get on a call, we can do that too!

Any of the changes that we submit will be open for review and discussion. We will clearly explain why they are necessary, what the changes will do, and what impact they will have in your tech debt scorecard.

Communication is key to us! We provide you with a monthly report on your technical debt, including codebase, development workflow, infrastructure, and best practices. We are always open to hearing your thoughts and needs and answering your questions.

Summary

Our commitment to helping people and businesses overcome their technical debt is stronger than ever.

We are excited to launch our new monthly maintenance packages tailored for non-profit organizations, startups and small businesses. We are certain we will gradually reduce technical debt in their applications.

Our technical debt remediation services, provided by a team of experts, include dependency management, Ruby upgrades, Rails upgrades, performance monitoring, tech debt management, and security patches.

These three affordable plans starting at $1,000 per month are cashflow-friendly, consistently add value to your codebase, and give you access to our team of legacy code experts.

You can expect to see gradual improvements in your code quality and overall decreasing technical debt while keeping your development team’s velocity uninterrupted.

“The typical development organization can increase their feature delivery efficiency by at least 25% by managing technical debt. That’s the equivalent of having 25% more developers without additional staffing costs or** coordination needs**.”

(Source: CodeScene Whitepaper)

What would you do if you had 25% more development efficiency? How much more could your development team deliver in a month?

Let us be your trusted partner in making your application more maintainable, secure, and efficient.

Ready to pay off technical debt? Send us a message!

7 Common Mistakes in Rails Upgrades

Ernesto Tagwerker (he/him) — Tue, 25 Apr 2023 00:30:00 +0000

(This article was written by Rishi Jain and originally published in the FastRuby.io Blog)

Ruby on Rails is a popular web application framework that is constantly evolving with new versions being released frequently. While upgrading to a newer Rails version can bring new features, better performance, and security patches/improvements, it can also be a challenging task.

In this blog post, we will discuss 7 common mistakes made while doing Rails upgradesand how to avoid them.

Skipping Versions

We have seen customers trying to upgrade Rails from 5.2 to 7.0 and Ruby from 2.5 to 3.1 all under one single pull request and failing to deploy a successful version on production.

The problem with this approach is that it becomes extremely difficult to point out where the problem lies when your user encounters a bug in the app.

Did it happen when you upgraded from Rails 5.2 to 6.0 or in any other jump? Did it happen due to a deprecation warning that was supposed to be handled in Rails 6.0 to 6.1 jump but you skipped that as you tried to upgrade directly from Rails 5.2 to 7.0?

Another problem here is that you miss the chance to achieve small wins by deploying relatively small upgrades to production and thus exposing yourself to greater chances of encountering bugs and downtime to your app.

The only way to avoid these problems is to take a step-wise approach of upgrading only one major or one minor version at a time. If we were to upgrade an app from Rails 5.2 to 7.0, we would first upgrade it to Rails 6.0, deploy to production, then upgrade to 6.1, deploy to production, and then upgrade to 7.0 and deploy to production.

The Rails Guides also have documentation for changes involving each version jump which makes your job easier. For example: here is a documentation guide for upgrading the app from Rails 6.1 to 7.0.

If you also have to upgrade Ruby along with Rails, then the ideal approach is to upgrade them individually. This way you can minimize the risk of bugs creeping in.

Ignoring Deprecation Warnings

We have seen some clients silencing the deprecation warnings instead of addressing them. The reason deprecation warning exists is to alert developers of a behavior of the framework, ruby, or another gem that will not be supported in the future and to give them time to move away from the deprecated behavior which will eventually not be supported.

The problem with silencing the warning is when the deprecated behavior is no longer supported, it will break the application and the developer will have to either roll back the upgrade or make changes to the app really quickly and no developer would like to be in that situation.

Additionally, addressing the deprecation warnings are fairly straightforward most of the time, and the deprecation warning message also indicates how to fix / change the code to get rid of the warning.

It is way easier to address a deprecation warning that is explicit (it tells you the code, the change and the line that’s triggering it) than fixing a bug that you don’t know where it’s happening and what is causing it.

We’ve seen hours of work of debugging to end up finding that the bug was due to something that had a deprecation warning which was never addressed.

Upgrading Gems

When you are upgrading Rails, chances are that you are going to upgrade other gems along with it. But, how do you find out which gems need to be upgraded and to what versions? There are 2 ways to go about this.

First, running bundle update and then it will update every gem to the most compatible version. The problem with this approach is that since it is going to_update all the possible gems_ with a compatible higher version, you are exposing yourself to more bugs which can come due to code / behavior changes in the upgraded gems.

Second, running bundle update rails and then it will break with incompatibility messages across your gem set and with errors indicating which gems need to be updated. The downside to this approach is that it takes longer as you have to manually upgrade gems iteratively until the bundle update is successful.

The upsides are huge though as chances of bugs creeping comes down as you have only upgraded gems that absolutely needed to be upgraded.

You can read more about it here.

Undocumented Monkey Patches and Forking gems

Yes, Ruby is great because the powers it gives you and one of them is monkey patching existing behavior. This is great because it solves your problems in the short term.

But we have seen enough projects where the monkey patched behavior is left with no comments explaining why it was done in the first place and the developer who did this is no more working at the organization to explain and now you are left with no option but to make sense of the patch work all by yourself which is very close to guess work.

Another big problem we have encountered over the years is forking gems. Lots of times, developers fork open source gems and make changes to it to fit their needs.

But those changes are never submitted to the open source project and the reason for the fork is left to yourself without documenting it. Now it is the team who is working on the upgrade that is left to make sense of why the fork was done, and is it safe to go the released rubygems version of it or make the fork work with the upgraded Rails and other gems.

Lack of test coverage or testing strategy

To ensure that the upgrade of the Rails app is successfully released on production, you need either of the 2 things at least.

First, a good test coverage of your application. Anything above 80% test coverage is considered good if it includes coverage of the critical paths of the applications.

Second, awareness of all the critical paths of the application and ability to test them manually.

If you do not have either of the 2 things in place, it increases the chances of encountering bugs upon releasing it on production. Even with both the strategies in place, you can still set yourself for a buggy release on production and that can be due to not having a dedicated QA team or QA role defined in your workflow.

When the developer doing the code review on the pull request ends up doing the QA of it as well it is not an ideal situation. It can lead to bugs not caught before they are released to your users.

Not using the right tools

There are many ways to go about upgrading your application, but choosing the right tools and the right strategy can go a long way in making your experience smooth.

Something as trivial as branching and code arrangement strategy holds a lot of importance in your workflow. We have seen a lot of teams struggle or end up doing repetitive work because of lack of clearly defined strategy.

To avoid confusion on how to run the upgrades, we contribute and maintain the next_rails gem which:

Helps us in running 2 different versions of Ruby or Rails in the same branch
Facilitates running specs for the 2 different versions of Ruby or Rails from the same branch

This goes a long way in debugging issues while doing upgrades without switching branches. It also helps in implementing a gradual deployment strategy with Kubernetes.

We have also seen customers trying to do everything “the Rails way” when it does not make sense for them.

For example, Active Storage is a great gem and very useful for someone allowing users to upload files. But one of our customers wanted to use Active Storage even though their use case did not fit to use it.

What they already had made more sense for them. Using Active Storage would have made their systems more complex. So it is also important to know when to move away from the defaults.

Not Having a Rollback Plan

Finally, not having a rollback plan is a common mistake made while upgrading Ruby or Rails.

Despite careful planning, unexpected issues can arise during the deployment. It is important to have a rollback plan in case of any issues that may arise during the deployment process.

A rollback plan should include steps to revert to the previous version of Rails, restore db backups, and fix issues that caused the rollback.

Conclusion

Upgrading your Ruby or Rails version is essential for keeping your application secure and up to date.

However, upgrading can be a challenging task, especially when you make common mistakes.

In this article, we discussed 7 common mistakes that developers make when upgrading Ruby or Rails and how to avoid them. By avoiding these mistakes, you can make the upgrade process smoother and less stressful.

In conclusion, upgrading Rails can be a daunting task, but with the right approach, you can make it a seamless process.

Happy upgrading!

PS: Need help upgrading Ruby or Rails to their latest stable version? We have some availability to help your team upgrade Ruby/Rails!

How to Upgrade Rails Without a Test Suite

Ernesto Tagwerker (he/him) — Wed, 13 Jan 2021 09:00:00 +0000

Sometimes you will be caught between a rock and a hard place. For example: You really need to upgrade your Rails application because Heroku is discontinuing your stack in two weeks so you don't have the time to write an entire test suite.

Sometimes the situation will be that your boss really needs you to upgrade Ruby or Rails to use a version that gets security updates and they won't allow you to write tests beforehand.

This article will explain how to ship a Rails upgrade project without a test suite. If your application has no tests, you will learn how to upgrade without having to write tests first.

Set up Staging
Check the Changelog
Write a Testing Script
Set up Error Tracking
Set up Dual Booting
Upgrade Development and Test
Deploy to Staging and Test
Deploy to Production
If you have the time, write integration tests
Summary

1. Set up Staging

Have a staging server that is identical to your production server. You will need to thoroughly test your changes in a staging environment before you deploy any changes to production.

Strive to make this environment as similar to production as possible. Fill it up with production-like data, so that you can test real world scenarios.

2. Changelog

Many of the changes in the new Rails version won't affect your application. Read the most notable changes in the changelog and manually find whether the APIs that changed are getting used in your application's code.

In this step there will be a lot of grepping or finding in files within your code editor. If you want to learn how to do this, we wrote an article about that: How we upgrade Rails applications

3. Write a Testing Script

If you know the application from top to bottom, write down several manual test scenarios. If you don't, work with the product owner to define a set of steps that you can run to smoke test the application in your development, staging, and production environments.

4. Set up Error Tracking

If you don't have this configured, make sure that you set it up before you deploy anything to staging or production.

There are many options when it comes to error tracking. Some of the most popular alternatives are Sentry; Honeybadger; or Rollbar. This will come in handy when you deploy your code and you get real users using your application on the new version of Rails.

Considering your application does not have a test suite, I can guarantee that you will get exception notifications once your code is live. You want to make sure that you can get all the necessary information so that you can quickly patch those bugs.

Even applications with a solid test suite and great code coverage will find exceptions in production. So this is a great idea even if you are not deploying a major Rails upgrade. :)

5. Set up Dual Booting

This will help you with the next steps across all your environments. Using this technique you will save a lot of time, because you will be able to run your application with Rails X or Y by changing a single environment variable.

We have explained how to dual boot in this article:How to Dual Boot Ruby on Rails

6. Upgrade Development and Test

If you have set up dual booting correctly, you will be able to run your current Rails version like this:

bundle exec rails server

And your new Rails version like this:

next bundle exec rails server

Now you can start smoke testing your application in your development environment. This step will include a lot of steps that look like this:

Read and execute your testing script
Monitor your logs and error tracking service
Find issues
Patch them
And repeat...

Once you feel comfortable that you have tested your critical user paths and everything looks good, you can move on to deploying your changes to your staging environment.

7. Deploy to Staging and Test

Now you are at a point where you can involve your QA team. Once you have deployed and tested your changes in staging, you can involve more people in helping you manually test critical user flows.

8. Deploy to Production and Test

There are two safe-ish ways to deploy your Rails upgrade to production:

Gradual deployment
Full deployment

Gradual deployment

This is another step that benefits from your dual booting code. You can deploy your changes to only a few application instances in your cluster. Then you will have your cluster running both versions in parallel (Rails X and Y).

You can set up your production environment to direct only 10% of the traffic to the new version of your code. This article explains how you can do that:Continuously Integrating a Major Rails Upgrade

Full deployment

If your application does not get a lot of traffic at night, you might want to deploy your changes to all your visitors then. This approach is certainly riskier because slower traffic means fewer users which means fewer "testers" for real world scenarios.

In both scenarios, you will eventually sit and wait for errors. Depending on the severity of the errors, you might want to roll back your changes and go back tostep 6.

If there are only a few minor bugs, you might want to hot fix them in production.

9. Integration Tests

If you have the time, I would highly recommend writing some integration tests. You can use RSpec and Capybara to write some simple tests to view them in a browser.

You don't have to get too creative when writing these tests, you can basically write something like this:

# spec/features/homepage_spec.rb
require "rails_helper"

RSpec.describe "Homepage at FastRuby.io", js: true do
  it "does not blow up" do
    visit "/"

    expect(page).to have_text("Need to upgrade Rails but don't have the time?")
  end
end

You can write basic, smoke-testy integration tests that mimic the behavior of end users and get to a non-zero amount of code coverage in a few minutes. If you have the time, doing this will save you time in your workflow.

Summary (TL;DR)

Someone is going to test your application. It could be you, writing automated tests and increasing code coverage. It might be your QA team, testing things work as expected in staging and production. In the worst case, it will be your end users trying to do something in production.

If you don't have a test suite, it does not mean that you cannot upgrade a dependency of your application. It usually means that it will take longer than if you had a well-written test suite, because there will be a lot of manual testing during the project.

How to Prepare Your Rails App for an Upgrade

Ernesto Tagwerker (he/him) — Tue, 29 Dec 2020 09:00:00 +0000

This article is part of our Rails Upgrade series. To see more of them, click here.

This article will cover the most important aspects that you need to know to prepare your Ruby on Rails application for working on an upgrade.

Test Coverage
Staging and Production
Patch Version
Incompatibilities
Dual Boot

1. Code Coverage

Not all applications are good candidates for a Rails upgrade project. We strongly advise against upgrading big applications which are running in production with minimal test coverage.

Make sure that you have at least 80% test coverage before starting the upgrade project. If you don't have a solid test suite (or a dedicated QA team), you will likely find many problems which will force you to roll back the upgrades as soon as they hit production.

You can easily calculate your coverage by using simplecov. Here is a tutorial about how to use it.

2. Staging and Production

We advise all of our clients to follow a Git flow workflow and to actively manage at least two environments: staging and production.

Every change should be code reviewed using pull requests and it should run the entire test suite. Once all checks have passed, changes should be deployed to staging. After your QA team has tested your critical flow in staging, you can deploy the changes to production.

3. Patch Version

Before working on an upgrade you should make sure that you are running the application with the latest patch version. That way, you make sure that the latest security patches have been installed. On top of that, with more recent versions, you will get a series of deprecation warnings that will be useful in finding out what needs to be done.

4. Incompatibilities

Have you ever gotten tangled in dependencies? You need to upgrade dependency A, but that's incompatible with Rails 5.0 because dependency B (which is a dependency of A) is not compatible with that version of ActiveRecord).

Before you start going down the rabbit hole, make sure to check your Gemfile.lock for incompatibilities. For that, you can use this website: https://railsbump.org/

That will give you an idea of how many dependencies are not compatible with Rails 4, 5, or 6.

5. Dual Boot

To help you switch between your current Rails version and the new one, you can create a dual boot mechanism. The fastest way is to install the handy gem next_rails. You can initialize it by doing

$ gem install next_rails
$ next --init

You can then set up two Rails versions in your Gemfile like this:

if next?
  gem 'rails', '~> 6.0.0'
else
  gem 'rails', '~> 5.2.3'
end

Sometimes dependencies are backwards compatible with the current version of Rails. Within the libraries, you will find code that looks like this:

if Rails::VERSION >= 5.1
  # does X
else
  # does Y
end

If that is the case, then you might be able to just upgrade the dependency using bundle update.

Next Steps

Now that you have laid the groundwork for you upgrade, it is time to start the work itself. For details on what you specific version upgrade will require, check out the corresponding guide:

Churn vs. Complexity vs. Code Coverage

Ernesto Tagwerker (he/him) — Wed, 13 May 2020 02:25:00 +0000

Churn vs. Complexity analysis is a great way to find insights about the maintainability of a project. Two of my favorite authors have written great articles about the Churn vs. Complexity graph:

Getting Empirical about Refactoring by Michael Feathers
Breaking up the Beheamoth by Sandi Metz

This two-dimensional graph can be very useful in finding the files that are the hardest to maintain in your application. In this article I will explain:

How you can calculate these metrics and use them in your legacy project
How code coverage metrics can guide your technical debt's collection efforts

Churn

Churn by itself is a useful metric. It will tell you which files are the ones that are constantly changing. Change takes time, so files that are constantly changing are costing you time and money.

It will make you wonder:

Why are these files changing so much?
Are requirements constantly changing?
Are we truly understanding business rules correctly?
Is our application poorly designed?

If your legacy application is written in Ruby, you can use a gem called churn to find the files that are constantly changing.

Calculating Churn in Ruby

You can install churn like this:

gem install churn

Then call it like this:

churn -e rb --start_date "10 years ago" lib -i spec

This will show you a list of files sorted by their churn count (number of times that the file has changed in the SCM that you are using)

**********************************************************************
* Project Churn
**********************************************************************

Files
+-----------------------------------------------------------------------------------+---------------+
| file_path | times_changed |
+-----------------------------------------------------------------------------------+---------------+
| lib/metric_fu.rb | 50 |
| lib/metric_fu/version.rb | 44 |
| lib/metric_fu/configuration.rb | 36 |
| lib/metric_fu/reporting/templates/awesome/awesome_template.rb | 29 |
| lib/metric_fu/io.rb | 23 |
| lib/metric_fu/formatter/html.rb | 23 |
| lib/base/configuration.rb | 23 |
| lib/metric_fu/run.rb | 22 |
| lib/metric_fu/metrics/saikuro/saikuro.rb | 20 |
| lib/metric_fu/metric.rb | 20 |
+-----------------------------------------------------------------------------------+---------------+

By itself, this metric provides a limited insight:

These are the files that have changed the most since the beginning of the project

It doesn't provide insights into why these files are changing as much as they do. If you open these files in your editor, you might find that files with high churn are super complex or super simple.

Complexity

As you go about making your changes, you will introduce complexity. There is noway around it. The best way to have no complexity is to have no code.

It doesn't matter whether you are a rockstar object-oriented architect or a novice programmer. You will introduce complexity into a project.

"Complexity" should not be considered a negative term. "Unnecessary complexity" might be considered an anti-pattern. Good object-oriented programming calls for loose coupling and high cohesion.

You want modules that follow SOLID principles. When you notice your module is becoming extremely complex, you will want to refactor it into two or more modules. These modules will send and receive messages between each other, which will increase coupling (as loosely as possible) and hopefully improve cohesion per module.

As you go about submitting pull request to ship new features, change existing ones, or patch bugs, the maintainability of your project will vary according to the modules you introduce or change.

The bigger the project, the more complexity, the harder it will be to maintain it, because there will be more moving pieces and loosely coupled modules.

If you refactor a huge module, into two smaller modules, you will notice that cognitive complexity per module will (hopefully) get better. You won't have one huge, complex module anymore, you will have two or more modules that are easier to understand.

Modules that have one and only one responsibility will be easier to maintain and test. Future changes will be easier because you will be able to quickly understand what the module is doing.

In the next section I will explain how you can calculate complexity for all your Ruby modules.

Calculating Complexity in Ruby

There are many tools out there (e.g. three awesome libraries to assess code quality) that can help you find the most complex files in your project. One of the most popular tools in the Ruby world is flog.

Attractor uses flog to calculate complexity for each module. I really like the report that it generates. You can see all the modules in one page:

By itself this metric can take you in the wrong direction. Sometimes you will find extremely complex files which never change. So they are likely not your priority when it's time to refactor code.

Churn vs. Complexity

In his article, Michael Feathers, states the following:

These diagrams give us quite a bit of information. The upper right quadrant is particularly important. These files have a high degree of complexity, and they change quite frequently. [...] These classes are particularly ripe for arefactoring investment

I agree that this graph is great for finding refactoring candidates. The problem is that sometimes these candidates have no tests to verify their behavior. So sometimes we don't have time to:

Write tests
Refactor complex files

Sometimes we have to pick one or the other. So in my opinion it would be great to include another metric into our analysis: Code Coverage.

Code Coverage

When we start maintaining a module, we don't usually just look at its churn and complexity. We also look at the tests that describe its expected behavior.

Usually a module that has a decent test suite (basic code coverage) will be easier to understand than one without tests. We will have one more resource to learn about a module's behavior.

Code coverage metrics don't tell whether the test suite is good or bad. It tells you how many statements of your application are exercised by your test suite. You should not blindly trust code coverage percentages without doing a quick code review of the tests that are present.

Don't you just love it when a module has great tests that describe the expected behavior of its public API?

Churn vs. Complexity vs. Code Coverage

When I look at all the modules in the project, I want to know:

How many times has this file changed since the beginning of the project? (Churn)
How complex is this module? (Complexity)
What's the code coverage associated with this module? (Code Coverage)

This new dimension will tell us which files are the most changed, the most complicated, and the least covered with tests.

Refactoring modules that lack proper tests can quickly turn into a nightmare. You don't want your refactoring efforts to blow up in your face when changes hit production. And you probably don't want to test all your changes manually.

By adding a third dimension to the churn vs complexity graph, you will be able to gather new insights about your modules:

Should I refactor this module?
Should I increase test coverage before I refactor this module?
Do I have time to do both this week?

Calculating a Churn vs. Complexity vs. Code Coverage Graph in Ruby

Last year I published a library that can help you take all these metrics into account: Skunk. It relies on RubyCritic and SimpleCov to get all the metrics it needs.

You can install it like this:

gem install skunk

And run it like this:

skunk lib/

It won't generate a graph (yet) but it will generate a table with all the modules in the lib directory. It will sort files from worst to best (in terms of technical debt):

+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+
| file | skunk_score | churn_times_cost | churn | cost | coverage |
+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+
| lib/skunk/cli/commands/default.rb | 166.44 | 1.6643999999999999 | 3 | 0.5548 | 0 |
| lib/skunk/cli/application.rb | 139.2 | 1.392 | 3 | 0.46399999999999997 | 0 |
| lib/skunk/cli/command_factory.rb | 97.6 | 0.976 | 2 | 0.488 | 0 |
| test/test_helper.rb | 75.2 | 0.752 | 2 | 0.376 | 0 |
| lib/skunk/rubycritic/analysed_module.rb | 48.12 | 1.7184 | 2 | 0.8592 | 72.72727272727273 |
| test/lib/skunk/cli/commands/status_reporter_test.rb | 45.6 | 0.456 | 1 | 0.456 | 0 |
| lib/skunk/cli/commands/base.rb | 29.52 | 0.2952 | 3 | 0.0984 | 0 |
| lib/skunk/cli/commands/status_reporter.rb | 8.0 | 7.9956 | 3 | 2.6652 | 100.0 |
| test/lib/skunk/rubycritic/analysed_module_test.rb | 2.63 | 2.6312 | 2 | 1.3156 | 100.0 |
+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+

The SkunkScore is a function of complexity and code coverage.

Let's say that your application has two extremely complex modules: user and product. Let's assume that both of them have changed a lot (churn count at 100) and are extremely complex (1,000 flog points).

In this example, if user has more tests than product, user's SkunkScore will be lower than product's. Next week you could start refactoring user or increasing code coverage for product

By looking at this table you will be able to quickly decide about what to do: You might want to write tests for a complex module, refactor a complex module that is well covered by integration tests, or both!

Code Coverage as a Prioritization Mechanism

In big projects you might notice hundreds of modules in the upper right quadrant of the Churn vs. Complexity graph. You might ask yourself: What do I do first? Do I write a test for module User? Do I refactor module Product?

I strongly believe that Code Coverage is a great signal for complementing churn and complexity metrics. I hope you can use it in your next legacy project to gradually pay off technical debt!