DEV Community: Braden King

Why I'm Still Using jQuery in 2025 (Never gonna give you up)

Braden King — Fri, 07 Nov 2025 02:33:47 +0000

While grinding through the monumental JuggleBee upgrade, one of the recurring debates was: what do we modernize, and what do we leave the heck alone? Plenty got a shiny new coat of paint (see my earlier posts for all the juicy details), but one area I deliberately left untouched was the frontend JavaScript. These days, jQuery is seen as a relic of a bygone era — a noble steed well past its sell-by date. Hotwire now ships as the Rails 8 default, and heavyweight contenders like React and Vue have taken over the frontend spotlight.

Why I Kept It

So why didn’t I replace it with Hotwire or Stimulus when doing the big Rails 8 overhaul?

Because honestly... it still slaps.

Sure, jQuery has fallen out of favour, and yes, I could’ve followed the modern path. But here’s the reality:

It still works. Flawlessly.
The architecture is solid. It keeps behavior modular and scoped. No random scripts firing across unrelated pages.
It’s expressive and readable. You can look at the markup and know exactly which components will be applied.
Rewriting it would’ve cost me weeks — and yielded very little gain for the effort.

It’s easy to chase shiny new frameworks. But this setup? It’s already solved the very problems frameworks like Stimulus are trying to address — just in our own way, before they existed.

"Technical debt isn't defined by age. It's defined by pain."

This jQuery-based framework causes me zero pain. It’s clean, consistent, and extendable. And I’m not paying a complexity tax for keeping it around.

A Beautiful Framework

Back in the yonder years, when development on JuggleBee first commenced, jQuery was king. "Write less, do more" as the slogan proudly declared. These were the days before Turbo, pre-SPAs, when frameworks like React were still internal tools being tinkered on at Facebook. Even then, I liked my code clean, purposeful, and targeted. Every function should do its job — and only its job — exactly where it’s meant to. The typical jQuery spaghetti of the time grated on me.

Take this scenario: I’ve got a lovely Select2 dropdown on the listings page to filter by category. All good. But why is that whole library still being pulled in and initialized on the About Us page, which has no dropdowns in sight? This was a symptom of how jQuery scripts were commonly written — everything ran everywhere. I wanted modularity, not mayhem. And so, the “Behaviour Framework” was born.

So what exactly did we build?

In essence, it's a lightweight, declarative behaviour system — think of it like a primitive version of Stimulus or Alpine. Components declare themselves in the markup, and a central engine takes care of the wiring when the DOM loads. This means zero manual JS in our views, and zero unnecessary script execution across unrelated pages.

Let me show you how it works...

At the heart of it all is the Behaviour class. Its role is simple but powerful: register UI components and apply them only when needed — and only on the elements that require them. Here's a high-level look at how it works under the hood:

// Note: classes didnt exist so the "Class" we're calling below is a custom implementation
Framework.Behaviour = new Class({
  filters: {},
  addFilter:function(name, instantiator){
    this.filters[name] = instantiator;
  },
  addFilters:function(filters){
    for (const filter in filters){
      this.addFilter(filter, filters[filter]);
    }
  },
  apply:function(wrapper){
    this._scan(wrapper, $.proxy(this._apply, this));
  },
  unapply:function(wrapper){
    this._scan(wrapper, function(target, behaviourClassName){
      var behaviourResult = target.data('getBehaviourResult')(behaviourClassName);
      if (typeof behaviourResult.deinit === 'function'){
        behaviourResult.deinit();
      }
    });
  },
  // rest of the implementation ...
});

This allows us to define small, focused components — like a date picker — in total isolation. No global bleed. No script soup. Just self-contained behaviour.

One of the earliest components we wrote using this system was actually said date picker. At the time, we were using Bootstrap and jQuery UI plugins — each with their own quirks. So we wrapped them up into their own isolated modules, making them easier to configure and reuse across different forms, pages, and even admin views.

Here’s what the class for that looked like:

Component.DatePicker = new Class({
    options: {
        startDate: '04/07/2015',
        format: 'dd/mm/yyyy',
        todayHighlight: false,
        weekStart: 0
    },
    init:function(element, options){
        this.setOptions(options);
        element.datepicker(this.options);
    }
});

Once defined, we simply register our component with the behaviour system so it knows how to wire it up when the time comes:

var App = {
  behaviour: new Framework.Behaviour
};

App.behaviour.addFilters({
  'Component.DatePicker': {
    setup: function (element, options) {
      return new Component.DatePicker(element, options);
    }
  }
)

$(function(){
  var body = $('body');
  App.behaviour.apply(body);
})

Now comes the beauty of it — in your HAML or HTML, you declare the behaviour directly in your markup using a data-behaviour attribute. When the page loads, only the relevant components are instantiated, and only for the elements that need them.

  = listing.input :start_date,
    as: :string,
    label: 'Start Date',
    placeholder: "e.g. #{example}",
    input_html: { value: (localize(date, format: '%d/%m/%Y')),
      data: {behaviour: 'Component.DatePicker', 'options-component.datepicker' => '{"startDate" : "' + example + '"}'}

And just like that, our behaviours are neatly attached, scoped, and easy to manage.

It’s clean. It’s obvious. And it means onboarding a new team member doesn’t require a 2-hour walkthrough of where the JavaScript magic lives — it’s all in the markup and component files.

This approach meant zero wasted cycles, faster page loads, and a far more maintainable codebase. Behaviourally-aware pages, declarative setup, and modular control over every UI component. In today’s parlance, it’s not far off what Stimulus or Vue’s component system offers — just built years earlier and tailored to our exact needs.

This is the short version — enough to give you a taste of how it all works. In a follow-up post, I’ll take a deep dive into the full implementation, including sibling systems like the EventBus, Trigger logic, Adapters, and more.

Credit where it’s due: this wasn’t a solo effort. The framework was shaped with the brilliant Paul Schwarz, and together we built something that — dare I say — still holds up surprisingly well in 2025.

jQuery Isn’t Dead. It’s Just Retired.

Do I recommend jQuery for new apps in 2025? Of course not.
But for apps that already have it — and especially those with a system like this layered on top — there's no real reason to tear it out just to chase trends.

This is the kind of code you keep because it works — not in spite of it.

Coming Up Next

In Part 2, I’ll take you on a deep dive into the guts of the Behaviour framework: how components are hydrated, how the EventBus enables decoupled comms between modules, how Trigger handles custom DOM events, and more.

It’s a little old-school, sure — but it's also still slick as hell.

Release Process

Braden King — Thu, 23 Oct 2025 23:42:44 +0000

After having followed the various conventions defined by our Git and GitHub processes, we should now be in a good place to take the code that has been produced, get it ready for QA, merge and release it. Every organisation will have their processes and workflows set around this, some good, some bad. I worked with my team to build a robust and practical release process which best suited our needs at the time, allowing for a quick development - QA - release lifecycle. We didn't quite achieve the continuous-release dream, but we got close.

Disclaimer: This is an evolving document which has been altered and tuned over the years. It may not apply to you and your situation but perhaps there is a nugget or two here that could improve your workflow and developer happiness.

QA / Testing

As anyone will know, the QA process of manually testing and sanity-checking code changes in a piece of work can often take 10 times the duration it took to make the changes in the first place, depending on the size of the changes requiring testing. No one wants to hand over some work for QA, and have the QA engineer spend a day testing it, only to find a silly bug or edge case which could have been caught by a code review or proper test harness, resulting in the PR being handed back to the developer to make the fixes, resetting any QA progress. QA time is limited and not to be wasted. Therefore, we do as much as we can before handing over to QA, ensuring to the best of our ability, that they have a bug-free, fully functional code change to test, limiting pushback.

1. Green CircleCI workflow

We were in a good place with our test coverage, with a minimum of 98% coverage. Our testing suite was split up over a parallelised CircleCI workflow allowing for relatively fast builds and giving us the chance to ensure our entire test suite went green before moving on to requesting developer reviews. 95% of the time, our test harness would catch any accidental bugs or code smells, enabling us to pass clean, "bug-free" code to the team to review.

For this post, I didn't bother waiting for the entire build process to go green before screenshotting, but you get the idea.*

2. Deploy to an integration environment

Thanks to our DevOps engineer, we had a flexible integration deployment system built right into CircleCI. On approval of integration deployment, a fresh new VM would be spun up, our code checked out, and all systems set up for manual testing. We would sanity check our changes on a "production" system because all too often, you hear the phrase "Well, it worked on my machine". Subtle differences between development and production environments can result in a working dev build failing in production. This also gives us a chance to properly document how QA should go about testing our changes for when it gets handed over. For much larger features, we would use these environments for demos and to demonstrate the new functionality to the rest of the team, assisting with their code reviews.

3. Developer code reviews

Once we were confident all tests and code quality checks were passing, and we have sanity checked our own work, we would then request two developer reviews. This gave other developers the chance to familiaralize themselves with the changes, and ensure the code was clean and well written, fully tested and optimised. Oftentimes, a fresh set of eyes might identify an edge case that was missed or realise that a query is N+1 and could be optimised. Be there required code changes or not, after all is resolved and the team is happy, they would provide their two green ticks on the PR. We would also ensure our branch commits are in a good state by having done an interactive rebase against master, squashing and/or renaming commits to follow our conventions.

4. Hand over to QA

Once we are confident that our code works, we have the approval of the team and we are happy that our manual testing and sanity checks have all passed, the PR finally gets flagged for QA. QA will then test our code on the integration environment we used for our testing (creating their bespoke test data) and be guided by our specified testing steps and notes. A QA intends to break the code, so it is at this point all the weird and missed edge case testing usually happens and bugs are discovered, if present. Regardless, once QA has taken their sledgehammer to the work, and finds it without fault, they will provide their final green tick on the PR, leaving the PR with a total of 3 green ticks. We are now in a state to merge the work into master.

Merging

Before we merge a branch to master, a couple of final steps are taken to ensure as smooth a process as possible.

1. Rebase and commit squashing

During the previous QA testing phase, there may have been various code changes required or bugs resolved. Before we commit to merging the branch after all the checks are green, we ensure our branch is up-to-date with the latest master by performing an interactive rebase against it, and squash any necessary commits, ensuring a clean, flat, and well-written git history is maintained (as per our Git Conventions). Ideally, there would have been no additional code modifications, so this step could be skipped as we do this before handing it over for dev review.

If there were merge conflicts that needed resolving, that means other work has made it in which may affect your code changes. In this instance, we would, based on the conflicts, possibly ask QA to go over the PR one more time before it gets merged, based off team decision.

2. Checking for migrations

Migrations can be tricky things. Testing a migration against a local database means nothing when run against a production database. Something as simple as changing a column name can bring an application to its knees if done incorrectly. Very often, one will see code-altering data in the database inside the migration (yes, this is a bad practice and shouldn't happen in a perfect world, but this is not a perfect world) which, when operating on millions of rows in a production database, can cause database locks and timeouts, failing the deployment process. Having been bitten too many times in the past by dodgy migrations requiring a release rollback, we opted to isolate any PRs that contained any database migration changes and deploy them as standalone. It is at this point that QA would flag the PR for isolated deployment to, in the worst case of a rollback, not have other PRs affected by the rollback.

3. Merging into `master`

Our master branch was protected against merging by everyone except our lead QA engineer, the most senior dev and the CTO. In 99.9% of instances, merging was done by our QA engineer, allowing for a controlled merge process. This also prevented untested code from sneaking into master under the guise of a "hotfix" or other such shenanigans.

Release

Our dream was to have rolling deploys - as soon as anything was merged into master, it would deploy. At the time of writing, however, we were working off manual releases, usually containing a handful of PRs.

Tag and generate release docs

GitHub made it easy to generate our release notes as it can do so automatically when creating a new release. Specify the new tag to be applied to master branch (major/minor/micro version bump), ask Github to generate the release notes and that's it. Thanks to our strict use of git commit conventions, the release notes description was clear without needing additional modification most of the time. For larger, more involved features, additional context would be supplied to better communicate the changes with our users.

Migration-induced isolated deployment

If a PR containing a database migration is flagged, a release will be created containing all previous PRs that have been merged since the last release, excluding the migration PR, and that will be deployed. The PR containing the migration would then get merged and a new release would be created straight away with only this PR. This was to ensure that there are no potential issues from compound migrations and also to allow quick and simple rollback should there be an issue. All this was made easier by having the master branch locked down to lead QA merging only, meaning nothing else could slip from elsewhere.

Press the button

Once the release tag has been created, the entire CircleCI build would run once more, running the entire test suite, including the slower integration test suite (not run by default) and once green, the release would be approved through CircleCI and off it goes. As we had a blue-green delivery process in place, a whole new cluster of pods would spin up with the new release, and only after all the various checks were completed ensuring all services were running without issue, we would have the load balancer switch over to the new pods and start killing off the old ones.

That's all folks

And that concludes part 3 of my documentation about the processes and workflows we built and fine-tuned over the years around the development lifecycle. It may not be perfect and there was a lot more we wanted to do (rolling deploys, etc) which we hadn't quite gotten to, but what we did have in place worked well for us. Sometimes the smallest change at the beginning of the process can produce significant wins at the end of the process. For instance, how our release note documentation was generated descriptively and concisely based on our git commit conventions, or how our GitHub documentation process helped us find where bugs were created years later due to easy searching.

All of these processes took some time, effort and accountability to become habits. There would be moans and groans when a PR was rejected because the branch name didn't match the pattern (look up Git move) or when an interactive rebase to squash that final "fix issue" commit tacked on during the review process was insisted upon, or blocking a PR until it had a decent enough description. Some might find these requests to be petty but looking back on the bubbling effect of them, the entire team would agree it was worth putting in that extra leg work at the end of the day.

Issue and Pull Request Conventions

Braden King — Sun, 12 Oct 2025 09:21:57 +0000

My previous post on GIT Conventions broke down various conventions around branching and committing code. As part of building a solid process around development, the next area to deal with is that of getting those branches and commits together for a merge and release. This is usually done via some sort of ticket on an issue tracker and code pull request. The following guide was developed as a collaborative effort with my team and lead to a more robust and progressive environment with improved communication and overall general happiness, even though it adds a little extra overhead.

Development Documentation

When it comes to software development in general, documentation about the work being performed is incredibly important. Not only for your own understanding but for that of your team (and future you/team). Developers are lazy; documentation is a chore and it just slows us down; we want to code and deploy at the speed of light! The number of times I've had to go hunting through hundreds of previous PRs with incomprehensible titles and missing descriptions in order to find the correct one which holds the change that introduced a bug, is way too high and wastes and inordinate amount of my time and sanity.

A feature request or support ticket can come in from many different sources, perhaps a verbal suggestion from a product manager, or a ticket from a bug reporting system like Zendesk to JIRA. In order to unify these multiple sources into a single source of truth for the development team, the feature / issue would be written down into a Github Issue (we favoured Github as our central work hub, making use of their great tools), referencing the source when available.

Once the issue was drafted, it's prioritised and assigned to a developer. The assignee would then spend a little time investigating the issue, collecting additional information, communicating with the various parties involved, and fleshing out the issue in a detailed and descriptive manner. With the issue in a good place, work can begin and once done, a PR created and linked to the issue. The PR didnt need to contain too much information, just a short description to help with searching for the most part, as the issue covers everything.

Issues

The central place for all information regarding a piece of work is the issue/ticket. We chose to use Github for our issues and pull requests however the structure defined here works with any project management tool. At the time, we had defined a ISSUE_TEMPLATE in our .github repository but that method is now deprecated in favour of the multi-issue type setup, however, each section still applies.

1. Description

The entrypoint and most important part of the issue. When developing a new feature, detail what the feature is, how it is intended to work, what problem will it solve and what was the reasoning behind this feature request in the first place. If the issue is a bug fix, detail what the bug is, how it was found and what was the cause of it, following with how you went about resolving it. This may sound like you need to write a thesis to explain the code change but all of this could easily be construed in a few concise sentences. It can take a little practice and if you're struggling to form a short but clear, comprehensive description of the task at hand, perhaps ask ChatGPT to summarise it for you :P

2. Links

This section contains all links associated with the changes needed so that those inspecting the issue can quickly and easily navigate to all related material. This could be other PRs which are linked to the change (perhaps backend and frontend PRs are necessary), the support tickets that spurred on the change, documentation or external resources (blog post, stackoverflow entry, etc) used in order to achieve the solution and whatever else could be of interest.

3. Integration Environment

At my previous employ, our CI/CD pipeline would deploy the PR to a newly spun up integration environment with seeded database in order for QA to have a running instance to test on. In the nature of providing all information in one place, this section included the URL to the CI/CD process responsible for creating (and destroying) the temporary environment, all associated web addresses to the various platforms and servers that might need accessing, as well as SSH instructions to the integration server in questions.

4. Testing Notes

This section allows you to define a structured and clear process for QA to test the changes you have made. Perhaps they are same as the reproduction steps cited in a bug report, or detail how to use a new piece of functionality. A step-by-step guide will help QA test your change but also identify where they could attempt to break it, ensuring you have put in place proper protection mechanisms such as validations or rescue conditions.

5.1 Migrations (Optional)

Database migrations can be a real headache if not done correctly. Sometimes a migration file will be added but the schema forgotten. Or the migration itself contains code to update a table with some new / altered values which falls apart on massive data sets. You may be able to correct mad migrations locally by just dropping and recreating the database, but you will have no such luck in production. Failed migrations can really throw a spanner in the works, therefore it is most important to make your team mates / QA / product aware that your work includes migrations and the team as a whole can battle test it (perhaps with a dry-run against a production replica database) and be on hand should anything go wrong.

5.2 Additional Notes (Optional)

Sometimes, there are other random tidbits you wish to include, perhaps direct messages to team members regarding anything written above, or notes to yourself reminding you to deal with something you stumbled upon when doing this work. This is where you can dump all those extra thoughts / notes / ideas / suggestions so that you can have it off your mind and have it available to remind your later.

Example

As I am unable to share actual issues from work (trade secrets and all that), I have put together a dummy example based on the information above. The description could be a bit more detailed, however, there was image size considerations to take.

Pull Request (PR)

Given we provided all the information needed for the work done in the associated Issue, as well as ensuring all discussion is kept to the issue (comments), we keep the PR relatively simple.

A basic summary of the work done (one or two sentences) was required, purely in order to assist searching for the PR in the future (an empty PR description gets lost forever).
After the short summary, a link to the Issue is added. If you use Github projects, you can conveniently create links between PRs and Issues, more in their documentation here.
The owner(s) be assigned to the PR.
Link other relevant PRs to connect GitHub timelines

Next Up

As mentioned up at the top, by nature, developers are lazy. There could be push-back when attempting to introduce these conventions which is understandable but in time, the team will come to understand and appreciate the detail and extra depth provided around any piece of work, especially when it comes to bug hunting, refactoring or feature improvement. Being able to sit and clearly write down what you are doing, why you are doing and how you are doing also allows us to step back from the code and look at it from a wider perspective, which in turn could open our eyes to other possible solutions, questions, or problems which could arise from the planned work.

The next post (and final in this series) will focus on turning our completed work with detailed issue and associated PR, into a mergable unit which undergoes QA, merging and finally release!

Git Conventions

Braden King — Fri, 26 Sep 2025 14:41:25 +0000

Over the last decade or so, I have had the opportunity to experiment with various git usage strategies and styles. Ranging from branch names, to pull request descriptions, a lot of time has been spent thinking about how to best describe our work to convey as much information clearly and concisely to others. There are a wealth of strategies or style guides on how to best utilise the git ecosystem but there is no silver bullet that solves all potential scenarios. What follows is an outline of some of the rules and guides I have incorporated into my daily git life which has best worked for my team and me.

Branches

99% of the time, code changes fall into one of a handful of categories/types. When creating a new branch, naming it something clear and meaningful can help other developers know at a glance what sort of changes are been introduced. It can also simplify finding a branch using tab completion locally when jumping between branches.

Branch Types

The following branch types should suit most use cases. These can be refined or altered depending on your use case (for instance, one might not utilise the style type if they work on CLI scripts for a living)

feature - a new feature
fix - bug fixes, hotfixes, typos, etc
style - UI / UX style changes
test - adding or refactoring tests; no production code changes
housekeeping - everything from code refactoring to updating documentation
devops - updates to configuration files, software versions, etc

Branch Format

The proposed branch format will make it easy to see at a glance what type of work has been done in the branch with a clean and easy-to-read branch name. The max length of a branch name is 255 characters but where possible, I try to keep the length to no more than 50 characters for readability purposes.

type-name_of_branch

The type is separated from the branch name with a - while the rest of the name is done in snake case (words separated by _)

Alternatively, if using a task/issue tracking application, like JIRA or GitHub projects, it adds additional visibilty to include the issue/ticket number in with the branch, and using a / instead of - can aid in making the branch name a little easier to read, for example:

type/ticket#-name_of_branch

Examples branch names:

feature-add_user_authentication
fix-about_page_infinite_redirect

// or

feature/21-add_user_authentication
fix/42-about_page_infinite_redirect

Commits

Developing a structured format for our commit messages will clarify each commit's purpose resulting in a cleaner git history. At a glance, one will know if a commit is intended to add a feature, fix a bug or just improve code quality. We should aim to keep the work done within a branch small and testable, often resulting in there only being a single commit per branch, however, it's better to have lots of small atomic commits within a branch than having all the commits squashed into one before merging. This makes bisecting introduced bugs a lot easier.

Commit Message Template:

This is a sample commit template I have been using for a while now. As I try to keep my commits granular and bespoke, I define the first line leaving everything else commented out. However, if you are pushing up a commit that involves a lot of changes, perhaps references a specific issue or task item, or includes changes that could affect future development, it is recommended to flesh out the commit message with as much information as possible to help future you (or team members) get a clear picture of the work done by looking at your commit alone.

The commit subject, as seen below, has the convention of starting with the type of work being committed (bug, feature, housekeeping, etc) all in lowercase, followed by a semicolon, space and commit message, starting capitalised, in the imperative form, without any full stop at the end.

type: [Ticket#](Optional) Summary of change

# **--- Proposed Changes ---**
#
#
# Issue / Task: [name](url)

# --- COMMIT END --- (informational only, do not uncomment)
# <type>: <subject> (Approx 50 characters)
# |<----  Using a Maximum Of 50 Characters  ---->|
# Explain why this change is being made
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|
# --------------------
# Type can be
#    feature      (new feature)
#    fix          (bug fix)
#    style        (UI / UX style changes)
#    test         (adding or refactoring tests; no production code change)
#    housekeeping (refactoring code or adding documentation)
#    devops       (background / architecture changes)
# --------------------
# Remember to
#   - Use the imperative mood in the subject line
#   - Do not end the subject line with a period
#   - Separate subject from body with a blank line
#   - Use the body to explain what and why vs. how
# --------------------

All the lines starting with a # are commented out and will not be displayed when viewing the commit message so if you intend to add future detail to your commit message, be sure to uncomment the lines necessary.

You can set up your default git commit message template with

git config --global commit.template ~/.gitmessage

Example commit messages:

feature: Add user authentication
fix: About page infinite redirect

// or

feature: [21] Adds user authentication
fix: [42] About page infinite redirect

Very often when jumping into a piece of work, I might not know right off the bat what the commit message will be as it tends to evolve as the work gets completed. In this case, I usually start my commit with something like

wip: Not sure what the issue is

and later on, once having completed the work and getting the branch ready for review, rename the commit messages appropriately during an interactive rebase (git rebase -i).

Closing Comments

This is by no means the definitive git convention standard to employ and it is something that is continually evolving and morphing as I find myself working on new and different projects. Everyone's experience is different and must be dealt with accordingly but, perhaps there are a few nuggets here that could help you guide a more structured and concise git workflow.

To further the conventions, I have also put together standard workflows, processes, and templates when it comes to GitHub Pull Requests (PR) and Issues affecting code reviews, QA testing, and deployment, but that is a story for another post.

Additional Resources

1.) A lot of the inspiration for these conventions has been taken from "Conventional Commits".

https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits
https://marcodenisi.dev/en/blog/why-you-should-use-conventional-commits/

2.) A classic article on how best to write commit messages. I have gleaned a lot of the commit message advice in this article to supplement my variation.

https://cbea.ms/git-commit/#imperative

3.) A commit linting tool you can incorporate into your workflow to enforce a standard of commit messages. Can be configured in a pre-commit GIT hook.

https://commitlint.js.org/#/

Feature Flags | Controlled Chaos in Production

Braden King — Tue, 09 Sep 2025 14:04:25 +0000

Feature flags are a way of life when developing software. They let you deploy code to production without immediately exposing it to users — like flipping a switch without blowing the fuse.

In practice, they're used to:

Ship features incrementally
Test changes in production with internal users
Run A/B tests or multivariate experiments
Deliver bespoke functionality to specific customers (not my favourite approach, but hey, sometimes we have to pick our battles)

Feature flags introduce flexibility — but also the responsibility to manage them well. Left unchecked, they can become a tangle of forgotten toggles, quietly rotting your codebase from within.

Let’s take a look at one of the more robust feature flag services out there.

LaunchDarkly

One of the more popular services (at least in my limited experience) is LaunchDarkly. It allows you to create and manage feature flags, define targeting rules (e.g., which users get what), and view flag usage analytics — including which flags are no longer being used.

That last bit is more useful than it sounds. Stale flags can linger for months or even years, adding dead weight to your app and making the logic harder to follow. Being able to identify and prune them is a big plus.

Here’s a basic integration pattern for using LaunchDarkly in a Rails app:

module FeatureFlag
  class << self
    def for(entity)
      @entity = entity
      self
    end

    def feature_a? = check_for("feature-a", default: true) # this default will make sense shortly
    def feature_b? = check_for("feature-b")
    def feature_c? = true # hard-coded flag (sometimes needed)

    private

    attr_reader :entity

    def check_for(flag_name, default: false)
      return false unless entity.present?

      ld_client.variation(flag_name, entity_context(entity), default)
    end

    def ld_client
      @ld_client ||= Rails.configuration.ld_client
    end

    def entity_context(entity)
      LaunchDarkly::LDContext.create(
        {
          key: entity.identifier, # a unique identifier for the entity
          kind: entity.type       # usually "user", but could be "account", etc.
        }
      )
    end
  end
end

This pattern gives you a central place to check feature availability in your app. You might wire this into your controllers, services, or views like so:

if FeatureFlag.for(current_user).feature_a?
  render :new_feature_version
else
  render :legacy_version
end

It’s readable, testable, and keeps your flag logic out of the weeds.

Handling Flags in Test and Development Environments

Since LaunchDarkly is an external service that communicates via HTTP, you definitely don’t want your test suite making live requests every time it runs. That’s just asking for flakiness and slow feedback loops.

Instead, we can use a mock client in the test environment to simulate feature flag behavior without hitting the actual API. Here’s a simple example I popped into our lib folder:

module LaunchDarkly
  class MockLdClient
    def initialize(*) = true

    def initialized? = true

    def variation(_key, _user, default) = default
  end
end

This mock client always returns the default value passed into the variation method — making it trivial to control feature behavior explicitly in your tests.

But wait — why not just put LaunchDarkly into "offline" mode in the test environment, like we do below for development?

Good question. While offline: true does prevent real network calls, it still requires the full LaunchDarkly SDK to be initialized — which adds unnecessary overhead and dependencies to your test suite. By using a lightweight mock client instead, you get a few key benefits:

Faster tests — no SDK initialization, no config loading, just a plain Ruby object
Zero external dependencies — the mock removes the need to load the LaunchDarkly gem at all in tests
Simpler control — it's easier to stub or extend the mock for edge cases if needed
Isolation — your tests won't break due to SDK upgrades or changes in default behaviors

In short, the mock client keeps your test environment lean and focused. It’s a small abstraction that pays for itself in speed and stability.

With that in place, in your LaunchDarkly initializer (config/initializers/launch_darkly.rb), you can wire it in like so:

require "#{Rails.root}/lib/launch_darkly/mock_ld_client.rb"

case Rails.env
when "test"
  Rails.configuration.ld_client = LaunchDarkly::MockLdClient.new("FAKE API KEY")
when "development"
  config = LaunchDarkly::Config.new(offline: true)
  Rails.configuration.ld_client = LaunchDarkly::LDClient.new(ENV['LD_KEY'], config)
else
  Rails.configuration.ld_client = LaunchDarkly::LDClient.new(ENV['LD_KEY'])
end

In the test environment, we avoid any HTTP calls by using the mock client.

In development, we set LaunchDarkly into offline mode. This disables all outbound network traffic and ensures your app doesn't hang or fail due to a misconfigured API key. You can still control the outcome of flags by setting the default values in your FeatureFlag methods — which is usually more than enough for local dev.

This setup gives you full control and isolation in non-prod environments, with zero reliance on external calls. Win-win.

Some Other Options

While this post focuses on LaunchDarkly, there are plenty of other options — some open-source, some more opinionated, and some simpler to get going with.

Here are a few worth considering:

Flipper – Powerful, flexible, and actively maintained. Can use a variety of backends (Redis, ActiveRecord, etc.) and integrates with a slick UI via Flipper Cloud.
Rollout – A battle-tested gem that’s been around for a while. Simpler API, great for percentage rollouts and user targeting.
Flipflop – Great for toggling features via a web UI. Good for admin-driven flags or feature previews.

Which one to use depends on your needs — whether you want self-hosted vs. SaaS, need advanced targeting and analytics, or just want a simple way to toggle features in development.

Parting Thoughts

Feature flags give you control, flexibility, and faster feedback loops — but like anything powerful, they need to be managed responsibly. Treat them like temporary scaffolding, not permanent fixtures. Set reminders to clean them up. Document what each flag does and who owns it. And when possible, limit the number of active flags in your system at a given time.

If you’ve had war stories with forgotten flags or misconfigured rollouts, I’d love to hear them. Otherwise, happy toggling.

Better Sidekiq Classes

Braden King — Thu, 28 Aug 2025 22:12:04 +0000

Sidekiq is pretty much the go-to solution for enqueuing jobs for background processing when working on a Ruby-based project. It's simple to implement, has a clear DSL, and is well-supported by common testing frameworks like RSpec. That being said, and I may be nitpicking, but the standard implementation examples do add a little extra overhead if you wish to be more flexible with your job business logic, and additional test setup is required.

The "normal" way

Given we want a little background job that updates a user's name and any other business logic needed (to keep the example simple), we could create a standard Sidekiq job with that logic and call it from our code as such:

class UpdateUserJob
  include Sidekiq::Job

  def perform(user_id, name)
    user = User.find(user_id)
    user.update!(name: name)
    # .. additional business logic here
  end
end

UpdateUserJob.perform_async(1, "bob") # perform the job as soon as possible
UpdateUserJob.perform_in(5.minutes, 1, "bob") # delay the processing by 5 minutes

This is simple enough. But what if we want to test the logic being performed inside this job? Firstly, we'd need to update our spec_helper to let it know what to do with a job. If you're using RSpec, you might even need to add the rspec-sidekiq gem for additional configuration and matcher options. A classic-looking spec for this job might look something like this:

it "updates the user" do
  UpdateUserJob.perform_async(1, "bob")
  expect(UpdateUserJob.jobs.size).to eq(1)
  UpdateUserJob.drain
  expect(User.find(1).name).to eq("bob")
end

We need to drain the job before we can test the result of its work. Alternatively, we could wrap the test inside one of the Sidekiq testing helper methods:

it "updates the user" do
  Sidekiq::Testing.inline! do
    UpdateUserJob.perform_async(1, "bob")
    expect(User.find(1).name).to eq("bob")
  end
end

This does work as expected however it does leave a little to be desired. We have to remember to do this whenever testing job logic (the number of times I've had to search through previous specs to remind myself of the syntax), it adds a few extra lines to the tests which are not necessary and there is a spec performance hit as well.

The "use case" way

So, what options do we have? Well, the first option would be to extract the logic performed by the job into a class which we would then pass the job attributes to for processing. That way we can independently test the business logic without having to mess with background workers and the like. I have used various names for these classes, Use Case, Resource, or Library to name a few (use whatever best suits you and your conventions). Our new job would look something like this:

class UpdateUserJob
  include Sidekiq::Job

  def perform(user_id, name)
    UpdateUserUseCase.new(user_id, name).call
  end
end

class UpdateUserUseCase
  def initialize(user_id, name)
    @user_id = user_id
    @name = name
  end

  def call
    user = User.find(@user_id)
    user.update!(name: @name)
    # .. additional business logic here
  end
end

Now, when it comes to testing, we could just forgo testing the actual job class as it does nothing except pass on some arguments to a plain old Ruby object. We can just test the class directly. Sidekiq is also already extensively tested so there is little point in testing whether the jobs on the queue have increased or not unless you are expecting new jobs to be created as a knock-on effect of your business logic.

it "updates the user" do
  UpdateUserUseCase.new(1, "bob").call
  expect(User.find(1).name).to eq("bob")
end

The added benefit to doing it this way is that you have a plain old Ruby object that you can call independently and inline in your code elsewhere should the need arise. For instance, you may want to defer the processing to the background when handling a mass import of data, however, when being performed as a single HTTP request to your API, you could wish to do it inline.

The downside to this is that we now, however, have had to create an additional class to provide this flexibility. That means, if we wish to keep this convention going, for each Job class, there would be a corresponding UseCase class. What if we could take this idea one step further? What if we could turn our Job class into a plain old Ruby object right from the start? Let's rewrite our UpdateUserJob class.

The "runner" way (with POROs)

Let's pretend you had never heard of Sidekiq or background queues, and you want to write some code to perform a specific task. For the sake of convention, I have ended the following class name with "Job" to match previous examples however by syntax definition, it is no longer what we would call a classic "job". It is now just a Plain Old Ruby Object (PORO; identical to our previous UpdateUserUseCase).

class UpdateUserJob
  def initialize(user_id, name)
    @user_id = user_id
    @name = name
  end

  def call
    user = User.find(@user_id)
    user.update!(name: @name)
    # .. additional business logic here
  end
end

With that in place, we need to set up some sort of mechanism to have this code be run by Sidekiq in our background queue. We can introduce a simple class to wrap the sidekiq calls, allowing us to inject our custom job class with its arguments. To not conflict with the Sidekiq namespace, I have created the Runners module which will run this code for me (side note: no matter what project I've worked on in the past, I always seem to use these "runner" style classes for various things).

module Runners
  class Sidekiq
    include ::Sidekiq::Job

    sidekiq_options(retry: 3, backtrace: true, queue: "default")

    def perform(job_class_name, *args)
      Kernel.const_get(job_class_name).new(*args).call
    end

    def run(job_class, *args)
      self.class.perform_async(job_class.to_s, *args)
    end

    def run_in(delay_in_seconds, job_class, *args)
      self.class.perform_in(delay_in_seconds, job_class.to_s, *args)
    end
  end
end

And with that, we have everything we need to be able to throw plain old Ruby classes into the background for processing. If we wish to run our business logic inline, we simply run

UpdateUserJob.new(1, "bob").call

but if we want to delegate the processing to the background queue, we can send it off immediately or delay it

Runners::Sidekiq.new.run(UpdateUserJob, 1, "bob") # perform the job as soon as possible
Runners::Sidekiq.new.run_in(5.minutes, UpdateUserJob, 1, "bob") # delay the processing by 5 minutes

Bells & Whistles

Now that we have our lovely Sidekiq runner class, we can embellish it with a couple final bells and whistles. We might want to add / override the sidekiq_options on demand instead of being stuck with the previous hard-coded options. Perhaps we prefer using keyword arguments in our method definitions for the added clarity and ability to insert the arguments in any order. And maybe, we would like the job names in the Sidekiq UI to be a little more descriptive as to the actual job they are running so that we don't have to go digging through the arguments list to find specific jobs.

module Runners
  class Sidekiq
    include ::Sidekiq::Job

    DEFAULT_OPTIONS = { retry: 3, backtrace: true, queue: "default" }

    def perform(job_class_name, *args)
      if args in [Hash]
        # This handles the case of keyword arguments
        job_class_name.constantize.new(**args.first.symbolize_keys!).call
      else
        # This handles the case of basic arguments
        job_class_name.constantize.new(*args).call
      end
    end

    def initialize(options = {})
      self.class.sidekiq_options(DEFAULT_OPTIONS.merge(options))
    end

    def run(job_class, *args)
      update_display_class(job_class)
      self.class.perform_async(job_class.to_s, *args)
    end

    def run_in(delay_in_seconds, job_class, *args)
      update_display_class(job_class)
      self.class.perform_in(delay_in_seconds, job_class.to_s, *args)
    end

    private

    def update_display_class(job_class)
      self.class.sidekiq_options.merge!("display_class" => "#{job_class} [#{self.class.name}]")
    end
  end
end

In essence, you can now define your background job classes as basic Ruby objects, execute them inline, or transfer them to Sidekiq for background processing. The main requirement is maintaining a consistent DSL with your job classes, such as implementing a mandatory call (or equivalent: perform or execute) method. (Kudos to my friend Kris for the original idea.)

JuggleBee’s Great Leap – Data Migration, ActiveStorage, and Production Readiness (Part 2)

Braden King — Mon, 18 Aug 2025 06:41:24 +0000

In case you missed Part 1, we covered:

Why I started fresh on Rails 8 instead of doing incremental upgrades.

Migrating core models/controllers/services to modern Rails conventions.

Swapping Sprockets for importmaps and modernizing the JavaScript setup.

Replacing Sidekiq + Redis + whenever with ActiveJob + SolidQueue.

Moving deployments to Kamal 2 with Traefik and Let’s Encrypt.

Catch up on it here: JuggleBee’s Great Leap – Rebuilding a Rails 4 App in Rails 8 (Part 1)

Now—back to the post.

Now that we had a deployable app, I set up a staging server using my new favourite provider, Hetzner (not a sponsor, lol), spun it up, and witnessed a “fully functional” skeleton of JuggleBee. Stage 1 of the migration plan was complete.

Now came the real meat and potatoes of the project — actually hydrating the new app with all of its production data. We’re talking over 50,000 images, countless database records, and security credentials… the works. This is the part where a missed step could mean broken listings, missing files, or downtime. No pressure.

The Daunting Database Migration

Legacy JuggleBee had been coasting along happily on Postgres 9.6 — which, back in 2016, was the latest and greatest. Fast forward to today and it’s long past its sell-by date, with official support ending in November 2021. Upgrading wasn’t just about keeping up with the times; Postgres 17.5 brings some serious perks:

Native JSON field type support.
Incremental backups with pg_basebackup --incremental, slashing backup time and storage usage.
Noticeable performance gains from better memory management, indexing, and partitioning.
Improved observability via enhanced EXPLAIN options and richer stats views.
…and more.

It was a no-brainer to upgrade, but the version gap meant one wrong move could corrupt thousands of user, auction, and invoice records. That made reliable backups non-negotiable before touching a single byte. Luckily, I already had a manual backup process baked into my deploy routine. Here’s the script (feel free to steal any of the scripts in my posts):

#!/bin/bash

DB_CONTAINER=($(sudo docker ps | grep postgres | awk '{print $NF}'))
BACKUP_NAME=dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql
BACKUP_FOLDER=db_backups
KEEP=10

# Dump the database into a backup sql file
echo "Creating the database dump..."
docker exec -t $DB_CONTAINER pg_dumpall -c -U postgres > $BACKUP_NAME
echo "Database dump created."

echo "Moving database backup to backup folder..."
mkdir -p $BACKUP_FOLDER
mv $BACKUP_NAME $BACKUP_FOLDER
echo "Backup moved to backup folder."

echo "Deleting old releases..."
(cd $BACKUP_FOLDER && (ls -t | head -n $KEEP; ls) | sort | uniq -u | xargs rm -rf)
echo "Backup stored."

One catch: pg_dumpall (used above) tries to dump everything — including Postgres cluster-wide settings — which can be version-specific and cause headaches on import. For a major version jump, you want pg_dump, which targets a single database and avoids the version mismatch landmines.

For the migration, I only needed to change the docker command we executed - with the added ENV vars, that is:

DB_USER=db_user
DB_PASSWORD=db_password
DATABASE_NAME=database_name

# ...

docker exec -e PGPASSWORD=$DB_PASSWORD -t $DB_CONTAINER \
    pg_dump -U $DB_USER $DATABASE_NAME > $BACKUP_NAME

With the new backup in hand, importing into Postgres 17.5 went off without a hitch — no edits, no drama. Honestly, I was braced for a fight given the version gap, but the data was simple enough (and avoided fancy Postgres features) that it just… worked. A rare and pleasant surprise in a project full of moving parts.

Listing Image Migration

Unlike the data migration before it, migrating all the listing images (just shy of 50,000!) came with its own set of headaches. The legacy setup used CarrierWave with a custom uploader and fixed S3 paths, which worked fine at the time but wasn’t exactly future-proof. Since I was already upgrading to Rails 8, it made sense to tackle this technical debt head-on and move to ActiveStorage — effectively retiring these gems:

carrierwave
fog-aws
mini_magick

… and replacing them with image_processing for post-processing.

In the old days, uploads required creating an “Uploader” class and mounting it on a model. For example:

# app/models/image.rb
class Image < ActiveRecord::Base
  mount_uploader :aws, ImageUploader
end

# app/uploaders/image_uploader.rb
class ImageUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick
  storage :fog

  process resize_to_fill: [850, 850]

  version :thumb do
    process resize_to_fill: [280, 280]
  end

  def store_dir
    "listings/#{model.listing_id}/#{model.id}"
  end
end

With ActiveStorage, uploaders and hard-coded S3 paths are gone. You simply declare the attachment in your model (after setting up config/storage.yml):

class Image < ApplicationRecord
  has_one_attached :file do |attachable|
    attachable.variant :thumb, resize_to_limit: THUMB_DIMENSIONS, preprocessed: true
  end
end

That takes care of future uploads — but what about migrating the 50,000+ legacy images stored in the old bucket? The image.aws field plus CarrierWave’s store_dir gave me the exact file path to each image. I then wrote a script to:

Download each image from the legacy bucket.
Re-upload it through ActiveStorage so it generates its own hashed storage path.
Skip already-migrated images to allow safe re-runs.

Here’s the script in all its glory (run synchronously to avoid AWS rate limits — which meant a cool 4 hours of migration time):

#!/usr/bin/env ruby

require_relative '../config/environment'
require 'aws-sdk-s3'
require 'stringio'

OLD_S3_BUCKET = Rails.application.credentials.dig(:old_aws, :bucket)
OLD_S3_REGION = Rails.application.credentials.dig(:old_aws, :region)
OLD_S3_ACCESS_KEY_ID = Rails.application.credentials.dig(:old_aws, :s3_key)
OLD_S3_SECRET_ACCESS_KEY = Rails.application.credentials.dig(:old_aws, :s3_secret)

# Optional: skip already migrated images
SKIP_EXISTING = true

s3 = Aws::S3::Client.new(
  region: OLD_S3_REGION,
  access_key_id: OLD_S3_ACCESS_KEY_ID,
  secret_access_key: OLD_S3_SECRET_ACCESS_KEY
)

puts "Starting image migration..."

Image.find_each do |image|
  begin
    if SKIP_EXISTING && image.file.attached?
      puts "Skipping Image #{image.id} (already attached)"
      next
    end

    # Construct old S3 key from uploader logic - your path here
    key = "listings/#{image.listing_id}/#{image.id}/#{File.basename(image[:aws].to_s)}"

    obj = s3.get_object(bucket: OLD_S3_BUCKET, key: key)

    image.file.attach(
      io: StringIO.new(obj.body.read),
      filename: File.basename(key),
      content_type: obj.content_type || 'image/jpeg'
    )

    puts "Migrated Image #{image.id} (Listing #{image.listing_id})"
  rescue Aws::S3::Errors::NoSuchKey => e
    warn "Image #{image.id} missing in old bucket: #{key}"
  rescue => e
    warn "Failed to migrate Image #{image.id}: #{e.class} - #{e.message}"
  end
end

puts "Migration script finished"

Four hours later, we were in business — all images were now managed by ActiveStorage.
Future uploads are handled automatically, thumbnails are generated on demand, and the whole setup is cleaner and easier to maintain.

Credentials & Security

You might have noticed the use of Rails.application.credentials in the previous script. That’s new territory — Rails encrypted credentials didn’t exist back in 4.2.

Back then we had secrets.yml, which stored everything in plain text and was meant to be excluded from Git. In theory, you’d inject it during deploy with whatever tooling you used. In practice… I was lazy. My deploys were manual, the repo was private, and I just checked them straight in. Big no-no. Thankfully, Bitbucket never got hacked — but let’s just say this setup wouldn’t pass any kind of security audit.

Rails 5.2 introduced encrypted credentials — finally, a way to store secrets in plain text locally while Rails encrypts them with a master key. That master key stays out of Git and gets injected during deploy. Much better.

Fast forward to today, and Kamal (my de facto deployment tool) takes it a step further with built-in support for pulling secrets straight from password managers like Bitwarden, 1Password, or LastPass. That means my Rails master key, database credentials, and other environment variables can live safely in Bitwarden, and Kamal just grabs them during deploy. No manual copying, no “where did I put that key?” moments, and no plain-text secrets hanging around in the repo.

Here’s an example using Bitwarden via the CLI. This snippet fetches all secrets and assigns them to variables in .kamal/secrets:

SECRETS=$(kamal secrets fetch --adapter bitwarden-sm all)

KAMAL_REGISTRY_PASSWORD=$(kamal secrets extract KAMAL_REGISTRY_PASSWORD $SECRETS)
RAILS_MASTER_KEY=$(kamal secrets extract RAILS_MASTER_KEY $SECRETS)
POSTGRES_USER=$(kamal secrets extract POSTGRES_USER $SECRETS)
POSTGRES_PASSWORD=$(kamal secrets extract POSTGRES_PASSWORD $SECRETS)

The only catch: you’ll need to have the Bitwarden CLI installed and authenticated on every machine you deploy from. It’s a one-time setup, but totally worth it for the peace of mind of never having to worry about leaked secrets again.

Lessons Learned

Looking back, a few big takeaways stood out:

Scripts are your best friend. Whether it’s a database dump, image migration, or credentials setup, having a repeatable script means you can run it, tweak it, and run it again without reinventing the wheel. It also removes a ton of mental overhead when you’re juggling multiple moving parts.
Test migrations in staging — thoroughly. Moving to PostgreSQL 17.5 could have been a disaster if I’d gone straight into production. Running the full migration end-to-end in a safe environment gave me confidence and caught subtle issues before they ever touched live data.
Expect the cleanup phase. Even after the “big ticket” migrations were done, staging revealed a laundry list of smaller fixes — broken image links, JavaScript load order issues, outdated gem calls, and other gremlins. None of these were major individually, but together they took nearly two weeks to iron out. Build that buffer into your timeline.
Take the opportunity to ditch technical debt. CarrierWave, fog-aws, Sidekiq, Redis… all of these had served me well for years, but replacing them with ActiveStorage and SolidQueue means fewer dependencies to maintain, fewer services to monitor, and a cleaner architecture.
Security deserves equal billing with features. Rails encrypted credentials plus Bitwarden CLI integration finally dragged my secrets management into the modern age. No more plain-text secrets in Git. Enough said.
Modern Rails is worth the leap. From importmaps to Kamal, the tooling around Rails 8 makes deployment, scaling, and maintenance dramatically simpler than what I was doing in 2015.

Closing thoughts

And with that, JuggleBee officially joined the modern Rails era.

This wasn’t just a version bump — it was a full-stack rejuvenation.
The app runs faster, the infrastructure is leaner, and I finally have a deployment pipeline I can trust at 2 a.m. without crossing my fingers.

Was it worth skipping incremental upgrades? Absolutely. Starting fresh on Rails 8 gave me a clean slate to rebuild only what mattered, using tools that will keep JuggleBee humming for years to come.

If you’ve been sitting on a legacy Rails app, staring down the upgrade path and wondering if it’s worth the effort — it is. Just plan your migrations, test them in staging, and embrace the opportunity to shed some old weight while you’re at it.

JuggleBee’s now live on Rails 8 / Ruby 3.4.3 / PostgreSQL 17.5, with ActiveStorage handling thousands of images, Bitwarden keeping our secrets safe, and Kamal making deployments a one-command affair.

Now it’s time to step away from the terminal, grab a cold beer, and actually enjoy the thing I’ve been rebuilding over the last month — until the next big upgrade comes along.

JuggleBee’s Great Leap - Rebuilding a Rails 4 App in Rails 8 (Part 1)

Braden King — Wed, 13 Aug 2025 14:49:18 +0000

JuggleBee was born in 2015. It was Namibia's first online auction platform and is still one of the biggest today. I built it with Ruby on Rails 4.2 on Ruby 2.2. It sat there, rock-solid and stubbornly stable, only needing the occasional dust-off and minor tweak over the years. At various points in time, I thought about upgrading the various versions; however, I was stuck between a rock and a hard place — in order to upgrade Ruby, I had to upgrade Rails, and vice versa. The idea of incremental upgrades felt like a nightmare — two battlefronts to fight on, Ruby on one side and Rails on the other.

Fast forward to 2025. With the arrival of my daughter, I acquired a smattering of free time interspersed with sleepless nights. The perfect time to finally bite the bullet, bring JuggleBee into the 21st century (you know what I mean), and get these upgrades done. After much pondering and planning, only one realistic option remained... incremental upgrades would take months with constant patching between every version bump; I would have to take the leap from Rails 4.2 straight to Rails 8, with Ruby hopping from 2.2 to 3.4.3. It was quite the journey, and what follows is a breakdown of the challenges and learnings I made along the way.

Starting Fresh

Not to blow my own horn or anything, but I was in a pretty good place with this migration plan. The codebase of JuggleBee was intentionally built with self-contained business logic components, defining a clear separation of concerns. The models and controllers were not overly bloated, with liberal usage of "service objects" performing the more complicated logic, and an added separation of logic between my controllers and views using the "view decorator" pattern. This architecture made the copy-pasta approach almost… dare I say… fun. But let’s not kid ourselves — a jump from Rails 4.2 to 8 is no walk in the park.

As part of the rails new process (after installing the latest Ruby and necessary Rails gems), and before the true code migration could begin, I just needed an empty, runnable project with the necessary gems installed. I appended my old Gemfile with the auto-generated one, removing all locked versions to ensure the latest compatible versions were installed. I also identified irrelevant and dead gems, removing those and replacing them with alternatives where necessary (more detail on this later).

Reading into each of the default gems specified by the rails new generator gave me a good understanding of what the current Rails stack looks like. I didn’t need all of it, so some were commented out, but I did take some of the new suggestions into account. Puma, for example, replaced Unicorn, which I was previously using. I could also get rid of God, in the non-divine sense, as I no longer needed to monitor my server state manually. All in all, this whole process didn’t take more than an hour or so.

Models, Controllers, Services & Views (in that order)

These being purely Ruby code made it the easiest place to start. Even though we jumped up from Ruby 2.2 to 3.4.3, not all that much in the core language changed. Twas Rails that was the most behind. For example, JuggleBee was developed before the abstract ApplicationRecord class made its way into the Rails architecture!

Models

The models were the easiest to migrate over, as they already had a smattering of unit tests behind them. First, though, we had to get the database up and running. Spoiler alert: I was also updating our Postgres version from 9.6 to 17.5 as part of this big update. The old migration files were fossils — brittle, outdated, and utterly unfit for a modern Rails 8 app. The simplest solution was to drop a pg_dump of the current database (just on my local copy of the now legacy JuggleBee) and import it, generating the schema.rb. I could now copy across my models and test them out in the rails console.

Some of the updates required to get things up and running were:

belongs_to is now a required atribute. I have a home-grown version of polymorphism which allows a Listing to be either a Product or Auction and the belongs_to on these associations are optional, so I had to update these associations accordingly (**side note: a refactor waiting to happen). So,

belongs_to :auction
belongs_to :product

becomes

belongs_to :auction, optional: true
belongs_to :product, optional: true

I had a couple of instances of update_attributes (very selective. Given they bypass validations, they were used with extreme caution) which is now deprecated and had to be changed to update.
Deprecated validation methods such as validates_presence_of :name needed updating to validates :name, presence: true sort of changes.

As for the views, the gems I used (haml-rails, redcarpet, simple_form, cocoon, etc) are all still actively maintained and required no changes at all — a very pleasant surprise.

Controllers

Next up were the controllers. Thanks to my use of service objects for the bulk of complex logic, migrating controllers was mostly painless. Rails 8 is stricter, and that’s where most of my changes were required. While bringing over controllers, I also began migrating the service objects they called upon, which are POROs and required almost no changes.

The main updates included:

Params passed to background jobs now must be valid JSON. This was especially relevant for controllers triggering email or background tasks.
Controller filters were renamed to actions (before_filter → before_action).
Controller hooks like before_action should come after the method they reference, not at the top of the file (a style guideline enforced in modern Rails apps).
redirect_to :back was replaced with redirect_back fallback_location: root_path (or an appropriate fallback path).
The responders gem is no longer included in Rails, so respond_with calls were rewritten using respond_to blocks.

All in all, the MVC migration was more about cleaning things up and embracing modern Rails conventions rather than fighting major incompatibilities.

JavaScript Modernization

This is where things started to get spicy — the kind of spicy where you wonder if you just bit off more than you can chew. So much has changed in the front-end assets side of things. JuggleBee leverages jQuery (thankfully I dodged the CoffeeScript bullet) with Sprockets as the asset pipeline. Modern Rails favours importmaps as the default asset manager and pipeline, and keeping with the spirit of rejuvenating JuggleBee and bringing it up to speed, I signed up to it too. This allowed me to replace a bunch of gems which added various front-end features, such as chartkick, masonry and bootstrap with the importmaps pin alternative. Some libraries had to remain as CDN imports in my layout file, due to the order at which these JavaScripts got initialized and loaded by the DOM.

My suite of JavaScript classes also needed a bit of love and attention. The Sprockets

//= require

statements were replaced with

import

and my classes now had to export themselves so that they could be loaded as ES modules. All the files had to be relocated from app/assets/javascripts/ to app/javascript/. The way we add our JavaScript base file into our application view layout also had to change slightly, going from

<%= javascript_include_tag "application" %>

<%= javascript_importmap_tags %>

Even though jQuery is considered a bit long in the tooth, given the plethora of really solid UI frameworks like Vue and React, I opted to keep my reliance on it for the time being. It still works, is actively maintained, and trying to replace it now would be a whole new kettle of fish. An adventure for another day.

Background Jobs & Scheduling

This area was one of the biggest wins in the entire migration. JuggleBee had the “classic” background processing setup: Sidekiq + Redis + whenever (for cron). It worked fine for years, but it always felt a little… heavy, like lugging around a toolbox just to tighten a single screw. Sidekiq required its own container, Redis was a hungry beast that always felt like it was asking for more memory, and whenever meant fiddling with cron jobs and ensuring everything stayed in sync across deploys. It worked, but it was yet another moving part in an already aging stack.

Enter SolidQueue — a gem that ships with Rails 8, built to replace Sidekiq-like setups with something that is both simpler and more tightly integrated with ActiveJob. The real beauty? No Redis. SolidQueue uses the same database you already have (Postgres in our case) to manage job queues, which meant I could drop an entire service and reclaim a chunk of server memory.

Here’s what this meant for JuggleBee:

No more Sidekiq configuration, container management, or Redis headaches.
The whenever gem (used for cron scheduling) could be thrown out too, thanks to SolidQueue’s built-in recurring.yml.
Background jobs now feel like a natural part of Rails — no extra glue required.

To put it in perspective, my stack went from:

Rails App + Sidekiq + Redis + whenever + cron

to:

Rails App + SolidQueue

That’s it. Beautiful, minimal, and a lot less to maintain.

Another chef’s kiss moment was how little code I had to change. Most jobs migrated over with minimal tweaks — the biggest adjustment being that job arguments must be JSON-serializable. This meant replacing keyword arguments with hashes like:

EmailJob.perform("MyEmailClass", {"from" => current_user.name, "subject" => "Hello there"})

instead of:

EmailJob.perform("MyEmailClass", from: current_user.name, subject: "Hello there")

It was one of those rare upgrades where less really is more. Dropping Redis and cron alone made this whole migration feel worth it.

Infrastructure & Deployment

For years, deployment was powered by a custom shell script I wrote. It wasn’t flashy, but it was reliable and got the job done. It handled atomic releases, cleaned up old deployments, built Docker images, restarted containers, and even maintained a cache for faster updates. For a single-developer project like JuggleBee, it was the perfect balance of simplicity and control.

Here’s the core of that script:

#!/bin/bash

branch=${1:-master}
cwd=/home/ubuntu
repo_url=your_repo_here
revision=master
keep=5
timestamp=$(date +%s)
cache=$cwd/.git_cache
releases=$cwd/releases
mkdir -p $releases
previous=$releases/$(ls $releases/ -t | head -n 1)
release=$releases/$timestamp

if [ ! -d $cache ] ; then
        git clone $repo_url $cache
fi

echo "downloading latest source code from $branch..."
mkdir -p $release
(cd $cache && git gc --prune=now && git remote prune origin && git fetch origin && git reset --hard origin/$branch && git archive $revision | tar -x -c $release)

echo "release timestamp is: $timestamp ($release)"

echo 'building docker images...'
/bin/bash -c "(cd $release && docker compose -f docker-production.yml build)"

if [ $? -eq 0 ]
then
        if [[ $previous != "" ]] ; then
                echo 'stopping previous containers...'
                /bin/bash -c "(cd $previous && docker compose -f docker-production.yml stop && docker ps -a -q --filter='status=exited' | xargs docker rm)"
        fi

        echo 'restarting application...'
        /bin/bash -c "(cd $release && docker compose -f docker-production.yml up -d)"

        echo 'deleting old releases...'
        (cd $releases && (ls -t | head -n $keep; ls) | sort | uniq -u | xargs rm -rf)

        echo 'creating symlink.'
        rm $cwd/current-release
        ln -s $release $cwd/current-release

        echo 'deploy complete.'
fi

Honestly, this script could have kept soldiering on for years… until Kamal walked in like the cool new kid who makes your old tricks look ancient. It wasn’t broken — far from it — but Kamal is like having a personal DevOps engineer in your terminal. It takes all the things I cared about (Dockerized deploys, atomic releases, rollbacks) and adds extra superpowers I didn’t even realize I needed.

Introducing Kamal 2

Kamal is a server provisioning and deployment tool built specifically (but not limited to) Rails apps. It automates a ton of tasks that my script didn’t — and one of the most significant changes? No more Nginx.

Kamal ships with a built-in Traefik proxy that handles all your routing and SSL certificates out of the box. No more tinkering with nginx.conf files or restarting a separate webserver. One less dependency chewing through RAM and one less thing to break at 2 am.

Here’s what Kamal brings to the table:

kamal setup: installs Docker, Git, and all required dependencies on your server.
kamal deploy: builds your Rails app into a Docker image, pushes it to your registry, and runs it on the server.
Traefik proxy with SSL (via Let’s Encrypt): you get HTTPS without lifting a finger.
Accessory management: want Postgres or Redis? Kamal spins them up as Docker containers.
Scaling: need more capacity? add another container in deploy.yml and Kamal will route traffic automatically.

The impact of this was huge. I went from managing Docker builds, old release directories, and an Nginx webserver, to just running one command. There’s something almost unsettling about how smooth it is — I felt like I was missing steps at first, like forgetting my keys when leaving the house.

Wait, that’s it? Did I actually deploy? Did I forget something? Oh… it’s done already. Huh.

This wasn’t just a convenience win — it was a dependency detox. Between dropping Nginx here and killing Redis with SolidQueue earlier, my infrastructure got a lot lighter, faster, and cheaper to run. Kamal didn’t just evolve my old script — it rendered half of its logic unnecessary.

Half Way There

With the new Rails 8 foundation in place, JuggleBee has already shed a lot of its old skin. We’ve modernized the models and controllers, swapped out a creaky asset pipeline for importmaps, retired Sidekiq, Redis, and cron in favor of SolidQueue, and traded a homegrown deployment script (solid as it was) for the convenience and power of Kamal 2. The app is lighter, faster to deploy, and much easier to maintain — but we’re not done yet.

Getting the Rails 8 app running and deployable was only half the battle. Now comes the rest of the journey:

Migrating data from a legacy PostgreSQL 9.6 database to a fresh PostgreSQL 17.5 instance.
Replacing CarrierWave with ActiveStorage and migrating all user-uploaded files into a new S3 bucket.
Locking down credentials with Rails encrypted secrets and Bitwarden CLI.
Cleaning up leftover code smells, finalizing test coverage, and polishing the overall performance of the new stack.

That’s some of what Part 2 will cover — all the finishing touches, the unexpected hurdles, and the final steps that took JuggleBee from a Rails 4 relic to a lean, modern, and production-ready Rails 8 app.

Stay tuned for Part 2, where the migration story continues.