Forem: Planet Argon

When Reporting Quietly Becomes the Slowest Part of your Rails app

Autumn — Wed, 18 Mar 2026 23:08:17 +0000

Reporting rarely shows up as a problem on day one.

It usually starts with something small and useful. You set up a dashboard, a few queries, and maybe a quick way to answer a question that used to take too long.

This seems to work fine, so it gets left alone.

Then the app grows.

With more data, more questions, expanded filters, and more metrics, this process begins to carry more weight than it was designed for.

At some point, it stops feeling simple.

We start to see reporting become one of the slowest, most complex parts of an otherwise healthy Rails application.

The pattern we keep running into

What’s interesting is that this doesn’t happen because of one bad decision. It’s usually a series of reasonable ones.

A query gets a little more complex. Then another layer gets added. Active Record turns into raw SQL. Indexes are introduced to keep things fast. Views are added to organize the logic.

Each step makes sense on its own, right?

But over time, the system becomes harder to understand, slower to run, and more difficult to change. Upgrades get riskier, and even small changes start to feel expensive.

Teams often try to fix this by adding more indexes or introducing views, but they don’t make queries faster. Materialized views can work for smaller datasets, but become costly to refresh as things grow

None of these approaches are wrong. They just don’t always address the root of the problem.

A shift in how we approach reporting

Instead of continuing to optimize increasingly complex queries, we step back.

Most reporting is time-based: Days. Weeks. Months.

That gives us a clue.

Rather than calculating everything on the fly, we look for the smallest useful unit of data. Often that’s a day. Sometimes it’s something else. But there’s usually a clear base unit underneath the complexity.

Once you find that, you can start shaping the data in advance rather than rebuilding it on every request.

What tends to work better in practice

From here, a few patterns make reporting systems much easier to work with as they grow.

We create tables that are designed specifically for reporting, storing only the data needed to answer those questions. Instead of querying across many tables with complex joins, we aim to keep reporting queries focused and predictable.

We move heavy data processing out of request time, so user-facing performance doesn’t compete with reporting workloads. In some cases, this means using a follower database or a separate process to prepare reporting data in the background.

And we accept a small tradeoff: not everything needs to be real-time. In many cases, slightly delayed but fast and reliable reporting is a much better experience than slow, live queries.

We’re walking through this LIVE

We’ve been seeing this pattern often enough in client work that we decided to put together a short session to walk through how we approach it.

If reporting has started to feel heavier than it should, you’re welcome to join us.

Join the session

Ruby 4.0 and Ruby Box: What Changed and How to Upgrade Safely

Autumn — Wed, 04 Feb 2026 17:04:47 +0000

Ruby 4.0 dropped over the holidays, bringing us all new primitives for isolation, parallelism, and performance, as well as upgrade anxiety (inevitable) and the perpetual temptation to just rewrite our entire app (resist!). Let’s dive in!

Ruby Box: Isolation without abandoning Ruby’s flexibility

Ruby Box introduces a way to evaluate code inside an isolated environment. This means constants, classes, and monkey patches defined in a box do not leak out unless you explicitly expose them.

At a high level, Ruby Box is a formal mechanism for scoping global state.

Basic example

box = RubyBox.new

box.eval do
  class User
    def role
      :admin
    end
  end
end

defined?(User)
# => nil

Outside the box, User does not exist.

Selectively exposing behavior

box = RubyBox.new

user_class = box.eval do
  class User
    def role
      :admin
    end

    self
  end
end

user = user_class.new
user.role
# => :admin

Why this matters in real applications

In legacy Rails apps, global state is often the hidden cost of change. Monkey patches, initializer side effects, and gem overrides accumulate quietly as tech debt over the years. Ruby Box gives us a new way to:

Run isolated test scenarios without polluting the global runtime
Experiment with alternative implementations safely
Evaluate upgrades to dependencies without forking the app

This is particularly relevant when incrementally modernizing older systems, which is exactly where we see the most rewrite pressure among new (and sometimes existing!) Planet Argon clients.

ZJIT: A new foundation for Ruby performance

RUBYOPT="--zjit" ruby app.rb

Ruby 4.0 introduces ZJIT, a next-generation JIT compiler designed to be more maintainable and extensible than previous implementations.

ZJIT is not yet a universal replacement for YJIT, but it establishes a clear direction. Because it’s a work in progress, it's not enabled by default just yet. Here is a quote from the release notes. “ZJIT is faster than the interpreter, but not yet as fast as YJIT. We encourage you to experiment with ZJIT, but maybe hold off on deploying it in production for now. Stay tuned for Ruby 4.1 ZJIT.”

Enabling ZJIT

What changes in practice

You do not write Ruby differently to use ZJIT. The benefit is structural, not syntactic. ZJIT introduces:

A cleaner internal compiler architecture
Larger compilation units
A path to future optimizations that do not require rewriting Ruby code

For teams running mature applications, this matters because it provides immediate and actual performance in runtime evolution instead of theoretical gains that could maybe possibly potentially come with a risky application rewrite.

Ractors: Continued progress toward true parallelism

Ractors were introduced in Ruby 3.0. Ruby 4.0 refines the model and reduces internal contention, making parallel execution more practical.

Basic Ractor usage

r = Ractor.new do
  "Hello from another core"
end

r.take
# => "Hello from another core"

Structured communication with Ractor::Port

port = Ractor::Port.new

producer = Ractor.new(port) do |p|
  p.send("work item")
end

consumer = Ractor.new(port) do |p|
  p.receive
end

consumer.take
# => "work item"

Why this matters for Rails applications

Most Rails apps today rely on process-level concurrency. Ruby 4.0 continues the slow but intentional shift toward safer parallel execution within a single process.

That unlocks future architectural options without forcing a move to an entirely different stack or runtime.

Core language and standard library improvements

Ruby 4.0 also includes a collection of smaller improvements that add up over time.

Improved conditionals

if foo
  && bar
  || baz
  do_work
end

Ruby 4.0 improves parsing and readability in complex multi-line expressions, reducing subtle bugs in legacy conditionals.

Array enhancements

[1, 2, 3, 4].rfind(&:even?)
# => 4

Small additions like this reduce custom utility code that often proliferates in older codebases.

Better error context

Ruby 4.0 enhances error messages by showing both caller and callee context, making it easier to debug layered systems.

def a
  b
end

def b
  raise "boom"
end

a

The resulting stack trace now surfaces more actionable information, which is especially valuable in large applications with deep call chains.

Why We’re Excited about 4.0

At Planet Argon, most of our Ruby work starts with systems that have a history, are in full use by a large customer base, and can’t afford a risky, drawn-out rewrite.

Ruby 4.0 reinforces a belief we have held for years:

You do not need to rewrite your application to modernize it.

We’ll be using the new 4.0 features to:

Help isolate risk (Box)
Help performance evolve independently of application code (ZJIT)
Get better concurrency out of Ruby apps (Ractors)
Reduce friction in our everyday maintenance work

And how about that! None of these requires throwing away working software. :)

Upgrade strategy: How we recommend teams approach Ruby 4.0

Upgrading to Ruby 4.0 should be treated as an engineering initiative, not a version bump.

Here is the strategy we typically recommend.

1. Establish a behavioral baseline

Before upgrading, ensure you have:

A reliable test suite
CI visibility into failures
Basic performance benchmarks

This is not about perfection. It is about confidence.

2. Upgrade Ruby before Rails

Move the Ruby version forward first while holding Rails constant where possible. This isolates runtime changes from framework changes, making failures easier to reason about.

3. Use Ruby Box experimentally

Do not start by restructuring your application. Use Ruby Box in test or tooling contexts first:

Isolated test execution
Dependency experiments
Refactoring spikes

Treat it as a safety tool, not a refactor mandate.

4. Measure, then enable JIT options

Evaluate YJIT and ZJIT in staging or production-like environments. Measure memory, CPU, and latency. Choose deliberately.

Performance gains should be empirical, not assumed.

5. Avoid the rewrite trap

The biggest risk we see is teams using upgrades as justification for a rewrite. Ruby 4.0 explicitly reduces the need for that by improving the runtime itself.

Modernization works best when it is incremental, observable, and reversible.

Closing thoughts

Ruby 4.0 seems designed for giving long-lived systems room to keep evolving. For teams maintaining legacy Ruby and Rails applications, this release is a reminder that stability and progress are not opposites. With the right strategy, they actually reinforce each other!

This post was originally shared on [Planet Argon's blog](https://blog.planetargon.com/blog.

How to Demo Your Application to a New Development Team

Autumn — Thu, 14 Aug 2025 19:00:23 +0000

When you start working with a new development team, one of the first and most valuable things you can do is walk them through your application. It's more than just clicking around—it's about sharing the story of your app: what it does, who it serves, and how it's built.

We’ve seen a lot of client-led demos, and we’ve learned what makes them effective—and what leaves teams guessing. This post outlines a simple framework for walking a development team through your application. It includes key talking points to help you deliver a clear and helpful overview that saves time and builds shared understanding from the start.

We’ll cover:

How to introduce your business and users.
What technical details are most beneficial to share early on.
What’s changed in your app recently—and what’s coming up.
How to prepare the team for emergencies and escalations.
What kind of support you need from the dev team week-to-week.

By the end, you’ll have a helpful checklist for your next application walkthrough.

1. Start with the Big Picture: Your Business and Your Users

As the new team onboards to your application, it will be important to highlight the technical aspects of what the application does. However, something people often miss when demonstrating to a new team is explaining the why behind the application.

What business purpose does your app serve?
Who are your users?
What problems does it solve for them?
How do you interact with those users?

Start from the 30,000-foot view:

→ “Our users are [x] who want a way to [y].”

Then, take on the personality of a daily user:

→ “So if I want to get [y] from the app, I would log in and navigate to [critical page #1] or [critical page #2].”

Finally, show how your team engages with those users:

→ “As a customer service representative, we can pick up a user’s case and [do x] or [do y].”

This context helps the engineering team understand why they’re building and supporting the product, making it easier to navigate the app with purpose instead of aimlessly clicking around.

2. What Does the Application Do?

After covering what the application looks like for users and administrators, it is time to move over to the more technical functions of its structure. A senior engineer, CTO, or technical project manager would best lead this section of the demonstration.

Here, we should aim to answer questions like:

Where is the application hosted?
Is there up-to-date documentation on how to set up the application?
Are there important services that the onboarding team needs to be aware of (like Sidekiq Pro or AppSignal)?

Here are a few key areas to touch on:

Hosting and setup:

→ “When we have a new engineer starting, the first thing we ensure they have access to is [x].”

Application history:

→ “This started as a basic [code framework] app but has since expanded to include [other frameworks/tools].”

Important services:

→ “We use Sidekiq Pro for background jobs and AppSignal for monitoring.”

Known quirks or exceptions:

→ “An important thing that may not be super clear in the documentation is [x], which exists for [y purpose].”

Build process:

→ “When a change is ready, the testing suite runs and then [x] happens.”

These insights give the onboarding team a strong technical foundation to begin working efficiently.

3. Where Does the Application Stand Today?

After giving the team an idea of what the business does and how the application is set up, it’s time to get into the current state. This section aims to give the team a healthy understanding of what new features have been implemented recently, any ongoing issues, and cover important things to be aware of for future work.

What’s new:

→ “In the last three months, we added a new way for users to [x].”

What’s wrong:

→ “We’ve been having issues with [x] and [y], which we [have/haven’t resolved yet].”

What’s bothering you:

→ “It hasn’t happened in a while, but every few months, I worry about [x].”

What’s coming:

→ “In the next two months, the Ops team would like to see [x] happen.”

This helps the team prioritize their focus areas and understand where they can add the most value.

4. Preparing the team for emergencies

Emergencies are never fun, but they happen. Use this part of the demo to walk the team through what to do when something goes wrong.

What do you do when things go poorly?
Where do you look if there is an outage?
How have outages historically escalated to the engineers?
Have there been recurring themes in the recent outages?

How escalations happen:

→ “Historically, [x person/people] are the first to tell us when something is wrong.”

Where to look:

→ “When we get a report, we start by checking [x]. That usually tells us [y].”

Recovery process:

→ “If we need to rollback to a previous version of the app or database, here’s how we typically do that.”

Sharing your existing process gives your new team a sense of confidence and preparedness for when things break.

5. Helping Teams Help You

Finally, wrap up your demo by discussing what a successful working relationship looks like. Be clear about how you like to work, how you prefer to get updates, and what you expect from your dev partners.

For more on how to build collaborative and inclusive developer relationships from day one, check out this episode of Maintainable Software Podcast with April Wensel, where she shares thoughtful insights on navigating legacy code with empathy and intention.

Cadence:

→ “Every Tuesday morning, our operations team meets to review priorities and plan the next few weeks. I need updates on [x] and any [y] incidents before that meeting.”

Preferred processes:

→ “It’s easiest for me if updates are made in [x-way].”

Escalation protocols:

→ “If there’s a new incident or outage, I’m responsible for notifying [x-people]. For that, I need to know [y] and [z].”

Making it happen 🚀

Demos don’t have to be polished or perfect, but they do need to be intentional. A clear, thoughtful walkthrough of your application helps your new engineering team get up to speed faster, make fewer assumptions, and deliver better work sooner.

The more context you give, the more your development partners can support your business goals effectively.

How to Demo Your Application to a New Development Team: A Helpful Guide

Autumn — Wed, 30 Jul 2025 18:42:36 +0000

We’ll cover:

How to introduce your business and users.
What technical details are most beneficial to share early on.
What’s changed in your app recently—and what’s coming up.
How to prepare the team for emergencies and escalations.
What kind of support you need from the dev team week-to-week.

By the end, you’ll have a helpful checklist for your next application walkthrough.

1. Start with the Big Picture: Your Business and Your Users

What business purpose does your app serve?
Who are your users?
What problems does it solve for them?
How do you interact with those users?

Start from the 30,000-foot view:

→ “Our users are [x] who want a way to [y].”

Then, take on the personality of a daily user:

→ “So if I want to get [y] from the app, I would log in and navigate to [critical page #1] or [critical page #2].”

Finally, show how your team engages with those users:

→ “As a customer service representative, we can pick up a user’s case and [do x] or [do y].”

This context helps the engineering team understand why they’re building and supporting the product, making it easier to navigate the app with purpose instead of aimlessly clicking around.

2. What Does the Application Do?

Here, we should aim to answer questions like:

Where is the application hosted?
Is there up-to-date documentation on how to set up the application?
Are there important services that the onboarding team needs to be aware of (like Sidekiq Pro or AppSignal)?

Here are a few key areas to touch on:

Hosting and setup:

→ “When we have a new engineer starting, the first thing we ensure they have access to is [x].”

Application history:

→ “This started as a basic [code framework] app but has since expanded to include [other frameworks/tools].”

Important services:

→ “We use Sidekiq Pro for background jobs and AppSignal for monitoring.”

Known quirks or exceptions:

→ “An important thing that may not be super clear in the documentation is [x], which exists for [y purpose].”

Build process:

→ “When a change is ready, the testing suite runs and then [x] happens.”

These insights give the onboarding team a strong technical foundation to begin working efficiently.

3. Where Does the Application Stand Today?

What’s new:

→ “In the last three months, we added a new way for users to [x].”

What’s wrong:

→ “We’ve been having issues with [x] and [y], which we [have/haven’t resolved yet].”

What’s bothering you:

→ “It hasn’t happened in a while, but every few months, I worry about [x].”

What’s coming:

→ “In the next two months, the Ops team would like to see [x] happen.”

This helps the team prioritize their focus areas and understand where they can add the most value.

4. Preparing the team for emergencies

Emergencies are never fun, but they happen. Use this part of the demo to walk the team through what to do when something goes wrong.

What do you do when things go poorly?
Where do you look if there is an outage?
How have outages historically escalated to the engineers?
Have there been recurring themes in the recent outages?

How escalations happen:

→ “Historically, [x person/people] are the first to tell us when something is wrong.”

Where to look:

→ “When we get a report, we start by checking [x]. That usually tells us [y].”

Recovery process:

→ “If we need to rollback to a previous version of the app or database, here’s how we typically do that.”

Sharing your existing process gives your new team a sense of confidence and preparedness for when things break.

5. Helping Teams Help You

Cadence:

→ “Every Tuesday morning, our operations team meets to review priorities and plan the next few weeks. I need updates on [x] and any [y] incidents before that meeting.”

Preferred processes:

→ “It’s easiest for me if updates are made in [x-way].”

Escalation protocols:

→ “If there’s a new incident or outage, I’m responsible for notifying [x-people]. For that, I need to know [y] and [z].”

Making it happen 🚀

The more context you give, the more your development partners can support your business goals effectively.

Deploying a Ruby on Rails app to DigitalOcean Using Kamal

Autumn — Thu, 24 Jul 2025 00:11:37 +0000

If you’re deploying Ruby on Rails applications to the cloud, you may have explored tools to simplify and streamline the process. Recently, we’ve been experimenting with Kamal, a tool for deploying containerized applications, and we’re excited to share our experience with deploying a Rails app to DigitalOcean using their Managed Database service.

This post introduces Kamal, explains why it’s worth exploring, and walks you through a sample deployment configuration to demystify Kamal and help you decide if it’s the right tool for your next project.

What Is Kamal?

Here's how the official Kamal documentation describes it:

Kamal offers zero-downtime deploys, rolling restarts, asset bridging, remote builds, accessory service management, and everything else you need to deploy and manage your web app in production with Docker. Originally built for Rails apps, Kamal will work with any type of web app that can be containerized.”

In simpler terms, Kamal is a deployment tool designed for containerized applications. Whether you’re managing Rails apps or other containerized projects, Kamal handles complex tasks like asset management, remote builds, and service orchestration. It provides powerful features for those looking to avoid the overhead of Kubernetes while still leveraging Docker-based workflows.

The Case for Kamal: Why It’s Worth Exploring

You may have heard Kamal described as a "Capistrano-like tool for containerized apps." While that description is somewhat accurate, Kamal is much more than that. It stands out for developers who:

Want a simpler alternative to Capistrano.
Are focused on lightweight deployment workflows.
Appreciate a tool that integrates deeply with Rails (but also supports other frameworks).

Kamal offers several unique advantages, making it a compelling choice for deploying containerized applications.

Optimized for Rails

Kamal was initially built with Ruby on Rails in mind, offering built-in support for Rails conventions. But it’s versatile enough to work with any containerized web app, making it a great fit for diverse tech stacks.

Rails 8 Integration

Kamal is tightly integrated with Rails 8, coming pre-installed and leveraging new features like simplified containerization out of the box. This reduces setup time and ensures compatibility with the latest Rails conventions.

Streamlined Asset Management

Kamal automates asset bridging between deployment versions, ensuring static files like CSS and JavaScript are handled seamlessly without downtime. This eliminates the manual asset precompilation headaches often encountered in traditional workflows.

Easy Environment Management

With Kamal, environment variables and secrets are centralized in .kamal/secrets, simplifying managing production settings across servers. This reduces configuration drift and enhances security by keeping sensitive data out of version control.

A Modern Alternative to Capistrano

Kamal modernizes deployment by replacing Capistrano’s script-based approach with a Docker-centric workflow, offering better scalability and consistency. It’s easier to set up for containerized apps while retaining the simplicity Capistrano users love.

Flexible Support for Managed Databases

Kamal integrates effortlessly with managed database services like DigitalOcean’s, allowing you to configure database connections via environment variables without managing database containers. This flexibility simplifies infrastructure while leveraging cloud provider reliability.

Ideal for Small Teams or Solo Devs

Kamal’s lightweight design and minimal setup make it perfect for small teams or solo developers who need efficient deployments without the complexity of Kubernetes. It balances power and simplicity, reducing the learning curve for resource-constrained projects.

Developer-Friendly Debugging Tools

Kamal provides commands that give developers quick access to runtime diagnostics and interactive troubleshooting. These tools streamline issue resolution without requiring external monitoring setups.

Active Community and Documentation

Kamal benefits from a growing community on GitHub and comprehensive official documentation, offering quick support and detailed guides for both beginners and advanced users. This ecosystem ensures you’re never stuck when exploring its features.

Why We Chose a Managed Database Instead of a Database Container

Choosing a managed database service was a deliberate decision that has made our deployment process much simpler and more efficient. With DigitalOcean’s managed database service, many of the operational headaches of managing a database—like backups, scaling, and connection management—are handled automatically. This not only saves time but also ensures that the service provider professionally manages critical tasks like disaster recovery and high availability.

Managed databases also remove the need to configure and maintain database containers, which can be tricky to set up correctly, especially for production environments. Instead of worrying about things like replication, version upgrades, and performance tuning, you can focus entirely on building and improving your application. This approach is a game-changer for small-to-medium apps, where development resources might be limited. It allows developers to deploy confidently, knowing that the database infrastructure is reliable, scalable, and secure.

In our case, DigitalOcean’s managed database service was particularly appealing because of its seamless integration with other DigitalOcean products, intuitive user interface, and competitive pricing. Setting up the database was straightforward, and connecting it to the Rails app required only minor adjustments to configuration files. This simplicity made it easy to get the app up and running quickly, without spending hours on infrastructure setup.

If you're deploying small or medium-sized apps or new to cloud deployments, managed databases are worth considering. They offer a balance of simplicity and robustness that’s hard to achieve with self-managed solutions.

Getting Started with Kamal - Tips, Tools, and Insider Know-How

Kamal is designed to make deployments simple and efficient, but setting up a new tool can always feel a little daunting. Here’s how to get started with Kamal and some helpful tips to make the process smoother.

Prepare Your Environment

Before diving in, ensure you have the following tools and concepts ready:

Docker Installed and Configured: Kamal relies on Docker to build and run containers, so install Docker and familiarize yourself with basics like creating a Dockerfile and running containers. Test it locally with docker run hello-world to confirm it’s working.
SSH Access to Your Server: Kamal uses SSHKit to communicate with your server, so set up SSH keys and verify access with ssh user@your-server-ip. Passwordless login via keys is recommended for automation.
A Cloud Service Provider: Decide where you’ll host your app. Kamal works seamlessly with AWS, Google Cloud Platform, DigitalOcean, and more.
A Deployed App or Sample Rails App: To experiment with Kamal, it helps to have a simple Rails app ready to deploy.

Install Kamal

If you’re using Ruby on Rails 8, Kamal comes pre-installed in your app. For older versions or other frameworks:

Add Kamal to your Gemfile: gem 'kamal'
Run bundle install to install the gem.
Initialize Kamal with: kamal init

This generates config/deploy.yml (your deployment blueprint) and .kamal/secrets (for sensitive data). Add .kamal/ to .gitignore to keep secrets out of version control.

Configure Your `deploy.yml` File

The deploy.yml file defines how Kamal deploys your app. Here’s a starter example for a Rails app on DigitalOcean with a managed database:

service: my-app
image: username/my-app:1.0.0
servers:
  web:
    - 192.168.1.100  # Replace with your server IP
env:
  secret:
    - RAILS_MASTER_KEY
    - PRODUCTION_DB_HOST
registry:
  username: username
  password:
    - KAMAL_REGISTRY_PASSWORD

To connect your Rails app to a managed database like DigitalOcean’s, grab the host, username, and password from your provider’s dashboard, store them in .kamal/secrets, and reference them in deploy.yml under env.secret.

Pro Tips:

Service Name: Match it to your app’s repository name (e.g., my-app) for consistency.
Image Tagging: Use specific versions (e.g., 1.0.0) instead of the latest for easier rollbacks.
Secrets: Store sensitive values like RAILS_MASTER_KEY and PRODUCTION_DB_HOST in .kamal/secrets, not the YAML file.
Roles: Add workers: under servers if using background jobs (e.g., Sidekiq).

Understand the Deployment Workflow

Kamal uses a simple yet powerful workflow for deployments:

Build the Docker Image: Kamal builds your app’s image locally or remotely (configurable in deploy.yml).
Push to a Registry: Upload the image to DockerHub or another registry specified in the registry section.
Deploy: Run: kamal deploy

This pulls the image to your server, starts containers, and performs a rolling restart for zero downtime. If using accessories (e.g., Redis), they’re deployed automatically—no separate accessories flag is needed unless isolating specific updates.

Master Kamal’s Debugging Tools

Kamal includes several built-in commands to simplify debugging:

Logs: View real-time output with:

kamal logs -f

Rails Console: Debug interactively on the server:

kamal app exec --interactive "bin/rails console"

Shell Access: Inspect the container directly:

kamal app exec --interactive bash

Work with Accessories

For services like Redis or Sidekiq, define them as accessories in deploy.yml:

accessories:
  redis:
    image: redis:latest
    host: 192.168.1.100
    port: 6379

Deploy with Kamal deploy, and Kamal manages them alongside your app. Add volumes or environment variables as needed for persistence or configuration.

Example Configuration for Deploying with Kamal

Here’s the deploy.yml for a Rails app on DigitalOcean with their managed database:

service: my-rails-app
image: myusername/my-rails-app:1.0.0
servers:
  web:
    - your-droplet-ip  # From DigitalOcean dashboard
env:
  secret:
    - RAILS_MASTER_KEY
    - PRODUCTION_DB_HOST
registry:
  username: myusername
  password:
    - KAMAL_REGISTRY_PASSWORD
accessories:
  redis:
    image: redis:latest
    host: your-droplet-ip
    port: 6379

Kamal's Community and Documentation

Using a new tool can be much easier with a strong community and resources at your fingertips. Kamal offers both, making learning, troubleshooting, and exploring advanced features simple. Whether you are looking for quick answers, detailed guidance, or inspiration from other developers, tapping into Kamal’s community and documentation will accelerate your journey to mastering this powerful deployment tool.

Visit the Kamal GitHub repository to connect with other users and get quick support.
Explore the official Kamal documentation for advanced features, like load balancing and remote builds.
Follow developers sharing tips on GitHub or blogs (like this one!).

Ready to give Kamal a try?

Explore Kamal's features, or experiment with a simple app to see how it fits your workflow. Whether managing small apps or planning larger deployments, tools like Kamal and managed databases can save you time and effort. Take the first step by trying it out on your next project—you might just discover your new favorite deployment tool! You might even want to check out the Maintainable Podcast episode 'Martin Emde – Ruby Central and the Art of Being Tolerant to Change', where Martin shares insights on effectively managing changes and complexity in Ruby applications.

Linear and Jira: Making the Right Call for Your Team’s Workflow

Autumn — Wed, 09 Jul 2025 17:12:56 +0000

When it comes to project management tools, the choice between Linear and Jira isn't just about features—it's about how your team works best. Do you need a lightweight, developer-friendly experience or a platform capable of handling complex workflows and extensive reporting? Understanding the nuances of each tool can help ensure your team stays productive and efficient. Let's explore the key differences, real-world applications, and how to determine which one aligns best with your organization's needs.

Understanding Your Organization's Needs

Size and Structure Matter

Your organization's size and structure are important factors when deciding between Linear and Jira. Are you a lean startup with a flat hierarchy? Or are you a large corporation with layers of middle management and a matrix structure?

Linear excels in simplicity and minimalism, making it an excellent choice for smaller teams or companies with streamlined decision-making.
Jira, on the other hand, offers customization and reporting capabilities, ideal for large organizations with complex workflows and multiple stakeholders.

Who Needs Access?

Another consideration is who will use the tool and how. For example:

Linear is designed with developers in mind. Its Slack integrations, team-managed projects, and focus on triage make it perfect for teams prioritizing speed and collaboration.
Jira is better suited for organizations where transparency and accountability extend to many layers, from operations to engineering managers and beyond.

Insights from Real-World Use Cases

Linear in Action

Michael Kurt, our Project Manager, shared how Linear’s features can simplify workflows:

Using Linear's Triage and Slack integrations, teams can easily manage incoming tasks and stay updated. The system encourages thoughtful comments and careful communication by connecting Linear comments to Slack tags, making collaboration seamless."

Linear also allows team-specific setups, where each product team operates independently without overlapping tickets. This compartmentalization can reduce noise and foster focused collaboration.

Jira’s Strengths

For larger corporations, Jira's robust capabilities shine. As Michael observed:

For companies with a structure like Operations > Product Manager > Project Manager > Engineering Manager > Pod Lead, Jira's extensive customization options ensure everyone's needs are met. However, it can become overwhelming if too many layers are involved in ticket management."

Jira's detailed reporting and dashboard features make it a favorite for organizations that need to monitor progress across multiple teams and departments.

Key Questions to Ask

What Are Your Growth Goals?

If your company is scaling rapidly, consider the future:

Will adding more layers to your structure require a tool with broader reporting capabilities?
Do you prioritize lightweight tools to maintain agility as you grow?

How Much Transparency Do You Need?

Both tools offer transparency, but in different ways:

Linear's Slack integration keeps communication tight within teams.
Jira's dashboards and reports are ideal for sharing progress with external stakeholders and leadership.

The Verdict: Linear or Jira?

There's no one-size-fits-all answer, but here's a quick summary:

Factor	Linear	Jira
Team Size	Small to mid-sized teams	Large, complex organizations
Hierarchy	Flat or minimal layers	Matrix or multi-layered structures
Transparency Needs	Team-level visibility	Organization-wide reporting
Ease of Use	Simple and intuitive	Robust but can be overwhelming
Integrations	Excellent Slack integration	Wide range of integrations

Still Undecided? Test Both

Both Linear and Jira offer trial periods. Engage your team and run a pilot project with each tool. Pay attention to ease of onboarding, user adoption, and how well each tool supports your workflows.

Choosing between Linear and Jira requires understanding your organization's size, structure, and goals. Whether you aim for efficiency or comprehensive control, the right tool can help your teams do their best work. Take the time to evaluate your needs—your future self (and your team) will thank you.

Hotwire for Rails Developers: Keeping UI Fast and Maintainable

Autumn — Thu, 22 May 2025 16:11:15 +0000

The Challenge of Modern Frontend in Rails

Rails developers often face a dilemma: Should they stick with built-in Rails tools or go all-in on React for interactivity? The rise of JavaScript-heavy apps has made Rails projects harder to maintain. Many teams feel forced to separate the frontend and backend, leading to extra complexity, API management, and more dependencies to manage. While React is powerful, it often adds more overhead than necessary for traditional Rails apps.

But what if you could build a modern, dynamic UI without the extra complexity?

Enter Hotwire – A Rails-native alternative

Hotwire embraces the power of server-rendered HTML while still delivering a fast, interactive user experience. Instead of shifting everything to the frontend, it keeps Rails at the core and handles interactivity in a way that feels natural to the framework.

With Hotwire, you don’t need to set up a separate API, manage client-side state, or keep up with endless JavaScript updates. You get the best of both worlds—modern UI interactions without the React overhead.

What is Hotwire? A Rails Developer’s Perspective

Hotwire is a framework that brings modern UI interactivity to Rails without the complexity of a full JavaScript frontend. It keeps things simple by relying on server-rendered updates instead of pushing everything to the client.

At its core, Hotwire = Turbo + Stimulus:

Turbo – Handles fast page loads, real-time updates, and partial page changes without writing custom JavaScript. This means forms, lists, and UI interactions feel instant without managing the frontend state.
Stimulus – A small JavaScript framework that adds enhancements where needed. Unlike React, it doesn’t take over the UI—it simply connects behavior to existing HTML elements.

Why Hotwire Fits Rails So Well

Rails has always been about "convention over configuration." Instead of forcing developers to make endless decisions about frontend architecture, Hotwire follows Rails’ principles:

It works out of the box with Rails' existing tools.
It keeps backend logic in Rails instead of spreading it across multiple layers.
It reduces unnecessary complexity by avoiding heavy JavaScript frameworks.

With Hotwire, you don’t need to rework how your app is built—you just extend Rails' strengths to create a fast, interactive UI with minimal effort.

When to Use Hotwire Instead of React

There are many cases where React is overkill in a Rails app. If you don’t need a full-blown single-page application (SPA), React might be adding more complexity than value.

When React is Overkill

Your app isn’t an SPA, but it still has some interactive elements.
You’re using React for only a few small features (modals, forms, or UI updates).
You’re dealing with long build times, slow initial page loads, or performance issues caused by client-side rendering.

When Hotwire Shines

You want to keep your app fully within Rails without adding a separate frontend framework.
You need real-time updates but don’t want to set up WebSockets manually.
You prefer less JavaScript and more of Rails' simplicity.

Hotwire is a great choice for those who want modern UI features without the complexity of a JavaScript-heavy setup. It lets you build fast, interactive apps while keeping your Rails app clean and maintainable.

Hotwire in Action: How We Use it at Planet Argon

In our recent project for Olsson Roofing, we built a mobile-first web application for field maintenance workers. Instead of using React as we typically would, we embraced Hotwire—Rails' modern approach to building responsive web applications without writing much JavaScript.

Turbo Streams for Form Steps

One of our main uses of Hotwire was implementing a multi-step form process for roof inspections. We used Turbo Streams to navigate different form sections without full page reloads. When users submit a form step, the controller responds with a Turbo Stream that updates just the form content:

The form partial is structured to work with these Turbo Stream updates:

This approach allowed us to:

Keep each form step isolated and maintainable
Provide instant feedback when moving between steps
Maintain a smooth user experience on mobile devices with slower connections
Handle form validation errors without losing context

Stimulus for Enhanced Interactivity

While Turbo handled most of our needs, we used Stimulus for client-side interactions that required JavaScript. Looking at our views, we can see how we connected Stimulus controllers:

This data-controller="form" attribute connects to our form controller that handles image previews:

The controller is automatically loaded thanks to our Stimulus configuration in app/javascript/controllers/index.js:

What We Learned

The Good

Productivity Boost: Hotwire allowed us to build interactive features with significantly less code than a React-based approach.
Performance: Thanks to Turbo's smart HTML streaming, the app feels snappy even on slower mobile connections.

The Challenging

Mental Model Shift: Coming from React, it took time to shift our thinking from client-side state management to server-side HTML updates.
Debugging: Initially, debugging Turbo Frame and Stream issues was tricky since they operate differently from traditional AJAX requests.
Documentation: While Hotwire's documentation is good, finding solutions for edge cases sometimes required diving into source code or community discussions.

What We'd Do Differently

Frame Organization: We would better organize our Turbo Frames hierarchy. For example, we could have nested frames for related form sections to better manage state:

Stimulus Controllers: Instead of the somewhat monolithic form controller we ended up with, we would create more focused, reusable stimulus controllers.
Error Handling: We'd implement more robust error handling for Turbo requests, possibly with a dedicated error Stimulus controller:

FAQ’s and Resources

"Can Hotwire handle complex UIs?" → Yes, but it requires rethinking how you structure frontend logic.
"What about existing React components?" → Hybrid approach: Keep React where needed and transition the rest.
"Is it hard to learn?" → If you know Rails, you can pick up Hotwire fast—here are some of our favorite resources.
- Hotwired.dev
- Hotwire Native for Rails Developers by Joe Masilotti
- From React to Hotwire – An Unexpected Journey webinar from Arkency
- Hotwire for Rails Developers course by Pragmatic Studio
- Hotwire Spark: live reloading for Rails applications by 37 Signals

Key Takeaways

Our experience with Hotwire has been largely positive. While there was a learning curve, the benefits of simpler code, better performance, and enhanced reliability made it a great choice for this mobile-first application. The framework's approach to progressive enhancement particularly shined in our use case, where network connectivity couldn't be guaranteed.

We're excited to continue using Hotwire for future projects, applying the lessons we've learned to build even better applications. The framework's alignment with Rails' "convention over configuration" philosophy means we can focus more on solving business problems and less on technical implementation details.

Also! Listen to Joel Hawksley discuss how frontend complexity affects maintainability and why simplicity matters on Maintainable Podcast: The Hidden Costs of Frontend Complexity.

We Think You'll Also Enjoy Reading...

FAQ's

Q: "What are the limitations of Hotwire?"

A: Hotwire simplifies building interactive Rails applications but may fall short for extremely complex, state-heavy apps typically suited for full JavaScript frameworks like React or Vue. While great for most Rails projects, it may require additional custom JavaScript or third-party integrations to handle sophisticated frontend logic or highly interactive UI components.

Q: "Can I use Hotwire with existing Rails applications?"

A: Yes! Hotwire is designed to integrate seamlessly into existing Rails apps. You can incrementally adopt it by replacing specific UI components or interactions with Turbo and Stimulus without rewriting your entire frontend.

Q: "How does Hotwire handle complex interactions?"

A: Hotwire manages complex interactions using Turbo for seamless partial page updates and Stimulus for targeted JavaScript behavior. Together, they allow developers to handle rich, interactive experiences without heavy reliance on complex JavaScript frameworks, keeping your UI maintainable and performant.

This post was originally posted on the Planet Argon blog.

Rails Core AMA - Rails World 2023: Hosted by...me!

Robby Russell 🐘🚂 — Wed, 18 Oct 2023 11:43:45 +0000

As a contributing member of the Ruby on Rails Foundation, Planet Argon is delighted to collaborate with the Rails Foundation Core members and other contributing members to improve and maintain the future of the Rails community for all of us.

In a remote work world, getting together in person is challenging, so we can't pass it up when an opportunity arises!

Recently, I headed out to Amsterdam for Rails World 2023!

Besides listening to insightful keynote talks and connecting with new and seasoned Rails practitioners, I was invited to host the Rails Core AMA Panel. Ten current 12 Rails Core members sat down to answer questions submitted by the Rails World community in the days leading up to the event.

In case you missed it, here’s a replay of the panel discussion.

originally posted on blog.planetargon.com.

How To Find Top Ruby on Rails Engineers In This Market

Robby Russell 🐘🚂 — Thu, 10 Nov 2022 21:15:51 +0000

Planet Argon is piloting a new service to help match Ruby on Rails engineers in the community with organizations that are struggling with their recruitment efforts.

But first, some background.

In 2005, we became one of the first companies to hire several Ruby on Rails developers. It's true. For a brief period, we were one of the largest employers of Rubyists, and these were some incredibly skilled individuals.

Several early-on employees went on to start and work at exciting startups. One of our first Office Managers took on the first non-technical role at a startup called GitHub. Other alums went onto places like GitHub, EngineYard, Kongregate, Amazon Web Services, and Stripe to name a few.

As a software consultancy, we've been able to recruit a lot of talented people across various skill levels. We've also inherited and worked on projects previously coded by hundreds of developers.

I also speak with a large number of organizations who are inquiring about our Team/Staff Augmentation services, which is essentially a "can we rent a few Planet Argon engineers for the next 3-6 months" conversation. Big-picture, these organizations would prefer to hire full-time employees, but for one reason or another, their recruitment efforts have been expensive, slow, and ineffective.

While our augmentation service is a healthy alternative, it feels more like a backup plan than a long-term solution.

When we partner up with them, we know, deep down, those organizations will replace us with their own hire… should they ever find the right person. Oftentimes, those organizations press ahead with their under-resourced team and cross their fingers that the right candidate will stumble across their job opening. 🤞

We send an email a month or three later asking, "Heya! Did you ever end up filling that role?" It's not uncommon to hear that they haven't filled it.

If that role was still available, periodically, I've shared those job ads with someone I know in the Ruby on Rails community who might be a good match. As a result, several developers have landed jobs and been happy and successful in their new roles. This made me curious to discover if there was an opportunity to do more with recruiting services.

Before RailsConf 2022, the idea of recruiting services came up again while our leadership team brainstormed new services Planet Argon could offer.

The previous year, we replaced several staff members who moved on to incredible opportunities that presented themselves during one of the busiest hiring sprees in the tech industry.

Jokingly, we said, "We've spent so much time recruiting Rails devs; maybe someone would pay us to do this for them, too?!" That’s when the lightbulb flipped on.

We know a lot of Ruby on Rails engineers. A lot of Ruby on Rails engineers know us.

We've been active contributors to the community since 2005.
We produce one of the top 10 podcasts in the community.
Every few years, we conduct the Rails community survey.
We created one of the most popular open-source projects (ohmyzsh) in the software industry.
We've hosted meetups, taken 60 Rubyists on hikes, even train trips across the United States.

Through all of these projects and experiences, we've established many relationships with people across the community.
During RailsConf 2022, I found myself reconnecting with people for the first time in a few years. Global pandemics can really shake things. Some engineers said they had found themselves in tricky situations.

For example, I spoke with a few people who had moved into management a few years ago, and it turns out they didn't love it. I asked if they considered stepping out of management and returning to an individual contributor role. Some of them said it was possibly an option, but most said they couldn't step down from their current team without feeling weird about it.

They'd need to find a new job elsewhere. But they weren't ready to cruise the job board sites, blast their resume everywhere, and wait for a callback.

Other engineers shared that they had been working at companies that broke their technology platform down into several different stacks, and they found themselves saying, "I honestly miss spending more of my day working in Ruby."

After the conference, I shared these stories with our leadership team. It really felt like we could help some of our Rubyist colleagues navigate these challenges.

We decided to take what we've learned from hiring Ruby on Rails engineers over the years and play matchmaker. We began vetting dozens of Rubyists who are (mostly) employed but curious should the right opportunity pop up.

As of this last month, we can now offer another option rather than saying "best of luck" to organizations contacting us for Team/Staff Augmentation who want to hire someone.

Our goal is twofold: to match skilled Ruby on Rails engineers with organizations where they can make an impact, stay engaged, and grow in their role; and to help organizations that are struggling to vet, hire, and retain experienced Ruby on Rails engineers.

Looking to Hire Ruby on Rails Developers? Learn more

Are you a Rails Developer seeking a new role? Learn more

Rails 6.1 is Coming Soon! How to Prepare Your App Now

Robby Russell 🐘🚂 — Mon, 07 Dec 2020 20:47:29 +0000

~~The next version of Ruby on Rails is currently being tested by the community and we anticipate a stable release in the next week.~~

Rails 6.1 is here! There are a number of memory optimizations, which should improve performance (aka speed!) of your Rails apps.

There are a number of new features, too. While there have been third-party libraries available for managing multiple databases, horizontal sharing, and switching connections on a per-database basis, it will be nice to now have this available for all applications.

Another nice feature coming to Rails will allow developers to enable a feature that will disable all eager loading of database associations. This will help us shut down those pesky N+1 queries.

I know that our team is thrilled to see that we'll be able to put an associated destroy call into background jobs.

Is your Rails app ready to update to 6.1?

Are you running on Rails 6.0.x? Yes, your application is ready for an upgrade.

If not, what version are you running?

Rails Version	Your Status	Latest Release
6.1.x-rc	🎉 You're on top of things!	Nov 2020
6.0.x	✅ Ready to upgrade	Oct 2020
5.2.x	⚠️ Almost Ready	Sept 2020
5.1.x	⚠️ Upgrade to 5.2.x ASAP!	March 2019
5.0.x	🚨🙀 OVERDUE for upgrade	March 2019
4.2.x	🚨😱💀 Bad situation	May 2020
4.1.x	🚨😱💀 Bad situation	July 2016
4.0.x	🚨😱💀 Bad situation	Jan 2015
3.2.x	🚨😱💀 Bad situation	Sept 2016

Why is everything prior to 5.1.x looking bad for you? Your application is no longer receiving security patches nor bug fixes from the Rails Core Team. (See the official Rails Security Policy)

We recommend that Ruby on Rails be upgraded one major/minor version at a time. For example, if you are running on 5.1 now, you need to upgrade to 5.2 next.

In an ideal world, your goal should be to get your application running on 6.0 by the end of 2021.

🤓 Read When Should You Upgrade Your Rails Application? to learn more about our rationale.

Wait, our developers think we should rewrite our application – do we still need to upgrade?

To be honest, we are not fans of big rewrites.

Our purpose at Planet Argon is to FIGHT THE BIG REWRITE. We even produce a podcast called Maintainable where we speak with experts in the industry on how to overcome the problems associated with technical debt and legacy code. We live and breathe this.

We understand the temptation to exclaim, "TIME FOR A REDO!" But we know, all-to-well, that rewrites are notoriously unsuccessful. If you need to maintain your existing app while building a new app, in parallel, you have a big task ahead of you. Furthermore, if you haven't established a cohesive process to keep that technology up-to-date, what makes you think you'll have better success with a different technology stack?

🤓 Read 3 Reasons Why You Shouldn’t Outsource Your Rails Upgrades to learn more.

Will our Rails upgrade hurt us?

Large companies like Shopify, Basecamp, and Github have been investing a lot of their Engineering time to contribute back to the core Rails framework. As a community, we are aiming to make sure that major/minor upgrades have limited breaking changes.

We're hoping that upgrades will continue to get easier than they were several years ago. Might that be one of the reasons why you're stuck where you're at? Did you navigate an expensive upgrade before?

Interested in a fresh set of eyes and a free action plan?

Get in touch so that we can help you explore a Rails 6 Upgrade.

This was originally posted on blog.planetargon.com

When Should You Upgrade Your Rails Application?

Robby Russell 🐘🚂 — Wed, 25 Nov 2020 00:43:12 +0000

A. Upgrade to the latest major/minor version each year, if you can.

As a general rule of thumb, Ruby on Rails has released a new version on nearly an annual basis. The core team has typically aligned these with the annual RailsConf so that there are new features and updates to demo in keynote talks.

This has consistently been the case for nearly each of the last 15 years...give or take a few.

I also understand that it can be a challenge for teams to plan and prioritize upgrades. I'll touch on that more later.

First, let's get down to brass tacks. We need to assess your situation.

What is the newest version of Rails?

The community is currently kicking the tires on Rails 6.1 release candidates.

Note: Due to COVID-19, the release cycle appears to have slowed down a touch.

What version is your app currently running on?

If your Rails application is not running on either 5.2.x or 6.0.x (or newer)...your application is at risk.

Rails Version	Status	Latest Patch
6.1.x	💚 Supported	Nov 2020
6.0.x	💚 Supported	Oct 2020
5.2.x	💚 Supported	Sept 2020
5.1.x	🚨 At Risk	March 2019
5.0.x	🚨 At Risk	March 2019
4.2.x	🚨 At Risk	May 2020
4.1.x	🚨 At Risk	July 2016
4.0.x	🚨 At Risk	Jan 2015
3.2.x	🚨 At Risk	Sept 2016

...you get the idea.

The older the version, the more at risk your application is.

Do you have multiple Ruby on Rails applications and want to have someone gather this information? We have a free google sheet template for you to document these details.

I encourage you to steal this template!

At risk of what, exactly?

Great question!

Like any software running on your laptop, smartphones... the software that we write to power our web application also has security vulnerabilities that are found. When these issues are found (usually by the good/friendly hackers who are kind enough to share what they discover), the Ruby on Rails Core Team will apply security patches and release a small update.

For example, if you are running on 5.2.9, they might release 5.2.10 to patch the security hole.
In theory, a developer on your team should be able to quickly bump up to the new version in the Gemfile with one line of code change, a run through your automated tests, and a deploy. ..and that known security hole is no longer a possible backdoor for the unfriendly hackers out there.

Note: this can be automated!

What about bug fixes?

The other benefit to staying up-to-date is that there are 🐛 bugs found within the underlying Ruby on Rails framework from time-to-time.

If they are critical enough bugs, the Rails team release will release a small patch for those.

Learn more about the official Ruby on Rails Maintenance Policy

What version are most Rails applications running on?

Every two years, Planet Argon surveys the Ruby on Rails developer community and shares our findings. This year, we have 2,049 members of the community share a number of details about their applications.

Based on the survey, ~62% of respondents said they were running on either 5.2.x or 6.x. (source)

Are you part of the other 38% that are running on an unsupported version?

How often should you update your version of Rails?

In an ideal world, your team would be aiming to stay up-to-date with Rails as new versions are released. But, we live in a world where each team has a wide range of priorities to juggle. Without a cohesive process to follow, teams will put upgrades into a someday/maybe list.

We understand why this happens.

Upgrades feel like a lot of work for little immediate payoff. However, this has a compound effect in that it results in making the upgrade path far more time consuming and risky to explore. As developers, we are risk-averse and product owners are worried about upgrades being drastically underestimated.

The reality is that some of the major version upgrades are far from trivial. Third-party dependencies tend to be a lot of the challenges that those upgrades need to navigate.

When everyone is afraid of breaking things in a working application – the decision gets delayed for another time, place, or even worse...left for future people added to your team to have to deal with.

As new engineers join your team and learn that keeping the applications up-to-date isn't part of your team's workflow, they will start to assume that it is not considered important within your company culture.

Note: Delayed upgrades can definitely impact your employee retention, too. When they aren't able to leverage newer features, libraries, and/or tools in Ruby on Rails, they may start to daydream about finding a new team where the grass may (or may not) be greener.

Regardless of how you spin it...this is problem. A problem that your team can (and needs to) solve!

Can't you just hire a professional to upgrade for you?

Yes! (...but I have written 3 Reasons Why You Shouldn't Outsource Your Rails Upgrades to explain my concerns about that as a long-term "solution").

Several companies have hired our team over the years to handle the underlying upgrade. We enjoy rolling up our sleeves and getting our hands dirty.

However, we believe that a better approach is to provide guidance to teams on handling their own upgrade.

Interested in helping get your team started? Take a look over our Rails Upgrade Kickoff service and fill out the form if you'd like to talk shop about how we can help your team manage their Rails upgrade process.

This was originally posted on blog.planetargon.com

How To Be A Good Guest (in another team's codebase)

Robby Russell 🐘🚂 — Tue, 24 Nov 2020 22:30:35 +0000

For nearly twenty years, I have regularly found myself (temporarily) in another team's software codebase. From being hired as a contractor, to providing emergency technical support, to helping companies understand the health of their application via a code audit...I have learned a few things (via trial-and-error) about what to--and more importantly--what not to do while being a guest.

This topic is near-and-dear to me. Recently, I was a guest on the Developer Tea podcast and we got deep into this topic. We got deep into it needed to split it up into two episodes!

🎙 Listen to part 1 and part 2.

Are you a freelancer or contractor about to temporarily participate in another Engineering team's project? Here are a few considerations for those first hours/days of being a guest.

(FWIW -- you can apply this to being a new full-time team member, too!)

Document Your Goals 📝

As a contractor, the company has likely brought you in to assist with something specific. What was the problem that they were encountering and/or feared they would encounter in the future?

Are you there because you have specific expertise that they have limited knowledge of, in-house?

Do they need help upgrading their Ruby on Rails application and you've helped dozens of teams do that? Has their application become unstable? Is their test suite taking far too long to run and they need you to help them speed that up?

Are you there to temporarily offset needing to hire a full-time engineer? (Aka staff augmentation)

Let's dig deeper into this one. Why do they need to bring in additional help right now? Did they recently lose someone? Has their team's Sprint velocity drastically slowed down? Are they needing to scale up for the next few months?

Whatever the case...you should understand what their underlying rationale is. You need to capture their WHY behind the decision.

If there is one thing that I've learned over the years...it is that when there are a lot of moving parts, we sometimes need to remind our clients of their own decisions.

As much as you would like to believe that everyone on the team you're temporarily joining is on the same page (and/or even support the idea)...it is wiser to assume they are not.

That's okay, though.

(Let's find comfort knowing that humans have this funny way of moving forward, together, despite an unpredictable level of chaos.)

This is why it is important for you to clarify what your goal is here. You will need to own the success of it. This is what they are paying you to do.

🚫 Anti-pattern: Being passive. Showing up on Day 1 and asking, "what do you want me to focus on? When will someone assign me tickets to work on?"

When you show up on Day 1, you'll want to reiterate why they hired you. Frame your questions around that.

"My goal is to help your team address X & Y over the next few weeks. Who would be the best person(s) to help me get up-to-speed on the current situation?"

Once you identify who your internal domain expert is, you'll want to reach out to them to schedule manageable blocks of time to a) reiterate your goals b) listen to them share their perspectives/concerns (capture these, too!) c) learn more about their capacity constraints, and d) ask them if there are other people on the current team who might also be helpful to help you reach your goal(s).

Make it a SMART Goal ⚽️

Take a moment to think 3-4 weeks into the engagement. You're having a one-on-one chat a team lead and they ask, "how is that project of yours coming along?" ...how will you respond?

Ideally, you should be able to respond with, "ON TRACK" or "OFF TRACK."

Software Engineers have been known to be risk-averse (for good reason!) but when we're hired guests, we should aim for removing ambiguity and/or diving too deep, too early, in a discussion. While we have to balance a lot of nuance in our jobs, let's keep be mindful to not overwhelm the person we're speaking to unless they are truly curious to get into the weeds with you.

We can do this by trying to clarify them via SMART goals.

💃🏻 ProTip: "We're on track!" > "I'm on track!"
(...remember, you are part of a team)

...wait, WTF are SMART goals? 🤔

Great question!

🧠 S.M.A.R.T. is a mnemonic acronym to capture our objectives by answering whether they are Specific, Measurable, Achievable, Relevant, and Time-bound.

Here is a helpful guide on writing achievable SMART goals by the fine folks at Atlassian.

Share your SMART goal 🥅

Rather than assume everyone shares the same understanding of the goal, it is important to share what you've captured with your new team members.

There are times when your new teammates might not believe a goal is achievable...especially if they've tried (and failed) to get there in the past. This is your chance to solicit input.

If it later comes up that they didn't share something useful when given a chance, then it'll be something you can recalibrate with them.

Avoid assuming that this is malicious. It's plausible that it wasn't on their mind at the time and they remembered it later.

Getting Into Their Code 👩🏼‍💻👨🏻‍💻

Let's assume that they are going to invite you to their code repository(s) and you'll be aiming to get their code up-and-running in a local development environment.

What kinds of changes are happening in their code?

One of the first things that I do after cloning a repository is to start browsing the output from git log. I'm looking to learn more about their team.

📝 Do they follow commit message conventions?
📖 Do the commit messages help tell a story?
🚢 Are they shipping new features?
🐛 Are they trying to squash a lot of bugs?
🎳 Who has been actively pushing code changes into the main branch(es)? (The bowling ball felt fun)

Using other fancy git commands, you can find files/areas of high churn, explore the maintenance (or lack thereof) of the test suite, how often documentation is updated, etc.

Will you be interacting with these people on the team in the coming days? Take note of a few observations.

"Wow, it seems like you've worked on a big feature recently. What was involved with that?"

"It looks like you've been helpful in squashing a lot of bugs recently. Is that a big part of your role here and/or do you rotate that responsibility across the team?"

How do you get their application running (locally)?

If you're lucky, the team will have up-to-date docs that'll help you quickly get their application running in your local dev environment. You might consider timing how long this process takes.

It can be helpful to report this back to a team lead to see if they are surprised by the information. If the team is encountering scaling problems, this can be one of those bottlenecks that slow down other new hires/contractors, too.

If anything, they can use this data point to properly map out a realistic onboarding timeline. Similar to capturing how long it takes for your test suite to run, how long deployments take, uptime... this is another useful metric to measure.

Recruit a spin-up buddy, if possible

When my team at Planet Argon are hired by a client, we try to have two of our engineers pair up on the process of getting the application running, in parallel. This way we can try to spot gaps in the documentation, debug issues quicker, and avoid having a scenario where one person who gets out ahead of the other.

If you are a solo guest working within a new-to-you team -- it might be a good idea to see if you can grab someone on the team to pair with you on setting up their application.

🤹🏻‍♀️ ProTip: If you want to get a feel for how complicated this process might be...ask one of their team members how anxious they would feel if their laptop died right now. 🙀 If they had a brand new laptop with a fresh operating system installed...how disruptive would that be for them? This is someone who has experience with their application and the underlying dependencies. If it is that scary to them...think about all the unknowns to someone brand new?

If you need to go rogue...

Should you not need to recruit someone to help you get up-and-running, then by all means, go on this solo mission but I encourage you to be extremely careful about this.

I've witnessed this a number of times over the years (by myself and members of my team). We'll begin to dig into our client's Ruby on Rails application, getting things up and running, and we forget to do the following.

Share our progress!

If the spin-up time takes a while, we would benefit ourselves (and our new teammates) by reporting on our smaller milestones.

A quick list of what's been accomplished and what remains should be simple enough to share. It'll give the team a chance to highlight if anything is missing from your list.

Update the documentation when we find any gaps and/or inconsistencies.

Our fresh perspective of reading and using the existing docs is a perfect time for us to create a new branch and commit updates so that we have a fresh pull-request to send when we're wrapped up.

🚫 Anti-pattern: Using language like "fixed" in documentation updates. Language like "updated" should suffice. Fixed has a different connotation. Assume it used to work fine at one point.

Acknowledge the great docs that exist!

While you are working your way through the documentation, if you are finding it to be well-organized and helpful, consider taking a moment to see who on the team was responsible for those updates. Look at the revision history. Reach out to the people who helped make your life easier today.

"Hi Kathryn! As I'm a frequent guest in other team's codebases...I see a wide spectrum of documentation in terms of organization and usefulness. I wanted to let you know that these are some of the best setup docs that I've seen. Thanks!"

"Oscar - I hit a problem while trying to install all the RubyGems because nokogiri was failing to build. I was about to start debugging it but noticed you had a helpful note in the docs about how to fix the dependency problem in Mac OS Catalina. You saved my afternoon!"

(Obviously, only do this if you found the documentation helpful; we don't want to placate anyone! 🙃)

The effort that we put into maintaining documentation tends to feel under-appreciated. Let's do our part to highlight when docs make our life easier!

🚫 Anti-pattern: Spending a ton of time trying to figure out how to fix a problem during the up-and-running phase without reaching out to other team members to ask if anyone had encountered it before.

If you spend several hours trying to Google for an answer on StackOverflow -- it is possible that someone on the team has but hadn't captured that in the docs before. This will help convey that you're humble enough to ask for assistance, which the team you're temporarily joining finds value in. We hope.

Be Vocal As You Dig into Your Project Work

Now that we're in a position to get crackin' on our work, it is tempting to put our headphones on and allow ourselves to get lost in the task-at-hand. While getting to a state of FLOW is important for productivity...we run the risk of being far too quiet for too long.

If the team has a good cadence on regular check-ins (do they have stand-ups? Slack channel updates?) then this might not be too much of a concern. Should they have a loose communication culture then we should be proactive over-communicators...especially in those first days as a guest.

What did you accomplish yesterday? What are you aiming to accomplish today? Do you have have any blockers?

Find out who might be able to help you remove a blocker. Do that earlier in the day so that you have a better chance of getting time scheduled with someone who can help.

🚫 Anti-pattern: Struggling to make meaningful progress in the first few days. We don't want our new team members to wonder what you've been up to. (While we can talk about how important it is for them to trust you...we need to earn some of that, too). Silence invites people to make assumptions. Influence the narrative!

As consultants, we are often hired for our expertise. We should avoid interpreting that as them expecting us to have all the answers. Let's just strive for having good questions.

Ask for Context Not Rationale

"Heya, quick question about this feature I'm starting to work on. Why did y'all design/build this it like this?"

🤦🏻‍♂️ Don't be that person.

Trust me, I've learned the hard way.

This is an ineffective way to win over your temporary teammates. Firstly, we shouldn't assume that the person(s) we're talking with had a hand in the design/building of something. They might have inherited it. They might agree with you if something was poorly designed... but I encourage you to be open, empathetic, and curious.

"Heya, I have a quick-wish question about this feature I'm starting to work on. Would you be a good person to help me get the scoop and/or backstory?"

Invite them to fill-in history. Listen. Assume that those who previously worked on it did the best that they could given the time/budget/resources available. Start from an assumption that they might agree with you.

You're there to help improve it not to be the person who can only point a flashlight 🔦 at it.

Note: if you find that they don't see a problem with it... you should find a way to have that collaborative conversation to explore that together. YMMV.

Leave the Team Better Than When You Found It

The long-term success of the team you're temporarily joining is not your primary responsibility. That isn't to say that you will not have an impact on it. With any team, it will change to a varying degree as people interact with it.

As consultants/contractors/freelancers...we have a unique and value perspective when we interact with different teams. If we're curious enough, we can spot patterns in the teams we participate in and share our observations.

If we care enough, we can highlight the things that you see are great about this team. The members of the team might be have been insulated by their team's bubble for a while. They may forget what it was like before.

On the flip side, if things seem toxic, let's find a meaningful way to convey that to the relevant people. We might not think it is our responsibility...oftentimes, it is not...but, again, the bubble might need to be stirred up. (I'm not advocating that you try to burn it all down...but you can share what you see is working or not compared to other teams you've been part of). Be mindful to not pre-diagnose the situation.

Raise underlying issues (versus pointing out the culprit).

🚫 Anti-pattern: Offering solutions versus experiments.
Compare "At another client, they used ABC. You should use ABC here..." versus "they experimented with ABC and had good success. Have you considered experimenting with ABC here before?"

Again, we're here to ask good questions.

Closing Thoughts

I know that I am scratching the surface at this topic. If you found yourself skimming this, let me summarize this into a few closing thoughts.

As a guest (in another team's codebase), please remember that you are a temporary member of that team now. Despite your technical skills, your goal is to be a productive and helpful contributor.

Be goal-oriented.

Avoid playing the hero.

Give credit.

Confirm assumptions.

Share kudos.

Stay organized.

Be thoughtful.

Propose experiments.

Be curious.

Be a good guest.

Forem: Planet Argon

When Reporting Quietly Becomes the Slowest Part of your Rails app

The pattern we keep running into

A shift in how we approach reporting

What tends to work better in practice

We’re walking through this LIVE

Ruby 4.0 and Ruby Box: What Changed and How to Upgrade Safely

Ruby Box: Isolation without abandoning Ruby’s flexibility

Basic example

Selectively exposing behavior

Why this matters in real applications

ZJIT: A new foundation for Ruby performance

Enabling ZJIT

What changes in practice

Ractors: Continued progress toward true parallelism

Basic Ractor usage

Structured communication with Ractor::Port

Why this matters for Rails applications

Core language and standard library improvements

Improved conditionals

Array enhancements

Better error context

Why We’re Excited about 4.0

Upgrade strategy: How we recommend teams approach Ruby 4.0

1. Establish a behavioral baseline

2. Upgrade Ruby before Rails

3. Use Ruby Box experimentally

4. Measure, then enable JIT options

5. Avoid the rewrite trap

Closing thoughts

How to Demo Your Application to a New Development Team

1. Start with the Big Picture: Your Business and Your Users

2. What Does the Application Do?

3. Where Does the Application Stand Today?

4. Preparing the team for emergencies

5. Helping Teams Help You

Making it happen 🚀

How to Demo Your Application to a New Development Team: A Helpful Guide

1. Start with the Big Picture: Your Business and Your Users

2. What Does the Application Do?

3. Where Does the Application Stand Today?

4. Preparing the team for emergencies

5. Helping Teams Help You

Making it happen 🚀

Deploying a Ruby on Rails app to DigitalOcean Using Kamal

What Is Kamal?

The Case for Kamal: Why It’s Worth Exploring

Optimized for Rails

Rails 8 Integration

Streamlined Asset Management

Easy Environment Management

A Modern Alternative to Capistrano

Flexible Support for Managed Databases

Ideal for Small Teams or Solo Devs

Developer-Friendly Debugging Tools

Active Community and Documentation

Why We Chose a Managed Database Instead of a Database Container

Getting Started with Kamal - Tips, Tools, and Insider Know-How

Prepare Your Environment

Install Kamal

Configure Your deploy.yml File

Understand the Deployment Workflow

Master Kamal’s Debugging Tools

Work with Accessories

Example Configuration for Deploying with Kamal

Kamal's Community and Documentation

Ready to give Kamal a try?

Linear and Jira: Making the Right Call for Your Team’s Workflow

Understanding Your Organization's Needs

Size and Structure Matter

Who Needs Access?

Insights from Real-World Use Cases

Linear in Action

Jira’s Strengths

Key Questions to Ask

What Are Your Growth Goals?

How Much Transparency Do You Need?

The Verdict: Linear or Jira?

Still Undecided? Test Both

Further Reading

Configure Your `deploy.yml` File