DEV Community: Michiharu Ono

The Case for Leaky Locks: Redis TTL as Failure Cooldown for Expensive AI Jobs

Michiharu Ono — Fri, 13 Mar 2026 16:25:39 +0000

I'm probably not the only one who's been told "always release your locks in a finally block." It's one of those conventions we follow without much thought, and for most situations it's completely right. But I recently ran into a case where doing the opposite was actually the better call.

The Problem I Didn't See Coming: How Releasing Locks Cost Me Money

My job queue was simple: user submits a document → AI evaluates it → result gets stored.

The issue was that AI calls can fail. Rarely, but they do. Out of nowhere, the model might ignore the expected output format or a rate limit kicks in. So I'd catch the exception, log it, mark the job as failed, and very responsibly release the lock in the finally block.

Then the user would hit retry.

And the AI would fail again.

And they'd hit retry again.

Each retry triggered another LLM call, and each one cost real money.

What I had was essentially a retry storm hitting my API at exactly the moment my system was already struggling.

Using Lock Expiration as a Cooldown Mechanism

Here's what I ended up doing:

lock_key = f"ai_job_lock:{job_id}"

# Try to acquire lock with TTL
acquired = redis.set(lock_key, "1", nx=True, ex=300)

# If the lock exists, the job is either running or cooling down
if not acquired:
    return

try:
    result = await call_llm_api(data)
    save_result(result)

    # Release lock only on success
    redis.delete(lock_key)

except Exception as e:
    log.error(f"Failed: {e}")

    # Do NOT release the lock
    # The TTL becomes the cooldown window

The lock just stays there. For five minutes. Then Redis evicts it automatically.

I know what you're thinking: "That's a memory leak!" When you see a lock that doesn't get released, the mental model most developers reach for is "something that accumulates indefinitely."

But here, it's a TTL with a 5-minute expiration. So, the worst case in this scenario is one orphaned key per job, and it self-destructs in 5 minutes. Not a leak.

Without TTL:  fail → retry → retry → retry → 20 calls in 60s
With TTL:     fail → blocked → blocked → retry at t=5min

Why This Works

Let us think about the common reasons AI calls fail. Rate limiting means you'll fail again immediately if you retry. Network issues are often temporary but not instant to resolve. Prompt problems won't fix themselves no matter how many times you retry.

When your system is already struggling, piling on more load is the last thing you want, especially when each LLM call is very expensive. The TTL acts as a forced cooldown. Five minutes sounds like a lot, but in practice it can be right for some use cases: long enough to recover from rate limits, short enough that for most async workflows users barely notice.

The Part I Actually Like

It felt wrong at first but there's no retry logic. No exponential backoff. No complex state machine. Just time.

# This is literally all the code
acquired = redis.set(lock_key, "1", nx=True, ex=300)

# On failure, just let it ride
# Lock expires naturally

And the system still recovers cleanly. If a worker crashes mid-job, the lock expires and the recovery service picks it up. The TTL handles both failure cooldown and crash recovery with zero extra code. (When a retry request arrives during the cooldown window, the worker simply fails to acquire the lock and exits early without calling the LLM.)

When This Doesn't Apply

Of course, this pattern isn't universal.

It's a bad fit for:

Cheap operations where retries are basically free.
Jobs that legitimately need immediate retry.
Situations where users expect a synchronous, instant response.

But for expensive and slow AI calls where failure usually means "try again later, not right now", this approach can quietly save you from expensive retry storms you didn't know you were building.

Risks worth mentioning

Lock duration mismatch
If a job runs longer than the TTL, the lock expires while the job is still running and another worker picks it up. Make sure TTL > worst-case runtime, or implement a heartbeat that refreshes the lock while the job is active.

Deterministic failures
The cooldown works well for transient failures like rate limits or network hiccups. It doesn't really help when the failure is caused by bad input or a broken prompt because they will just fail every 5 minutes until someone notices. I believe that it is worth classifying your failures and marking deterministic ones as permanently failed rather than letting them loop.

User-facing feedback
If a user hits retry and nothing happens, it feels broken. Surface the state somewhere: a "retry available in X minutes" message, a job status indicator, anything that tells them the system is aware and waiting rather than silently stuck.

Wrapping Up

We spend a lot of time building complex retry mechanisms, circuit breakers, and fallback systems. Sometimes the right answer is just: let it fail, wait a bit, try again later.

The Redis TTL is the "wait a bit" part, except it's automatic, requires no extra code, and can't be accidentally bypassed.

Curious if anyone else has hit this or found a better way to handle it.

How (and How NOT) to Name Rails Models Beyond the Obvious

Michiharu Ono — Sun, 09 Feb 2025 23:20:15 +0000

Have you ever encountered a model in a Rails app that initially seemed to have an understandable name, but as you became more familiar with the code, you realized the name led you to believe one thing when it actually meant something entirely different? 🙋‍♂️

This kind of naming can introduce unnecessary complexity, forcing you to "decipher" what the code actually does.

And that's never fun ☕️

Naming things in Rails is key to keeping your code easy to understand and maintain in the long run. While conventions like using snake_case for variables and methods is a no-brainer, I believe that picking the right names for models and methods requires a bit more thought.

In this blog, I’ll attempt to unpack meaningful names for your Rails models and methods, helping you avoid confusion and keeping things clear.

(Please understand that this blog isn’t a set of hard-and-fast rules 🙆‍♂️ It’s based on what I’ve found works well for me and my team in the past, especially when developers come and go and need to collaborate with multiple people. The goal is to make things clearer for everyone in the long run.)

How To Name Model

When naming Rails models, it’s crucial that the name communicates the model’s role, responsibility, and the real-world entity it represents.

In this section, I’ll cover key considerations to help ensure your model names are clear and avoid common pitfalls like vague or action-oriented names.

1. Does the Model Capture the Entity?

A well-named model should represent a real-world entity that the application works with. Typically, the name is a noun that reflects the object or concept it encapsulates, rather than an action or process. For example:

User represents a user entity.
Product represents a product entity.
Order represents an order entity.

On the other hand, naming a model after a process or a task (e.g., ProductProcessor) can mislead developers into thinking the model performs an action, rather than serving as a core data entity. Such models are often better suited to be service classes or similar, but that’s a topic I’ll cover in a future post on service classes 😌

2. Does It Capture the Responsibility?

In addition to representing an entity, a model's name should also reflect its core responsibility within the application. It’s not just about holding data but about encapsulating the relevant business logic for that data.

The model's name should align with its primary responsibility in order to avoid becoming a dumping ground for unrelated logic. (This happens more often than not! )

For example, a User model should primarily represent the user entity and manage core attributes like name, email, and date_of_birth.

If any additional responsibilities are needed, it is often better to delegate them to service classes (e.g., AuthenticationService) or similar. This allows the User model to remain focused on storing and managing user data.

Bad Model Example:

class UserAuthenticator; end
class UserLogin; end

Why Are They Undesirable? 🤔

UserAuthenticator:
The name suggests it handles authentication logic rather than representing a data entity. This blurs the line between business logic and data representation, making the model harder to understand and maintain. Before you know it, you’re thinking, “So, this model seems to handle authentication logic... but also stores this data... and now it's doing even more business logic too 🤯” Instead, it’s better to use a dedicated service class or similar, keeping the User related model focused on managing user related data while making authentication logic easier to maintain.

UserLogin:

While the name may seem intuitive at first, it can invite responsibilities that are outside the model's intended scope. The name suggests a process (logging in), not a data entity, and this can lead to confusion. Models should represent data entities, not actions or processes. As a result, this name may cause developers to think UserLogin is a service object or something responsible for the login process, when it's actually a model meant to represent user data.

If you start adding behaviors like session management because they seem to align with the name ⚠️, you risk turning the model into a "god object" that tries to handle too many responsibilities. As the model takes on both data and behavior, it becomes harder to maintain and extend. Over time, this can lead to a tangled codebase where the responsibilities of the model are unclear, making it difficult to manage and debug.

3. Avoid Misleading/Imprecise Names

Choosing precise names for models is critical to maintaining clarity in your codebase.

Misleading or imprecise names can lead to confusion and introduce subtle bugs, as they fail to communicate the model’s true role or behavior. Clear naming helps developers quickly understand the purpose of a model, what data it holds, and how it interacts with other parts of the application.

Example 1: Dialog vs Modal

Consider UI components:

Dialog: A non-blocking window that allows users to interact with other elements in the app while it's open. Common use cases include information displays, prompts, or optional actions.
Modal: A blocking window that prevents the user from interacting with the rest of the application until the action within the modal is addressed. It's commonly used for critical tasks like confirming a deletion or completing an essential form.

Even though they are similar, the distinction between these two components can be important. Mislabeling a Modal as a Dialog can confuse developers and lead to incorrect assumptions about its behavior, affecting both the code and user experience.

Example 2: Consent vs Agreement

In legal contexts, Consent and Agreement have distinct meanings, but they’re often used interchangeably, which can lead to ambiguity when naming models:

Consent: The act of granting permission or approval for something to happen. In legal contexts, it’s typically one-sided and can be revoked at any time.
Agreement: A mutual understanding or contract between two or more parties, usually involving commitments or promises, and often legally binding.

When naming models related to permissions or legal terms, it’s crucial to use these terms correctly. Confusing Consent with Agreement could mislead developers and result in improper handling of user data or permissions, which might have legal consequences. Proper naming ensures that models represent the right concepts and helps maintain clarity in both the code and the business logic.

Using misleading or imprecise names for models can cause confusion, making it difficult for developers to understand their role and function. Clear, accurate names are essential for maintaining the integrity of your codebase and ensuring proper functionality. Precise naming ensures that the right concepts are represented and makes it easier to manage the application as it grows.

4. Avoid Using Verbs in Model Names

When naming models, you should often avoid using verbs(or names that ends with -ing or -er) that imply actions.

Using verbs in model names can create unnecessary confusion, as it might suggest that the model is responsible for performing an action rather than simply representing data.

Avoid:

class FeeAdder; end

FeeAdder implies that the model is responsible for performing an action—specifically, adding a fee. However, models should represent data entities, not actions. The model name doesn’t clearly convey what the class represents, but rather what it is supposed to do. This could confuse developers about the class's purpose and make it unclear where the actual logic for adding a fee should reside.

Better:

class Fee
  # Represents a fee entity, focusing on attributes like amount, type, and associated details,
  # without being tied to the action of adding or creating the fee.
end

The model now represents the entity itself, which could include attributes such as amount, fee type, payment schedule, or any other characteristics relevant to the fee. The action of adding or creating a fee is better handled by a separate component, such as a service object or controller, rather than in the model itself.

5. Avoid Using Vague or Overly General Names

Names like Info, Data, or Details might seem fine at first glance, but they are too vague to effectively describe the specific role of the model. These names don’t provide enough context or clarity, making it difficult for developers to understand what the model actually represents or how it fits into the system.

Avoid:

class FeeInfo
  # "Info" is too vague and doesn’t specify what kind of information this model holds.
  # It could refer to any kind of fee-related data, such as amounts, types, discounts, etc.
end

Using generic terms like "Info" can make things unclear and lead to confusion. For example, a name like FeeInfo could mean a lot of things—whether it's about a fee's description, its discount structure, payment terms, or just a list of amounts. This vagueness makes it harder for developers to quickly understand what the model is really for, and they might make incorrect assumptions about its purpose.

This confusion can also cause headaches when it's time to extend or maintain the model. For example, if you're adding logic for fee discounts based on customer types, it's not clear if FeeInfo is the right model for that. This uncertainty can slow down both adding new features and debugging existing ones. 🛠️

Plus, names like "Info" end up making the model names longer without really helping anyone understand what it does. This bloats the codebase and makes it harder to navigate. If you have models named UserInfo, OrderInfo, and ProductInfo, for example, developers might waste time figuring out what each one actually does.

Better:

class FeeStructure
  # Indicates that the model represents the fee structure,
  # including different fee types, rules, and pricing logic.
end

FeeStructure explicitly describes the fee-related logic, avoiding confusion. This is much more specific and directly convey the purpose of the model.

How to Name Model Methods

When naming model methods, it’s essential to choose names that clearly communicate the behavior, purpose, and intent of the method. A well-named method provides instant clarity on what it does, why it exists, and how it should be used, without requiring anyone to read through its implementation.

Behavior: Focuses on what the method does in terms of business logic. Does it calculate something? Retrieve data? Or modify state?
- ✅ order.total_price → Calculates the total price, accounting for discounts and taxes.
- ❌ order.price → Unclear whether this is the base price, discounted price, or something else.
Purpose: Explains why the method exists—what problem it solves or what role it plays in the system.
- ✅ subscription.active_users → Returns only the users with an active subscription.
- ❌ subscription.users → Too vague—does it return all users, just active ones, or even canceled ones?
Intent: Reflects how the method should be used—whether it's a query (retrieving data) or a command (modifying state).
- ✅ user.deactivate! → Clearly modifies the user’s state, indicating a destructive action.
- ❌ user.set_inactive → The intent is unclear—does it save the change or just set an instance variable?

In my experience, if you struggle to name a method, it’s often a sign that the model name itself might be unclear.

A well-named method should feel natural and intuitive when read aloud in the context of the model. If you find yourself hesitating while naming a method, it could mean that the model’s name doesn’t accurately reflect the entity it represents.

For example:

✅ User.admin? → Makes sense because "User" is a well-defined entity, and asking if a user is an admin is a natural question to ask.

❌ UserAdding.admin? → Feels unnatural because UserAdding suggests an action, not an entity. What does it mean for an "adding process" to be an admin? This awkwardness signals that the model itself might need renaming.

I tend to find that this issue often appears when models are named after processes or actions (UserCreation, FeeProcessing, SubscriptionHandling) instead of the actual domain entity (User, Fee, Subscription). When the model is not well-named, every method added to it will feel slightly off, leading to unclear and awkward method names.

A good rule of thumb: If you struggle to name a method concisely, reconsider the model’s name first. A well-named model leads to method names that feel obvious and easy to understand.

With this in mind, let’s dive deeper into specific strategies for naming model methods clearly and concisely. The following tables will walk you through different types of methods and provide examples of good and bad naming practices.

1. Naming Methods for Getting Data

Methods that retrieve data should clearly express what they return. They should be descriptive, but not redundant, avoiding unnecessary prefixes like get_. The method name should make it clear whether it returns a single item or a collection.

Good Example	Bad Example	Why?
`order.total_price`	`order.price`	`"price"` is too vague—does it mean the base price, discounted price, or final total? `"total_price"` is explicit.
`company.employees`	`company.get_employees`	`"get_"` is unnecessary—method calls should be declarative, not imperative. `"employees"` is enough.

2. Naming Methods for Updating Data

Methods that modify data should describe what they change, not how they do it. Avoid vague or generic names like modify, which don’t specify what is being changed. If a method modifies data, consider adding ! to signal a state change.

Good Example	Bad Example	Why?
`user.update_email_address!`	`user.modify_email`	`"modify"` is ambiguous—it doesn’t specify whether it updates, deletes, or formats the email.
`subscription.cancel!`	`subscription.change_status`	`"change_status"` is vague—it could mean activating, pausing, or canceling. `"cancel!"` is explicit.

3. Naming Methods That Return Boolean Values

Boolean methods should ask a clear question and return true or false. Use ? at the end of the method to indicate a predicate. Avoid method names that suggest they return a status, object, or string rather than a boolean value.

Good Example	Bad Example	Why?
`user.admin?`	`user.is_admin?`	`"is_"` is redundant—Ruby convention prefers `?` methods for predicates.
`order.paid?`	`order.payment_status`	`"payment_status"` sounds like it returns a string or object, not just `true` or `false`.
`product.in_stock?`	`product.has_stock?`	`"has_stock?"` is unnecessary—"in_stock?" is more natural and aligns with human language.

4. Avoiding Implementation Details in Method Names

Method names should focus on what they represent, not how they work. Avoid tying methods to specific implementations, like database queries or API calls, since these details can change over time. Instead, name methods based on their domain meaning.

Good Example	Bad Example	Why?
`user`	`fetch_user_from_db`	`"fetch_user_from_db"` ties the method to one specific implementation. What if users are cached?
`notifications`	`retrieve_notifications_from_redis`	`"retrieve_notifications_from_redis"` locks the method to a specific storage. `"notifications"` allows flexibility.

5. Clearly Differentiating Between Queries and Commands

Queries return data and should never modify state, while commands modify state and should include "!" if they have potentially dangerous side effects. Mixing these two can cause unexpected behavior—or worse, accidentally change data when you only meant to retrieve it.

Imagine asking a waiter:
🧑‍💼 "Do you have a blueberry muffin?"
👨‍🍳 "Yes, and I just placed an order for you! You will be charged $12!"

Wait, you just wanted to check, right? Not commit to an order! This is what happens when a method that looks like a query (order.cancel) actually modifies state—it surprises developers and leads to unintended changes.

Good Example	Bad Example	Why?
`order.cancel!`	`order.cancel`	Commands that modify state should end in `!` to signal they change data.
`subscription.renew!`	`subscription.renew_subscription`	`"renew_subscription"` is unnecessarily long—"renew!" is already clear within the context of a subscription.
`user.active?`	`user.is_active`	Queries should end with `?` to indicate they return a boolean.
`cart.total_price`	`cart.calculate_total_price`	`"calculate_total_price"` suggests an action rather than a simple lookup—queries should describe what they return, not how.
`product.discontinued?`	`product.check_if_discontinued`	`"check_if_discontinued"` sounds like an action—a simple `?` method is clearer.

6. Handling Plurality Correctly

Use plural names for collections and singular names for single objects. Avoid redundant terms like _list, _records, or _collection, as it’s already understood that a method returning multiple objects is an array or collection.

Good Example	Bad Example	Why?
`company.employees`	`company.employee_list`	`"employee_list"` adds unnecessary verbosity—"employees" is expected to be a collection.
`user.friends`	`user.friend_records`	`"friend_records"` makes it sound like a raw database query instead of a meaningful method.

Wrapping Up:

Naming is a small but powerful aspect of software development in rails that greatly impacts code clarity and maintainability. The process of naming might take time to get used to, but it’s a goodd investment in cleaner, more maintainable code 😎. With thoughtful naming practices, your Rails applications will not only function well but also be easier to scale and collaborate on 😌

When Controllers Take on Too Much Responsibility

Michiharu Ono — Sun, 12 Jan 2025 05:01:30 +0000

In software development, following object-oriented programming (OOP) principles is key to building systems that are easy to maintain(If you were interested, I've covered this topic in this post so please have a look 👀)

But let’s face it—while we all recognize the importance of OOP, actually implementing these principles can be tricky, especially early in our careers or when we’re racing to meet deadlines.

One common pitfall in backend development is when controllers end up taking on too much responsibility. I believe this happens a lot especially when backend design is heavily shaped by frontend requirements, leading to bloated controllers that mix concerns and violate OOP principles.

In this post, I’ll attempt to unpack why this tends to happen, explore the risks of overburdened controllers, and share how to design a more maintainable solution that keeps your codebase scalable. Let’s get started! 🚀

Why Do Controllers Take on Too Much Responsibility?

Before diving into examples, let’s take a moment to reflect on why controllers often end up doing more than they should 🤔 In my observation, there are a couple of reasons why developers sometimes let controllers carry too much weight:

The Pressure to Ship Quickly

Deadlines can be relentless, and under that pressure, quick fixes sometimes win over thoughtful design. It’s “easy” to write everything directly into the controller—fetching data, applying business logic, and formatting JSON—because it feels like the fastest way to meet frontend requirements.
Temporary Features That Overstay Their Welcome

Sometimes, developers ship features intended to be temporary—a quick fix for an event, promotion, or beta test. Because these features are labeled as "short-term," taking the time to structure the code properly often feels unnecessary. After all, why bother refactoring or adding extra layers for something that’s supposed to disappear soon, right?

But here’s the catch ⚠️: those temporary features have a way of sticking around much longer than expected. Deadlines slip, priorities shift, or stakeholders decide to make the feature permanent. Suddenly, what started as a quick-and-dirty addition becomes a lasting part of the application, leaving behind tightly coupled controller code that’s difficult to maintain, extend, or debug.
“It works, so what’s the problem?😗”

When you haven’t yet experienced the downsides of overburdened controllers—like wrestling with a tangled codebase, overhauling the frontend, chasing down elusive bugs, or enhancing existing features—it’s easy to overlook the importance of separation of concerns. I’ll admit, I’ve been guilty of this myself 🙋‍♂️.

It’s a bit like boxing: you don’t fully appreciate the value of keeping your guard up until you take a punch to the face.

Without the perspective of long-term projects, it can be tempting to focus on code that “just works” in the moment, rather than considering how all the pieces will fit together down the line.

What Happens When Controllers Take on Too Much?

When controllers take on too many responsibilities—fetching data, applying business logic, and formatting responses—it can often lead to two major issues. These problems not only make the code harder to work with but can also create a ripple effect of complications down the line:

Tight Coupling Between Backend and Frontend Code

When controllers handle both backend logic and frontend-specific requirements, it creates tight coupling between the two. For example, if the frontend expects a specific JSON format to display a product’s sale status, any change to that format might require updates to both the backend logic and the frontend code.

This direct connection means that updates in one area can unexpectedly break or require adjustments in the other, making maintenance more complex. A more flexible approach is to decouple the backend and frontend, allowing each to evolve independently without creating unnecessary dependencies.
Shifting from Object Interaction to Step-by-Step Procedural Flow

In OOP, objects should manage their own behavior. For example, a Product object would know if it's on sale (on_sale?). However, when controllers become overly focused on frontend needs, they start manually assembling data in a step-by-step fashion. This results in procedural flow, where the controller handles all the logic instead of letting the objects themselves manage it.

By shifting away from object interaction, we lose the benefits of encapsulation, reusability, and maintainability.

Example: Product Listing

Imagine you’re building a product listing page for your web app. The frontend needs details like product names, prices, and whether each product is on sale. A quick implementation might look like this:


class ProductController
  def list
    products = Product.all.map do |product|
      {
        name: product.name,
        price: product.price,
        is_on_sale: product.discount > 0
      }
    end

    render json: { products: products }
  end
end

This implementation works—but it might come with several challenges:

Reduced Reusability:

The sale determination logic is now tied to the context of this specific controller method. If another part of the application (e.g., a report generator or an API endpoint) needs to determine if a product is on sale, developers might copy the logic instead of reusing it, leading to more duplication.
Tightly Coupled JSON Formatting

When the controller directly defines how JSON is structured to meet frontend requirements, it mixes presentation logic with business logic. The controller’s primary responsibility should be handling the request/response cycle, not deciding how the data should be presented. This makes the controller more complex and tightly coupled to the frontend, so any changes to the frontend’s data format will require updates in the controller, leading to unnecessary dependencies and making the system harder to maintain.
Testing Challenges

Do you write tests in controller level? In rails, most of the time, it is better to write business logic else where and controller should just focus on fetching objects. If you code like above, testing the controller now requires ensuring that the sale logic is correct in addition to verifying the controller's primary responsibility (e.g., routing and rendering). This increases the complexity of the test suite and makes the tests more fragile, as they are tied to both business logic and controller logic.

More "Maintainable" Solution

Instead of cramming everything into the controller, let’s spread the responsibilities across models and presenters. This approach keeps each piece of code focused on its specific role.

Here’s a refactored version:

class Product
  def on_sale?
    discount > 0
  end
end

class ProductPresenter
  def initialize(product)
    @product = product
  end

  def as_json
    {
      name: @product.name,
      price: @product.price,
      is_on_sale: @product.on_sale?
    }
  end
end

class ProductController
  def list
    products = Product.all.map { |product| ProductPresenter.new(product).as_json }
    render json: { products: products }
  end
end

💡Why This Works

By distributing responsibilities across models, presenters, and controllers, we achieve a cleaner and more maintainable solution. Each layer now focuses on its core responsibility, making the codebase more flexible, reusable, and testable. Here's why this approach is more maintainable:

Encapsulation

The Product model encapsulates the logic for determining if it’s on sale. Any changes to this logic only need to be made in one place.
Abstraction

The ProductPresenter handles JSON formatting, separating it from both the controller and the model.
Reusability

If you need to format products differently in another context (e.g., an admin dashboard), you can create a new presenter without touching the core logic.
Testability

Each layer can be tested independently 😎: models for business rules, presenters for formatting, and controllers for request handling. It is easy to write tests.

Conclusion

When controllers take on too much responsibility, they violate key principles of OOP and separation of concerns. This leads to tightly coupled, procedural-style code that’s harder to maintain and extend.

By focusing on designing robust objects and delegating responsibilities appropriately, you can keep your codebase clean and adaptable to changing requirements. Remember: controllers aren’t meant to carry all the weight of your backend—they’re just one part of a well-designed system 😌 Keep them lean and focused, and your future self and teammates will thank you!

(BTW, I’m not necessarily against so-called 'dirty coding.' Feel free to check out this post I wrote previously on the topic.)

Big Picture: Practical Steps for Upgrading the Ruby on Rails Version in a Small to Medium-Sized App 🚀

Michiharu Ono — Sun, 08 Dec 2024 03:27:19 +0000

Upgrading a Rails app to the latest version can feel overwhelming.

I had no idea where to start when I tackled it for the first time.

Deprecation warnings, gem conflicts, and the infamous “it works locally but not on production 🫥” surprises can make the process seem like a maze of headaches.

But don’t worry. With a clear plan and a step-by-step approach, it doesn’t have to be daunting. After upgrading my app from Rails 5 to Rails 7 and learning through mistakes, I would like to share the steps I’ve found most helpful 🚀

Step 0: Have a Degradation Test Ready

Before upgrading rails, it’s crucial to have a degradation test in place. A degradation test is a combination of automated tests (like unit, integration, or system tests) and manual tests that ensure the critical functionality of your application remains intact after changes. Essentially, it’s your safety net to catch breaking issues early.

If you already have a robust set of tests for major upgrades, great! If you don’t, it’s probably not realistic to start creating a comprehensive automated test suite just for the rails upgrade—it would be a monumental task. Instead, focus on creating comprehensive manual tests for your app’s core functionality 👀 Identify key features that must work without fail and document step-by-step processes to verify them.

With these tests ready, you'll feel more assured about handling the upgrade without worrying about breaking key features. While creating them might seem tedious now, they’ll save you time and headaches during this and future upgrades.

Step 1: Read the Official Migration Guide

This is one of the most important steps 🔥 in upgrading your Rails version—it sets the foundation for a smooth and successful migration.

Before diving in, bookmark the official Rails upgrade guide. This is your go-to resource for version-specific advice, highlighting key changes that could impact your app.

Take a moment to grab a coffee ☕️ and read through the documentation. As you go, create a checklist of the changes you’ll need to tackle, so you can work through them step by step. (Personally, I also create a list of what I don’t understand so that I can systematically research later.)

At first, it might feel overwhelming, especially if it’s your first time upgrading Rails—there’s a lot of information, and some parts may be unfamiliar. But that’s actually a good thing! 💡 Rails goes the extra mile to provide comprehensive guides to help you, something you don’t always get with other libraries. 😅

You may need to do some additional research along the way, but this effort pays off 👍 By understanding the changes and their impact on your codebase, you’ll be better equipped to troubleshoot issues, update your tests, and confidently make the necessary updates later.

Step 2: Fix Deprecation Warnings

When upgrading rails, one of the first things I always deal with is DEPRECATION WARNING. These warnings are rails' way of notifying you that certain features or methods you're using are outdated and will be removed in future versions.

While these warnings don’t necessarily break your app right away, ignoring them could cause issues when you eventually upgrade to the next rails version.

I’ve written an extensive post on the subject that walks you through the process in detail.

Check it out here: Rails and Ruby Deprecation Warnings: Stop Ignoring, Start Fixing.

Step 3: Update Gems

Upgrading rails almost always requires updating your gems to resolve dependency conflicts. While starting with bundle outdated to identify outdated gems might seem like a logical first step, it can be unrealistic for older apps with numerous gems or complex configurations.

A practical approach I often follow is to create a separate test branch for the upgrade. First, I update the Rails version in the Gemfile to the desired version, then run bundle update rails to begin the upgrade process. At this point, you'll likely encounter dependency conflicts, but that's expected 😌

The point here is to identify gems that have dependency conflicts so that you can systematically address these conflicts by updating gems one at a time in a different brach, ensuring each update works seamlessly with your current app’s setup. I believe this method keeps the process manageable while maintaining stability throughout the upgrade.

Here’s a step-by-step approach to manage gem updates effectively:

Create a Test Branch
Start by creating a new branch for the gem updates to keep your main branch stable. This allows you to experiment without affecting the production codebase.
Run bundle update
Execute bundle update rails . This step will likely trigger dependency conflicts. This is part of the process so it is okay 👍
Make a List of Conflicting Gems
Review the errors carefully and compile a list of conflicting gems. This will give you a clear roadmap for addressing each issue systematically and at the right time.
Update Gems Incrementally in Separate Branches
Update each gem from the list in a separate branch. In some cases, certain gems can only be updated after upgrading your rails version. Make a note of these gems 📝, and remember to revisit later.

For a more detailed guide on updating gems effectively, check out my post:

How to Keep Your Ruby Gems Up-to-Date Without the Stress.

This systematic approach ensures a smoother process, keeping your app stable while aligning with Rails’ latest requirements.

Step 4 : Update gem rails version

Once you’ve updated all the necessary gems and resolved dependency issues, it’s time to update your rails version. Run bundle update rails to ensure your application is using the latest rails version specified in your Gemfile.

Step 5 : Run `rails app:update`

Once you’ve successfully updated your rails version, the next step is to run the rails app:update command. This command is a useful tool that helps create new files and update existing ones to align with the latest rails version. However, you’ll also need to adjust the code to fit your specific configuration and needs.

Before running this command, I strongly recommend visiting RailsDiff to review the changes between your current Rails version and the one you’re upgrading to. This step helps you prepare for the updates and better understand the adjustments being made.

One important thing to note is that running this command might update the load_defaults version in your app in config/applicatin.rb. ⚠️You DO NOT have to update the version of load_defaults when upgrading rails version 🙆‍♂️ To better understand how to manage and update load_defaults, refer to my blog:

Demystifying Rails load_defaults: Mastering Configuration Updates.

Step 6 : Update Existing Code

After upgrading rails, it's possible that your application contains code that relies on now-deprecated behaviors. (Carefully review the deprecation warnings you encountered earlier, as they often pinpoint specific areas of your code that need attention.) Use the checklist you created in Step 1 and incrementally make change ✅

In addition, some gem upgrades may only be possible after upgrading rails itself. For these gems, you might find that their behaviors have changed, requiring you to update how your application interacts with them. Use the list from Step 3 and ensure their corresponding code adjustments are thoroughly tested after the rails upgrade is complete.

To streamline this process, I recommend you to use your test suite to catch regressions early. Running your tests after each change can help identify areas where functionality breaks, allowing you to address issues incrementally. Don't forget to also manually test complex workflows or areas that aren’t well-covered by automated tests.

Step 7: Test, Test, Test 😎

Testing is the keystone of any successful rails upgrade—your last line of defense against unexpected issues and your best assurance that your app is production-ready.

By this point, you’ve already laid a solid foundation: you’ve followed the upgrade guide, fixed deprecation warnings, and updated your gems. Now, it’s time to validate everything. This isn’t just about running tests—it’s about systematically uncovering and addressing any lingering issues. Let’s break it down. 🚦

1. Run Your Automated Test Suite

Automated tests can quickly identify broken functionality caused by the upgrade. Again, fix issues incrementally and rerun tests after each fix to confirm that the problem has been resolved.

2. Conduct Manual Testing

Automated tests alone may not be sufficient, especially for complex workflows, user interactions, or edge cases. This is where your manual degradation tests from Step 0 come into play. Focus on critical user-facing features like payment, form submissions, and reports—anything that directly impacts core functionalities.

3. Test in a Staging Environment

Before merging into production, deploy your upgraded Rails app to a staging environment that mirrors production. This step helps catch environment-specific issues that might not appear locally.

4. Plan for Post-Deployment Testing

Even with the most thorough testing, surprises can happen in production. Be prepared to monitor logs, errors, and user reports closely after deployment. Having a rollback plan ready can be a lifesaver in case something goes wrong.

Testing is the final hurdle in your Rails upgrade journey, and while it might feel tedious, it’s worth the effort. Think of it as your safety net that ensures your users experience a smooth, reliable application.

With automated tests passing, manual workflows verified, and staging tests completed, you’ll be ready to confidently deploy your upgraded Rails app. 🚀

Wrapping up

Upgrading a Rails app may seem overwhelming at first, but with a clear plan, it becomes a rewarding process. By preparing degradation tests, addressing deprecation warnings, and updating gems incrementally, you can minimize risks and maintain stability. Thorough testing—both automated and manual—ensures a smooth transition to the new version. Each upgrade strengthens your app’s foundation and boosts your confidence as a developer. Good luck 🚀

Demystifying Rails load_defaults: Mastering Configuration Updates

Michiharu Ono — Thu, 05 Dec 2024 21:45:15 +0000

Have you seen this line in your config/application.rb file?config.load_defaults 7.2

Or maybe you've stumbled across an enigmatic-looking initializer like this?👇

config/initializers/new_framework_defaults_7_0.rb

If you weren’t specifically looking for these, you might not even notice they exist.

In this post, I’ll explain what these settings are and guide you through the steps to manage them effectively.

What is config.load_defaults?

config.load_defaults is a configuration setting in rails that helps manage the default configuration values for a specific rails version.

It ensures that your application uses the configuration settings that are appropriate for the version of rails you're running, while maintaining compatibility with previous versions during an upgrade.

When you specify a version with config.load_defaults, rails will load the default settings for that version into your application. This includes changes to things like middleware, default behaviors, and other framework settings that may have evolved over time.

But, why does config.load_defaults exit?

Upgrading a rails application often means dealing with changes in configuration settings, some of which might involve breaking changes. These changes can impact significant parts of your codebase, and updating everything at once can be risky and time-consuming.

This is where config.load_defaults becomes a lifesaver. When you upgrade Rails, you can use config.load_defaults to explicitly specify the version of Rails that determines your application's default configuration settings.

For example, if you're using Rails 7.1, it’s possible that your app's configurations are still using defaults from 7.0 or below. This happens because rails gives you the flexibility to adopt the new defaults gradually. By doing so, your application continues running without any surprising behavior changes, while you methodically transition to newer settings.

This incremental approach allows you to align your app with the latest version’s best practices and performance improvements at your own pace. It’s a great way to minimize disruptions during an upgrade, giving you time to test and address any issues that might arise 😄

What is new_framework_defaults_x_y.rb?

During the version upgrade process, rails creates a special file in your config/initializers directory called something like new_framework_defaults_X_Y.rb (where X and Y matches your target Rails version) when you run rails app:update.

Think of this file as a cheat sheet 📝 for all the new configuration defaults introduced in that rails version. The settings are conveniently listed as commented-out lines, waiting for you to decide when (and if) you want to enable them.

Why is this file helpful?

Adopting new defaults can sometimes lead to changes in behavior that might affect your app. By uncommenting the settings one at a time, you can test each change individually, ensuring your application behaves as expected. This step-by-step approach minimizes risks and gives you the chance to handle compatibility issues without overwhelming your team—or your app 😌

Once you've uncommented all the lines and are confident your app is running smoothly with the new defaults, you can delete this initializer file. At this point, you should also update your config.load_defaults version to reflect the new Rails version.

What if You Can’t Update to a New Setting?

Sometimes, you might find yourself in a situation where updating to a new configuration setting isn't feasible due to specific constraints.

Don’t worry—you can still update your load_defaults version and work around the issue. 👍

Let’s say you’re working with new_framework_defaults_5_1.rb (meaning your Rails version is 5.1, but your load_defaults is still set to 5.0). If you can’t update the following setting because of a restriction:

config.assets.unknown_asset_fallback = false

You can explicitly override this setting by adding it to your config/application.rb file or one of your initializer files, like so:

config.assets.unknown_asset_fallback = true

Once you've added this override, you can safely bump the load_defaults version to 5.1. This ensures your app benefits from other new defaults while maintaining compatibility for the settings you couldn’t update.

⚠️ However, keep in mind that by taking this approach, you’re deviating from the framework’s default behavior. Make sure you document this exception clearly and regularly revisit it to ensure it remains necessary as your app evolves. Strive to align with the defaults whenever possible to keep your application consistent with rails’ best practices.

Wrapping Up

Keeping your app’s configuration aligned with Rails’ defaults is a critical step in maintaining stability and taking advantage of new features. The combination of config.load_defaults and new_framework_defaults_x_y.rb gives you the flexibility to upgrade safely, one step at a time.

By gradually adopting new settings, you reduce the risk of compatibility issues and ensure your app remains modern and efficient. Document any exceptions, revisit them often, and strive to align with Rails best practices. With these tools and strategies, you can confidently keep your app up-to-date and ready for the future.

Rails and Ruby Deprecation Warnings: Why You Should Care and How to Fix Them

Michiharu Ono — Mon, 02 Dec 2024 21:54:39 +0000

If you’ve ever fired up your rails server (rails s) or console (rails c) and been greeted with a loud "DEPRECATION WARNING,” you’re definitely not alone.

These warnings pop up because rails, in its ongoing evolution , regularly retires older features—features that might still work today but could spell trouble down the road.

In this post, I want to go through what deprecation warnings mean and how to handle them effectively in order to avoid common pitfalls.

TL;DR

Deprecation warnings are rails’(and ruby's) way of giving you a heads-up about features that will soon be removed or changed.
Ignoring them can lead to unexpected issues during upgrades.
Use configurations like config.active_support.deprecation to handle these warnings in development or test environments.
You should at least pay attention to deprecation warnings from both rails and ruby.

Why Should You Care About Deprecation Warnings?

Deprecation warnings are essentially rails’ polite heads-up that a feature or method you’re using is on its way out.

While technically it is just a “warning” that won’t break your app today, ignoring it could set you up for headaches down the road. After all, if it’s called a “warning,” you should probably pay attention to it, right? 😌 When the deprecated feature is eventually removed in a future rails version, your app could break unexpectedly.

When Deprecation Warnings Actually Matter?

From my experience, deprecation warnings matters most when you’re updating your app—especially during rails version upgrades.

Imagine this: you’re in charge of upgrading rails, juggling multiple breaking changes, and managing dependencies across a bunch of gems. The last thing you want is to be blindsided by deprecated features that have been quietly lurking in your app, only to find out they’re no longer supported in the new version. Not fun.

The earlier you tackle these warnings, the smoother your upgrade process will be, and the fewer bugs you’ll run into later. (I get it—keeping an eye on warnings and addressing them right away isn’t always realistic. But trust me, a little proactive effort here can save you down the road.)

Where Do We Find Deprecation Warnings?

In rails, you might see deprecation warnings in various places depending on your environment setup and the context of the issue. Here's where you commonly encounter them:

1. Development Environment Console

Deprecation warnings often appear in the rails server console (rails s) when you run your application in the development environment. These warnings are printed in real-time as you use the app.

2. Test Suite Output

When running your test suite, deprecation warnings might appear in the terminal output if your tests trigger deprecated methods or features. The configuration file for the test environment (test.rb) usually has a different value set for config.active_support.deprecation than development.rb, which is why you may only see the warning when you run your tests. We’ll talk about this in more detail in a later section.

3. Rails Logs

Deprecation warnings are logged in your application's log files (e.g., log/development.log, log/test.log, or log/production.log depending on the environment). These logs can be reviewed to identify and address issues. (This is also based on your value of config.active_support.deprecation )

4. Rails Console

If you're experimenting or debugging in the rails console (rails c), deprecation warnings can appear when you use deprecated methods.

5. CI/CD Pipelines

If you have continuous integration or deployment pipelines, deprecation warnings might appear in the build logs when running tests or tasks.

How do we mange deprecation warning?

There are two primary types of deprecation warnings you should definitely watch for to ensure a smoother upgrade experience in the future:

・Rails-specific warnings
・Ruby-specific warnings

1. Deprecation Warnings in Rails

Rails provides built-in tools to help you manage deprecation warnings effectively. You can configure how your application responds when a deprecated feature is used by adjusting the config.active_support.deprecation setting in your configuration files.

Rails offers several actions you can take to control how deprecation warnings are handled:

raise: Immediately raises an error, halting execution. This is useful for catching deprecated features early in development or testing.
stderr: Prints the warning to the standard error output.
log: Sends the warning to your application's log file. Ideal for apps that have been around for a while and need time to address warnings gradually.
notify: Triggers a notification, like a Slack message or email, whenever a deprecation occurs.
silence: Suppresses the warning entirely. This should be used sparingly.

If you are creating a new app, I would probably configure this setting to :raise in development and test environments. This means that when a deprecated feature is encountered, rails will raise an error immediately. By catching deprecation warnings early in the development cycle, you’ll be able to address them before they become bigger issues.

You can add like this to your config/environments/development.rb or config/environments/test.rb:

config.active_support.deprecation = :raise

HOWEVER, if the app has been around for a while, it might have a lot of warnings so :raise is not an ideal option. You could send the warning to logs and later review it or notify to slack to regularly review.

Furthermore, if you’re not comfortable with globally raising errors for all deprecation warnings, rails allows more granular control. The config.active_support.disallowed_deprecation setting lets you specify individual deprecations that should be handled differently.

This is useful if you've already addressed certain deprecations but want to be alerted if they reappear. You can configure specific deprecations to raise an error, which helps you identify and fix regressions quickly.

config.active_support.disallowed_deprecation = :raise
config.active_support.disallowed_deprecation_warnings = [
  /will be removed in Rails \d+\.\d+/ 
]

This way, you'll be notified if certain deprecated features are reintroduced into your app.

Managing Deprecation Warnings in Ruby

Dealing with deprecations in rails is only part of the story. You also need to pay attention to Ruby deprecations, as these can have a significant impact on your app's future compatibility as well.

A strategy I recommend is to apply the same approach to Ruby deprecation warnings as you do for rails. By handling both sets of warnings in a similar manner, you ensure a more consistent and proactive approach to keeping your app up-to-date.

Thanks to Piotr Jurewicz, who clearly explains how to print Ruby deprecation warnings (e.g., “DEPRECATION WARNING: [RUBY]”), the process is straightforward.

In essence, the Warning module in Ruby includes the warn method, which issues all warnings, typically printed to $stderr. You can customize the behavior of Warning.warn by extending the module with your own method, allowing you to filter warnings or redirect their output. To maintain the default behavior, simply call super within your custom method. However, it's advised not to redefine the instance method Warning#warn, as doing so may interfere with the default warning functionality.

(Read more about the Warning module here: Ruby Documentation)

For example, here’s how you can capture Ruby 2.7 deprecation warnings:

You could also enhance this logic to send notifications to Slack or any other service when a deprecation warning occurs.

module MyWarningFilter
  RUBY_DEPRECATIONS_2_7_2 = [
    "Using the last argument as keyword parameters is deprecated",
    # Add other deprecations as needed
  ]

  def warn(message)
    if RUBY_DEPRECATIONS_2_7_2.any? { |warning| message.include?(warning) }
      ActiveSupport::Deprecation.warn(message)
    else
      super
    end
  end
end

Warning.extend(MyWarningFilter)

I highly recommend reading Piotr’s blog post, as it provides detailed guidance on creating initializer files like the one above for various Ruby and Rails combinations. You’ll gain deeper insights into how to handle deprecation warnings effectively:

Do You Tune Out Ruby Deprecation Warnings?

Wrapping up

When you see deprecation warnings, it’s better not to ignore them—taking responsibility and action now will save you time and frustration later.

Proactively managing these warnings ensures your app stays compatible with future versions of rails and Ruby. Addressing them early helps prevent issues during upgrades and maintains the health of your application. By utilizing rails’ built-in tools and customizing Ruby’s Warning module, you can stay ahead of potential problems. Taking action now ensures a smoother, more stable development process in the long run.

How to use gem omniauth and omniauth-oauth2 to implement SSO for multiple customers

Michiharu Ono — Sun, 01 Dec 2024 03:01:44 +0000

I recently had the opportunity to set up SSO in a Ruby on Rails app for a very unique situation, so I decided to write about my experience.

This guide might be helpful to you if:

You plan to use OpenID Connect as the authentication protocol.
You need to implement SSO for multiple customers, and at least two of them use the same identity provider (IdP), such as Okta.
Your Rails setup does not support dynamically configuring client information as described in other solutions.
Due to customer-side limitations, their IdP CANNOT send custom parameters back to your Rails application. (*Most of the time, they should be able to do so. )
You cannot use third-party tools like Keycloak because of resource constraints or compliance requirements prohibiting external IAM solutions.

Suppose you have to implement SSO for two customers that use Okta for identity management, given the limitation above, there is a walk around😃

Let's dive into the actionable steps to implement SSO in your Ruby on Rails app while addressing the limitations described earlier!

Step 1: Add the required gems and run bundle install

# Gemfile
gem 'devise'
gem 'omniauth'
gem 'omniauth-rails_csrf_protection' # NOTE: Required as a countermeasure for CVE-2015-9284 in the omniauth gem.
gem 'omniauth-oauth2' # NOTE: Used to create Strategies classes for omniauth.

Step 2: Define the endpoints.

# config/routes.rb 
get 'auth/customer_a/callback', to: 'omniauth/sessions#create'
get 'auth/customer_b/callback', to: 'omniauth/sessions#create'

Step 3: Add a migration file and run rails db:migrate.

# db/migrate/xxxx.rb
class AddOmniauthColumnsToUsers < ActiveRecord::Migration[7.2]
  def change
    add_column :users, :provider, :string
    add_column :users, :uid, :string
  end
end

Step 4: Add the self.from_omniauth(auth) method as a class method in the User model to create or find a user based on authentication data from an external service. (Ensure to include error handling tailored to your app's requirements.)

 # app/models/user.rb
 class User < ApplicationRecord
    devise :database_authenticatable, :registerable, :recoverable, :rememberable, :trackable, :encryptable
    ...

  def self.from_omniauth(auth)
    find_or_create_by(email: auth['info']['email']) do |user|
      user.provider = auth['provider']
      user.uid = auth['uid']
      user.email = auth['info']['email']
      user.name = auth['info']['name']
    end
  end
 end

Step 5: Add a controller (Ensure to include error handling tailored to your app's requirements. Your customer could make their mistakes in configuration setup as well.)

*Note: You need the id_token to end an Okta session, so it is recommended to store it in the session. Use the rail’s reset_session helper to remove this when a user wants to log out.

class Omniauth::SessionsController < ActionController::Base
  def create
    omniauth_auth = request.env['omniauth.auth']
    id_token = omniauth_auth['extra']['id_token']
    user = User.from_omniauth(omniauth_auth)
    if user
      session[:id_token] = id_token
      sign_in(:user, user)
      redirect_to root_path
    else
      redirect_to redirect_path, alert: 'Add a custom alert statement here'
    end
  end

Step 6: Create a method to define an OmniAuth OAuth2 strategy for each customer.

Most of the code is from the following gem: omniauth-okta

# config/initializers/omniauth_okta.rb
require 'omniauth-oauth2'

OIDC_DEFAULT_SCOPE = %{openid profile email}.freeze

def create_omniauth_strategy(name)
  Class.new(OmniAuth::Strategies::OAuth2) do

    option :name, name
    option :skip_jwt, false
    option :jwt_leeway, 60

    option :client_options, {
      site:                 'https://your-org.okta.com',
      authorize_url:        'https://your-org.okta.com/oauth2/default/v1/authorize',
      token_url:            'https://your-org.okta.com/oauth2/default/v1/token',
      user_info_url:        'https://your-org.okta.com/oauth2/default/v1/userinfo',
      response_type:        'id_token',
      authorization_server: 'default',
      audience:             'api://default'
    }
    option :scope, OIDC_DEFAULT_SCOPE

    uid { raw_info['sub'] }

    info do
      {
        name:       raw_info['name'],
        email:      raw_info['email'],
        first_name: raw_info['given_name'],
        last_name:  raw_info['family_name'],
        image:      raw_info['picture']
      }
    end

    extra do
      {}.tap do |h|
        h[:raw_info] = raw_info unless skip_info?

        if access_token
          h[:id_token] = id_token

          if !options[:skip_jwt] && !id_token.nil?
            h[:id_info] = validated_token(id_token)
          end
        end
      end
    end

    def client_options
      options.fetch(:client_options)
    end

    def raw_info
      @_raw_info ||= access_token.get(client_options.fetch(:user_info_url)).parsed || {}
    rescue ::Errno::ETIMEDOUT
      raise ::Timeout::Error
    end

    def callback_url
      options[:redirect_uri] || (full_host + callback_path)
    end

    def id_token
      return if access_token.nil?

      access_token['id_token']
    end

    def authorization_server_path
      site = client_options.fetch(:site)
      authorization_server = client_options.fetch(:authorization_server, 'default')
      "#{site}/oauth2/#{authorization_server}"
    end

    def authorization_server_audience
      client_options.fetch(:audience, 'default')
    end

    def validated_token(token)
      JWT.decode(token,
                 nil,
                 false,
                 verify_iss:        true,
                 verify_aud:        true,
                 iss:               authorization_server_path,
                 aud:               authorization_server_audience,
                 verify_sub:        true,
                 verify_expiration: true,
                 verify_not_before: true,
                 verify_iat:        true,
                 verify_jti:        false,
                 leeway:            options[:jwt_leeway]
      ).first
    end
  end
end

okta_sso_customers = ['customer_a', 'customer_b']

okta_sso_customers.each do |name|
  strategy_class = create_omniauth_strategy(name)
  OmniAuth::Strategies.const_set(name.camelize, strategy_class)
end

Step 7: Add omniauth.rb. Use ENV variables and avoid hardcoding secrets in configuration files.

# config/initializers/omniauth.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :customer_a,
        ENV['OKTA_CLIENT_ID'],
    ENV['OKTA_CLIENT_SECRET'],
    client_options: {
      site: ENV['OKTA_ISSUER'],
      authorization_server: ENV['OKTA_SERVER_NAME'], # e.g., 'default'
      authorize_url: "#{ENV['OKTA_ISSUER']}/oauth2/#{ENV['OKTA_SERVER_NAME']}/v1/authorize",
      token_url: "#{ENV['OKTA_ISSUER']}/oauth2/#{ENV['OKTA_SERVER_NAME']}/v1/token",
      user_info_url: "#{ENV['OKTA_ISSUER']}/oauth2/#{ENV['OKTA_SERVER_NAME']}/v1/userinfo",
      audience: ENV['OKTA_AUDIENCE'], # e.g., 'api://default'
     },
    redirect_uri: ENV['OKTA_REDIRECT_URI']

   provider :customer_b,
        ...
end

Wrapping Up

Implementing SSO with the outlined steps makes it easier to set up seamless authentication for multiple customers using OpenID Connect—even in tricky situations like this one! 😊

I know this is not really the most straightforward way of using gem omniauth but if you find yourself in a similar boat, think of this guide as your starting template 🛠️, ready to be customized for your specific needs. By using OmniAuth and creating tailored strategies for each identity provider, you’re building a scalable and secure authentication setup that works for everyone involved. 🚀

Resources:
https://medium.com/@petro.yakubiv/authentication-with-okta-and-devise-in-ruby-on-rails-app-2e81a8c6b198

Practical Steps: How to Strategically Update Your Ruby Gems

Michiharu Ono — Fri, 29 Nov 2024 00:29:07 +0000

Updating Ruby gems seem like a simple task, but it could be a bit more complicated especially when you deal with apps that have been around for a while.

Keeping your Ruby gems up to date is essential for maintaining the security, performance, and compatibility of your application. Regular updates ensure you’re not only benefiting from the latest features but also protecting your app from vulnerabilities.

However, as with most things in development, we all know that it’s rarely that simple 🤷‍♂️ You’ll likely encounter breaking changes, dependency conflicts, and other challenges that require a more thoughtful approach.

In this post, I’ll walk you through a step-by-step guide to updating Ruby gems, including how to handle conflicts and assess your options when things go wrong. By understanding the overall process, I hope that you'll feel more confident and equipped to tackle these challenges when they arise 😊

Steps to update gems

Updating a gem isn’t just about bumping its version number—it’s a process that requires careful consideration to avoid introducing issues into your app. I tend to follow the structured approach below to make it manageable and easier to communicate changes to the team:

Step1: Read the Changelog:

The first step is to thoroughly read the changelog or release notes. These typically outline new features, improvements, bug fixes, and, most importantly, any breaking changes that could affect your application. (If the repository is well-maintained, it usually includes changelogs or at least release notes.) A few key things to look for in the changelog:

👀 Breaking Changes: These are the changes that can cause your code to break, so you definitely want to pay attention to them. They might involve things like renamed methods, altered method signatures, or the removal of features. If there are significant changes, you’ll probably need to adjust some parts of your code to make everything work with the new version.

⚠️ Deprecations: Sometimes gems mark certain features or methods as "deprecated." This means they’ll still work for now but will be removed in future updates. It might be tempting to ignore them since they aren't technically breaking your app yet, but it’s a good idea to tackle these early on. Fixing deprecations as they pop up saves you from headaches later and makes future updates smoother.

🚀 New Features and Enhancements: Updates often bring new features or performance improvements, and these can be real game-changers. These new additions are designed to make your life easier, so it’s definitely worth taking a moment to explore them.

(By the way, when upgrading to major versions, like updating Rails, you can also look for the “migration guides”. These guides are created specifically to help you navigate the big transition smoothly! )

Step2: Review Dependencies:

When updating a gem, it’s essential to take a look at its dependencies—other gems or libraries it relies on to function properly. Many gems have specific version requirements for their dependencies, and those dependencies might also need to be updated to ensure compatibility.

If the gem you're updating depends on an older version of another gem, you might run into conflicts, especially if that dependency also needs to be updated for your app to function correctly. For example, if you’re updating a gem that depends on an older version of Rails, you may need to update Rails as well or adjust some of your app’s code to match the new dependency requirements. We will talk a bit more about this later.

Step3: Change your codebase if necessary:

Once you’ve reviewed the changelog and dependencies, you can begin making any necessary changes to your codebase. (In some cases, refactoring the existing codebase beforehand can make the gem update process smoother.)

Step4: Test Thoroughly:

Run your test suite before and after the gem update. This ensures the update doesn’t introduce regressions or break functionality(Also, do manual testing when necessary.).

Step5: (optional) Use Dependabot or Similar Tools:

Tools like Dependabot automate dependency updates and alert you to conflicts or vulnerabilities.

What to Do When You Encounter a Dependency Conflict

Updating gems doesn’t always go smoothly. Dependency conflicts can often arise, especially in apps with complex or older codebases.

Understand the cause

Start by reading the error messages or Bundler output carefully. Determine which gem or dependency is causing the issue and why. For example, a conflict could arise because one gem depends on an older version of a library, while another gem requires the latest version.

Knowing the exact cause helps you decide whether you need to update the conflicting gem or whether you need to address other issues in your app’s dependencies.

So what action should I take?

When you exactly know why you have the issue, you can now evaluate your options😃 I listed six options below (but the list is not exhaustive):

==Option 1: Update the Conflicting Dependency==

If the conflict stems from an outdated dependency, the first and most straightforward step is to update the conflicting gem or its dependency to a version that resolves the issue.

This is your go-to option when the conflicting dependency is outdated and you can safely update it without causing issues for other dependencies. (but ensure you understand the changes of conflicting gem and run tests accordingly)

==Option 2: Downgrade the Gem==

If updating the conflicting dependency isn’t feasible (perhaps due to a major release with breaking changes), you may need to downgrade to a version of the gem that’s compatible with the rest of your dependencies.

This option is useful when an update introduces breaking changes that are difficult to address immediately or when the update causes issues that are not easily resolved. If the gem remains functional at a lower version, it can serve as a temporary solution.

However, downgrading a gem is not ideal, as it may result in losing important features, bug fixes, or security patches. Additionally, if the gem is no longer actively maintained, this could leave you vulnerable in the long term. If you choose this approach, it’s essential to have a plan to address the issue in the future. 🙂

==Option 3: Fork the Gem==

When the gem you rely on doesn’t offer a solution or has an issue that the maintainers haven’t addressed, you can fork the gem and apply a patch or modify it to fix the issue. Forking is a good option when the gem is particularly critical to your app and there are no alternatives.

However, it should only be used as a temporary fix, and you should aim to contribute your changes back to the original repository if possible. I personally found that maintaining a fork of a gem can be time-consuming, especially if the gem is updated frequently.

You’ll need to stay on top of changes to the upstream repository to ensure your fork doesn’t fall behind. Additionally, applying your own fixes could introduce unforeseen bugs.

==Option 4: Use Patch Gems or Monkey Patching==

If the conflict is isolated to a specific part of a gem, you can apply a patch to address the issue, or use monkey patching to modify certain methods or behaviors in the gem.

This approach is useful when you need a quick fix for a minor issue in the gem but should be used sparingly. Monkey patching can make your codebase a little harder to maintain and debug, especially if the gem undergoes updates that conflict with your patches. It can also lead to subtle bugs that are hard to trace.

==Option 5: Delay the Update==

If the gem update is not immediately critical, consider postponing it until a more stable version is released or a resolution to the conflict becomes available.

This approach is reasonable if the update is not urgent and resolving the conflict would take significant time or effort. However, delaying an update may not be ideal if the new version includes critical security patches. Assess the risks of delaying carefully, especially if the update addresses vulnerabilities or is part of a broader release that enhances your application’s stability or functionality.

==Option 6: Replace the Gem Entirely==

If a gem consistently causes issues or no longer meets your requirements, it is a time to consider replacing it with an alternative that offers similar functionality without the conflicts.This approach is ideal when persistent conflicts cannot be resolved through updates, downgrades, or patches, and when better-maintained or more compatible alternatives are available.

Keep in mind that replacing a gem can be time-intensive, particularly if it is deeply integrated into your codebase. It may require substantial code changes and adaptation.

Wrapping up

Updating Ruby gems is crucial for keeping your app secure and efficient, but it can sometimes be tricky. By following the steps in this guide, you'll be prepared to tackle dependency conflicts and breaking changes with confidence. No matter what option you choose—whether it’s updating, downgrading, or replacing a gem—just remember to test thoroughly and stay patient. You’ve got this! 💪

Getting Started with Object-Oriented Design (Part 2): Design Principles and Design Patterns

Michiharu Ono — Wed, 27 Nov 2024 00:52:58 +0000

In the previous article, we have discussed the fundamental goal of Object-Oriented Design (OOD), which is to manage the relationships between objects, allowing the system to adapt efficiently to future changes.

This naturally leads us to the next question: How do we effectively manage the relationships between objects? 🤔

The truth is, there’s no one-size-fits-all approach to this. Every system and context is different, and there are many ways to go about it.

Thankfully, there are some incredibly useful tools to simplify this process 😌 —tools crafted by industry pioneers like the Gang of Four. We owe these visionaries a great deal for sharing their wisdom, which has laid the groundwork for many of the techniques we rely on today.

With that in mind, I'd like to briefly introduce two practical concepts that can help you manage object relationships more effectively: Design Principles and Design Patterns.

They will help set you on the path toward building scalable systems or at least nudge you in the right direction. By applying these concepts, you'll not only enhance the quality of your code but also make your development process smoother and more predictable.

Understanding “Design Principles”

Design principles are general guidelines or best practices that help you make better decisions when writing code. These principles aren’t really specific solutions to problems, but rather broad rules that you choose to follow when applies.

Some popular design principles include:

1. Single Responsibility Principle (SRP)

This principle is about keeping each class focused on a single responsibility(*some might argue but it does not necessarily mean a single class must have only a single public method). This makes the code easier to understand and modify.

2. Open-Closed Principle (OCP)

This principle ensures your code can accommodate new functionality without altering existing code. This reduces the risk of introducing bugs when extending the app. For instance, by using inheritance or composition, you can add features while maintaining the integrity of the original class.

3. Liskov Substitution Principle (LSP)

You should be able to use a subclass anywhere you'd use its parent class without breaking anything. In other words, a subclass should honor the expectations set by its parent class, ensuring it behaves consistently and predictably without introducing errors or unexpected results.

4. Interface Segregation Principle (ISP)

This principle ensures that classes aren’t forced to implement methods they don’t need by promoting the use of smaller, more focused interfaces. In essence, it advocates for splitting large, "fat" interfaces into smaller, specific ones to reduce unnecessary dependencies and improve modularity.

5. Dependency Inversion Principle (DIP)

This states that high-level modules should not depend on low-level modules; instead, both should depend on abstractions. Abstractions should not depend on details, but details should depend on abstractions.

This concept might be self-explanatory at first, but don’t worry—let’s break it down with an example.

For instance, in a coffee maker system, the high-level module is the coffee maker, and the low-level module is the brewing method (e.g., drip, espresso).

If you apply the Dependency Inversion Principle (DIP), the coffee maker depends on an abstraction of the brewing method (an interface or abstract class that defines the brewing process), not on a specific implementation (such as a DripBrew or EspressoBrew class). This allows you to swap out different brewing methods without altering the core coffee maker logic. The coffee maker just needs to know how to interact with the abstraction, making the system more flexible and maintainable.

6. DRY (Don’t Repeat Yourself)

Duplicated code can lead to inconsistencies and make maintenance more difficult. Abstract common functionality into reusable components or methods. This reduces redundancy and ensures that changes only need to be made in one place.

7. Law of Demeter

The Law of Demeter is often summarized as "Only talk to your immediate friends." This principle emphasizes minimizing an object's knowledge of other objects' internal structures or properties. Instead of relying on deep method chaining (obj.getSomething().doAnotherThing()), delegate responsibilities to direct collaborators.

It is important to note that there are MANY MORE of these principles! You don’t really need to perfectly memorize them all but it is nice to know to stop your hands and think about it once in a while. (By the way, if you have every heard of SOLID, it is about the principles from 1 to 5.)

Also, make sure not to overemphasize one principle over another. ⚠️ For example, if you care too much about DRY principle for example, you might compromise other areas that may affect managing the relationships between objects.

Understanding “Design Patterns”

When it comes to object-oriented software design, principles like Single Responsibility and Open-Closed lay the groundwork for creating maintainable systems.

But what about recurring challenges that developers face across projects?

This is where design patterns come into play!

What Are Design Patterns?

Design patterns are proven, reusable solutions to common problems encountered in software design, providing you with practical templates for solving particular challenges.

Think of design patterns as ready-to-use blueprints that you can implement when you face a certain type of problem. These patterns help you avoid reinventing the wheel 🔄 and offer solutions that have already been tested and refined over time.

While design principles provide guidance on how to design, design patterns give you specific techniques or approaches to address particular issues.

Here are five of the commonly used design patterns in object-oriented programming. (There are many more!)

1. Singleton Pattern

Purpose: Ensures that a class has only one instance and provides a global point of access to that instance.

Example Use Case: Managing shared resources like configuration settings where only one instance should exist across the application.

2. Observer Pattern

Purpose: Allows one object (the "subject") to notify other objects (the "observers") about state changes, creating a one-to-many relationship.

Example Use Case: Used for situations where multiple parts of the system need to respond to changes in another part, such as updating UI elements when a model changes.

3. Factory Method Pattern

Purpose: Defines an interface for creating objects, allowing subclasses to alter the type of objects that will be created.

Example Use Case: Creating instances of different types of objects dynamically, for example, when deciding which type of user (admin, guest, etc.) to create based on conditions.

4. Decorator Pattern

Purpose: Adds new functionality to an object dynamically without altering its structure.

Example Use Case: Extending the functionality of existing objects, like adding additional presentation logic to a model object, often used for enhancing UI components.

5. Service Object Pattern

Purpose: Encapsulates business logic into separate classes, improving maintainability and keeping controllers thin.

Example Use Case: Handling complex logic or operations that do not belong in controllers or models, such as processing payments.

Design patterns are like trusty blueprints for tackling common challenges in software design, but they’re not always the right tool for the job. It’s easy to get excited and want to use a design pattern everywhere—I’ve definitely been guilty of this myself 🙋‍♂️

However, overusing them can add unnecessary complexity, so it’s important to step back and consider whether a pattern truly fits your specific problem. When applied thoughtfully, design patterns can be game-changers, helping you build code that’s maintainable, scalable, and clear.

Wapping up

Design principles and patterns are essential tools in a developer's toolkit 🛠️, offering both guidance and practical solutions for creating maintainable, adaptable systems. They’re not always applicable, but when used strategically and thoughtfully, they can simplify complexity and enhance your code's structure.

Always remember to assess your context 🔍 before applying any principle or pattern—what works for one problem might not suit another. With a balanced approach, you can leverage these concepts to build systems that stand the test of time, making both your life as a developer and your codebase far more enjoyable to work with! 😊

Getting Started with Object-Oriented Design (Part 1): Shifting from Process-Oriented to Object-Oriented Thinking

Michiharu Ono — Sun, 24 Nov 2024 02:59:18 +0000

“Hmm… Have you ever heard of OOD?”

That’s what one of the senior developers at my company once asked me, just 10 seconds after glancing at my code.

Without thinking, I quickly replied, “Yes.”

It was an instinctive answer, but the truth was, I didn’t fully understand what Object-Oriented Design (OOD) really meant at the time—or why it even mattered 🤷‍♂️

When we’re just starting out as web developers, it’s easy to focus on learning new languages, frameworks, and building projects as quickly as possible. The goal is often just to get something working, and concepts like OOP or OOD can feel abstract, like something you’ll figure out “later.”

But here’s the thing: later can come much sooner than you expect, especially when your code starts growing in complexity. (At least, it did for me 😅)

At its core, object-oriented design is about managing the relationships between objects, enabling the system to adapt efficiently to future changes.

But why do we need this? And what does managing the relationships between objects mean exactly?

Two Ways to Think About Systems: Process vs. Object-Oriented Perspectives

Before we dive into answering that question, let’s first explore the object-oriented view of the world. Without adopting this mindset, the principles and patterns of OOP can feel abstract and difficult to grasp. 😌

To build a solid foundation first, I want to start by comparing two key ways of thinking about systems: the process-oriented approach and the object-oriented approach. These two paradigms offer different perspectives on how we break down and model problems.

1. The Process-Oriented View

In general, the process-oriented perspective is about focusing on the sequence of actions or steps that need to be performed in a set order to achieve a result.

Don't think too hard on this 🙆‍♂️

It’s similar to following a recipe, where each action follows a specific order, and one step leads to the next. The key here is flow—moving from one state to another by completing predefined actions.

Let’s take a look at the example of making tea from a process-oriented perspective, where the focus is on the sequence of steps:

Boil Water: The first step is to boil water. The key here is that the water needs to be hot enough for the tea, regardless of how long it takes to boil.
Add Tea Leaves: Once the water has boiled, the next step is to add the tea leaves. This step can only happen after the previous one is completed, as it depends on the water being ready.
Let it Steep: After the tea leaves are added, the water must steep for a specific amount of time to extract the flavor.
Pour Tea into a Cup: Finally, after the steeping process is finished, the tea is poured into a cup.

In this approach, the focus is on performing actions in a specific order. If any action is skipped or carried out out of sequence, the result will not turn out as intended.

The process-oriented view sees the world as a series of actions, each building on the one before it, where every step must follow a predetermined flow to achieve the desired outcome.

2. The Object-Oriented View

In contrast, in object-oriented view, the focus is on "objects." These objects are like little workers that have two things: information (called attributes) and actions they can do (called methods).

Instead of viewing tasks as a strict sequence of actions, here we emphasize the interaction between objects, where each object performs actions based on the requests (or "messages") it receives from other objects. In other words, each object can "ask" other objects to do things, and they act based on those requests.

Let’s revisit the tea-making example from an object-oriented perspective.

==The Objects in Tea-Making==

Kettle: The Kettle has information like the current temperature of the water and whether it's boiling. It also has an action it can perform, like boiling the water.
TeaBag: The TeaBag has information about the type of tea and whether it’s steeped or not. It can also steep the tea in hot water.
Cup: The Cup holds the tea once it’s made. It has information about what’s inside (like tea or water) and whether it’s full.
Person: The Person is the one who makes everything happen. The Person asks the Kettle to boil water, tells the TeaBag when to steep, and pours the tea into the Cup. The Person coordinates the entire process.

You can already see how we capture the world is a little bit different from the setup. Now, let’s see some examples of how these objects might work together to make tea:

==How the Objects May Work Together==

The Person tells the Kettle to start boiling the water. The Kettle listens and heats the water without needing further help from the Person.
After the water is ready, the Person checks the TeaBag, maybe looking at how strong the tea should be or how long to steep it. The Person then tells the TeaBag to start steeping the tea (the Person might put the TeaBag in the water and monitor how long it steeps).
Person pours the Tea into the Cup once the tea has steeped enough, the Person checks the tea. If it’s ready, they tell the Kettle to pour the tea into the Cup. The Cup now holds the tea, ready for the Person to drink.

It is describing the same tea-making process, but do you now see the difference from the process oriented view? 🙂

In the object-oriented view, the focus is on how objects interact with each other by sending and receiving messages, rather than following a linear sequence of actions. It is just a different point of view💡 Each object has its own responsibilities and responds to messages (or method calls) from other objects based on its current state. This allows for flexibility—objects don’t rely on a predefined sequence of events but instead communicate as needed.

🤔 So, why do we need object oriented “DESIGN”?

In object-oriented applications, components (or objects) interact with each other, forming complex relationships and dependencies.

If these relationships aren’t properly managed, what would happen? A small change in one part of the code can cause problems in other areas, leading to instability and making the application harder to maintain.

Let's take the same tea-making example again, but this time imagine that the process isn’t organized well at all.

The Kettle and TeaBag are Too Dependent on Each Other:
- Imagine that the Kettle object not only boils the water but also decides how long the TeaBag should steep for some reason. In this setup, if you want to increase the steeping time, it might also affect how long the kettle boils the water, creating unnecessary links between unrelated tasks.
The TeaBag Controls the Boiling Process:
- If the TeaBag itself is somehow responsible for managing the boiling of the water, then it's now mixing two responsibilities: the boiling process and the steeping process. This would mean that any change to how the tea leaves steep (like changing tea types) could unintentionally interfere with how the kettle boils the water. This makes each object too tightly coupled and hard to modify without breaking other parts of the process.
The Cup Gets Involved in the Steeping:
- Now, let’s say the Cup is responsible for checking if the tea is steeped properly before it’s even poured. It may decide how long the tea should steep based on what is poured into it, creating confusion and redundant responsibilities. This prevents each object from focusing on just one task.

In this disorganized setup, making a change in one object (like adjusting how long the water boils) could unintentionally affect other objects, like the steeping time, and cause undesirable consequences, such as over-steeping or under-boiling the water. This results in a lack of flexibility and control, making it harder to manage and maintain.

Now, compare that to the organized object-oriented approach, where we treat each task as an independent object with its own responsibilities. If you want to change how long the tea steeps, you just adjust the TeaBag object without worrying about how the Kettle or Cup will be affected. This way, each part of the process is flexible, independent, and easier to manage. You can make changes to one object without breaking the entire system.

This is why we need OOD. By keeping these tasks separated, OOD lets you make adjustments and scale your system without chaos. This is why OOD is so powerful—it lets your code grow and adapt in a structured, maintainable way.

Wrapping up

OOD offers a way to manage the relationships between objects. While it might feel a little tricky at first, learning OOD ensures that your code isn’t just working for today but is also flexible and ready for future changes. By planning ahead, OOD helps you build code that’s not only sustainable but also scalable, making it easier to adapt as your project evolves.

In the next post, I will explain how to approach object-oriented design and introduce you to some tools.

How 'Conventional Commits' Improved My Development Workflow

Michiharu Ono — Sat, 23 Nov 2024 06:43:29 +0000

When you code, do you already know what goes into your commit messages when creating pull requests? 🤔

It’s not a topic we often discuss, but I’ve found that being intentional with commit messages naturally shapes how I organize my pull requests.

In fact, thinking about how you’ll structure your commits before you even begin coding can significantly benefit your development process in two major ways:

It naturally helps you structure your work: Thinking about the commit message beforehand naturally informs what goes into each commit. For example, you’ll start to distinguish between commits that add new files and those that improve existing features. This makes your commits more logical and easier to track.
It improves code clarity for others and yourself: A clear commit message helps the reviewer understand the purpose of each change. It also aids you in the future when revisiting your code—whether for bug fixes or adding new features—since you'll be able to easily identify what was done in each commit.

Practical Benefits of “Conventional Commits”

To keep things consistent, I’ve been using the “Conventional Commits” standard.

If you’re unfamiliar, Conventional Commits is a standardized way to write commit messages using the format:

type(scope): description.

This format isn’t just about aesthetics—it makes commits more human-readable and machine-processable, which opens the door to automation. For example, tools can use these messages to generate changelogs, handle versioning, or even enforce commit rules in CI/CD pipelines.

By using prefixes like feat, fix, or docs, you quickly convey the intent of each change, improving both collaboration and traceability.

Here’s a quick example of a “Conventional Commit”:

feat: implement filters for product search by price and category

You can tell it’s simple, clear, and instantly communicates the purpose of the change.

Make It Easier with VS Code

One great thing about “Conventional Commits” is that you don’t have to memorize the format. If you use VS Code, there’s an extension to simplify the process:

👉 Install the Conventional Commits Extension

This extension guides you through creating standardized commit messages right from your editor, making it easier to adopt this practice. It's so easy.

Wrapping Up

Being intentional about commit messages might seem like extra work at first, but it’s an investment that pays off VERY QUICKLY. With “Conventional Commits,” you’ll find your workflow becoming more structured, your pull requests clearer, and your development experience smoother overall.

How Focusing on Business Impact Improved My “Technical Debt” Conversations

Michiharu Ono — Thu, 14 Nov 2024 23:33:06 +0000

“The fact that you have technical debt is a good thing.”

I know this sounds counterintuitive.

A senior developer with over 20 years of experience once told me this, and it completely changed the way I thought about technical debt—especially in the fast-paced environment of small startups.

In case if you’ve never heard of the term, technical debt refers to the hidden costs and risks that accumulate in a codebase when shortcuts or compromises are made to achieve short-term goals—such as delivering new features quickly. For example, delaying updates to core dependencies or skipping key testing steps can accelerate development in the moment. But over time, these decisions add up, resulting in a backlog of issues that eventually hinder the team. This debt can lead to a range of future problems, including compatibility issues, maintenance challenges, performance limitations, and even security vulnerabilities. As technical debt grows, each new feature becomes harder to implement, testing becomes more cumbersome, and the system itself becomes more fragile.

When I joined the company as a junior developer, the company was already dealing with significant technical debt, and I struggled with it for over two years. For example, in 2023, while Rails 7.1 was available, we were still using version 5.2. This version lag limited our ability to use newer features and frameworks and left us with outdated dependencies. Furthermore, many libraries had critical updates available, but they hadn’t been applied (fortunately, we hadn’t experienced any security breaches). Additionally, there were several design flaws and coding practices that caused confusion, even among the developers. The lack of proper testing also made it difficult to ensure stability. However, when I observed the tasks assigned to developers, the focus was always on releasing new features by a set deadline. Nobody seemed to address the growing technical debt, and the codebase kept becoming more complex with each new feature built on top of it.

As I grew more anxious about the code’s state, especially as security patches continued to be ignored, I decided to bring up my concerns with a technical advisor at the company. I expected he might encourage me to push harder for code quality or maintenance efforts. Instead, his response completely reframed my perspective.

He explained that, having worked with many startups, he’d seen that most of them failed before they ever accumulated significant technical debt. “The fact that we’re facing these problems,” he said, “is a sign that the business has survived long enough to reach this stage.” This was actually a positive indication: it meant the company was moving forward, gaining users, and facing the same challenges that most successful companies face over time. Without this technical debt, we might not even have a product to work on. He also stressed the importance of prioritizing business success. “In order to for you to keep a job as a developer, the business needs to succeed first and foremost,” he said. “Everything we do should be driven by how it impacts the business, not just by technical concerns.” While code quality and system stability are important, he reminded me that our job as developers is to support the business—sometimes, that means balancing technical debt with the urgency to grow.

That said, he emphasized the importance of always being aware of technical debt and continuously improving the codebase. For developers who don’t control project priorities or tasks, it’s crucial to have good communication skills when discussing the state of the code. For example, if you come out and say, “There are technical debt and security issues, and it’s a problem that needs fixing,” non-technical stakeholders might just see a working product and not understand the urgency. However, if you frame it like this: “Currently, there are unpatched security vulnerabilities in key libraries that could be exploited by hackers. If left unaddressed, this puts the company at risk for data breaches, potential financial losses, and serious reputational harm, as seen in cases like Company XX.” Or, you could add, “Upgrading these libraries will not only mitigate these risks but also reduce ongoing costs, enhance the user experience, and streamline the development process, helping our team to work more efficiently.”

After the talk with him, I believe the way I communicate—not only within the dev team but across the entire company—has improved. By shifting the focus of the conversation to “How can I contribute to the success of the business?” rather than simply saying “Some problems need fixing,” decision-makers are more likely to pay attention and engage in the conversation. Framing the issue in terms of business impact makes it easier to align technical challenges with company goals. As a result, it becomes clearer why certain improvements are important, and it promotes a more collaborative approach to solving problems. Plus, it helps keep everyone on the same page—developers, business stakeholders, and the entire team working toward the same goals.

DEV Community: Michiharu Ono

The Case for Leaky Locks: Redis TTL as Failure Cooldown for Expensive AI Jobs

The Problem I Didn't See Coming: How Releasing Locks Cost Me Money

Using Lock Expiration as a Cooldown Mechanism

Why This Works

The Part I Actually Like

When This Doesn't Apply

Risks worth mentioning

Wrapping Up

How (and How NOT) to Name Rails Models Beyond the Obvious

How To Name Model

1. Does the Model Capture the Entity?

2. Does It Capture the Responsibility?

Bad Model Example:

Why Are They Undesirable? 🤔

3. Avoid Misleading/Imprecise Names

Example 1: Dialog vs Modal

Example 2: Consent vs Agreement

4. Avoid Using Verbs in Model Names

Avoid:

Better:

5. Avoid Using Vague or Overly General Names

Avoid:

Better:

How to Name Model Methods

1. Naming Methods for Getting Data

2. Naming Methods for Updating Data

3. Naming Methods That Return Boolean Values

4. Avoiding Implementation Details in Method Names

5. Clearly Differentiating Between Queries and Commands

6. Handling Plurality Correctly

Wrapping Up:

When Controllers Take on Too Much Responsibility

Why Do Controllers Take on Too Much Responsibility?

What Happens When Controllers Take on Too Much?

Example: Product Listing

More "Maintainable" Solution

💡Why This Works

Conclusion

Big Picture: Practical Steps for Upgrading the Ruby on Rails Version in a Small to Medium-Sized App 🚀

Step 0: Have a Degradation Test Ready

Step 1: Read the Official Migration Guide

Step 2: Fix Deprecation Warnings

Step 3: Update Gems

Step 4 : Update gem rails version

Step 5 : Run rails app:update

Step 6 : Update Existing Code

Step 7: Test, Test, Test 😎

1. Run Your Automated Test Suite

2. Conduct Manual Testing

3. Test in a Staging Environment

4. Plan for Post-Deployment Testing

Wrapping up

Demystifying Rails load_defaults: Mastering Configuration Updates

What is config.load_defaults?

But, why does config.load_defaults exit?

What is new_framework_defaults_x_y.rb?

What if You Can’t Update to a New Setting?

Wrapping Up

Rails and Ruby Deprecation Warnings: Why You Should Care and How to Fix Them

TL;DR

Why Should You Care About Deprecation Warnings?

When Deprecation Warnings Actually Matter?

Where Do We Find Deprecation Warnings?

1. Development Environment Console

2. Test Suite Output

3. Rails Logs

4. Rails Console

5. CI/CD Pipelines

How do we mange deprecation warning?

1. Deprecation Warnings in Rails

Managing Deprecation Warnings in Ruby

Wrapping up

How to use gem omniauth and omniauth-oauth2 to implement SSO for multiple customers

Wrapping Up

Practical Steps: How to Strategically Update Your Ruby Gems

Steps to update gems

What to Do When You Encounter a Dependency Conflict

Understand the cause

So what action should I take?

Step 5 : Run `rails app:update`