puma-dev makes it easy to switch between working on multiple Rails apps in a local environment, without dealing with port conflicts. It also spins down idle apps to save resources.

Let’s say you’re working on an app in ~/src/myapp. If you run puma-dev link, it will create a new symlink in ~/.puma-dev/. You can then access your app on your local machine at https://myapp.test, without having to manually start a Rails instance.

With the emergence of AI agents, it’s becoming more common to be working on multiple features concurrently in isolated workspaces by using Git worktrees.

In Conductor you can specify scripts to run when setting up a new workspace or archiving an existing one. We can make use of these to set up puma-dev automatically.

Conductor assigns random names to workspaces (from a list of city names). For the hostname, I prefer to prefix the workspace name with my repo name, e.g. https://myapp-toronto.test.

When a workspace is longer needed, e.g. the feature has been merged, the workspace can be archived, and the symlink will be removed from ~/.puma-dev/.

Here are the scripts that I’m using:

bin/conductor-setup

#!/usr/bin/env ruby
workspace_path = ENV.fetch("CONDUCTOR_WORKSPACE_PATH")
project = File.basename(File.dirname(workspace_path))
name = "#{project}-#{File.basename(workspace_path)}"
system("puma-dev link -n #{name}") or abort "puma-dev link failed"
puts "puma-dev link succeeded: https://#{name}.test"

bin/conductor-archive

#!/usr/bin/env ruby
workspace_path = ENV.fetch("CONDUCTOR_WORKSPACE_PATH")
project = File.basename(File.dirname(workspace_path))
name = "#{project}-#{File.basename(workspace_path)}"
symlink = File.expand_path("~/.puma-dev/#{name}")
File.delete(symlink)

You’ll also need to make each script executable using chmod +x.

To learn more about using Conductor with Rails, check out:

• Using Conductor.build with Ruby on Rails by Andrea Fomera.
• Conducting Rails by John Nunemaker.

Introduction

In this post I’ll briefly explain what git hooks are, introduce hk, and show some practical examples of using it with Ruby and Rails projects.

Git hooks

Git hooks are shell scripts which run automatically in response to particular events. These are usually written to a hidden .git/hooks directory, either per project, or globally in your home directory.

The most commonly used kind of Git hook is a pre-commit hook, typically used for linting and formatting.

While you can write hooks by hand, people typically make use of hook manager tools. These usually provide higher-level abstractions, or make it easier to share hooks within a team, and keep them up to date. Common tools include:

• Husky (written in JavaScript) - popular in the Node/JS world
• pre-commit (written in Python)
• Overcommit (written in Ruby)
• Lefthook (written in Go) - by Evil Martians, who are well-known in the Ruby world

Other approaches

Although git hooks have been around for a long time, I have found that they are not so commonly used. Instead, people would usually rely on their editor for linting, and make use of format-on-save, for example with Ruby LSP.

Now that more and more code is being written by agents, there is often no editor tooling involved so that approach fails. You could use a prompt (e.g. in CLAUDE.md) to make your agent aware of your linting/formatting tools, but this is not ideal:

• It’s slow. The latency as the agent goes back and forth with the linting/formatting tools is a drag.
• It’s a waste of tokens and context.
• The agent behaviour is non-deterministic, so even if it usually runs the linting/formatting, it may occasionally neglect to.

The one thing that we should aim for is to always catch linting/formatting issues before CI runs, to avoid wasteful cycles.

With hooks, we can have consistent and reliable linting and formatting for both human-authored and agent-authored code.

Introducing hk

hk is a project by Jeff Dickey (jdx) who is also the author of mise, a popular tool for managing development environments.

It was first announced in February 2025. It fills a similar role to the tools listed above, but has some particular areas of emphasis:

• Performance: It’s written in Rust and design so that tools can run concurrently, and knows to only run on modified files.
• Ease of configuration: It includes helpful defaults (“builtins”) for a wide variety of ecosystems.
• Low friction: It handles aspects such as re-staging of fixes, and doesn’t get in the way during git operations such as rebasing.

Using hk with Ruby

hk includes builtins for many common Ruby tools:

• brakeman
• bundle-audit
• erb
• fasterer
• reek
• rubocop
• rubocop-server
• sorbet
• standard-rb

(I contributed rubocop-server to take advantage of RuboCop’s --server mode).

Getting Started

hk has good documentation on how to install it, so I won’t repeat the general steps here. Instead I’ll focus on Ruby and Rails.

Once installed, run hk init to create a default hk.pkl configuration for your project. This can later be committed to a project to allow others to make use of it.

The default hk.pkl has no active steps, so by default it does nothing.

(Sidenote: the configuration format used is pkl, pronounced ‘Pickle’, which I had never heard of before. I was surprised to discover that it’s an Apple project).

Adding RuboCop

We’ll start with RuboCop, since it’s so common in the Ruby world. Let’s add a step for it:

local linters = new Mapping<String, Step> {
["rubocop_server"] = Builtins.rubocop_server {
    prefix = "bundle exec"
}

Two things to note:

• We are using rubocop_server instead of RuboCop, to avoid the startup overhead.
• We are prefixing the command to ensure it uses the RuboCop version from Gemfile.lock, rather than the latest installed gem version.

Note that we don’t have to specify the RuboCop command or flags, or be aware of subtleties like the --force-exclusion flag. It’s already defined as part of the builtin.

Let’s test it out by creating a very simple Ruby file without committing it.

# demo.rb
puts "hello world"

Then run bundle exec rubocop demo.rb

If you’re using the default RuboCop configuration, you should see two issues reported:

demo.rb:1:1: C: [Correctable] Style/FrozenStringLiteralComment:
  Missing frozen string literal comment.
puts "hello world"
^
demo.rb:1:6: C: [Correctable] Style/StringLiterals:
  Prefer single-quoted strings when you don't need string interpolation or special symbols.
puts "hello world"
     ^^^^^^^^^^^^^

Now let’s try committing that file:

git add demo.rb
git commit -m "Add demo.rb"

You notice that one offense is fixed, but not the other. This is because Style/FrozenStringLiteralComment is considered an unsafe autocorrection in RuboCop, as it could potentially change the behaviour of the code.

Since the file is not considered valid, the commit is rejected. We need to manually fix the other offense by adding the # frozen_string_literal: true line, and then commit again.

If you were using a coding agent, you could let it handle this fix you. And depending on the model’s capabilities, it may be be able to check if # frozen_string_literal: true is actually safe or not in this case.

Adding biome

In the past I’ve used eslint alongside Prettier, but I’m now trying out biome, a Rust-based linter/formatter which supports many frontend technologies including JavaScript, TypeScript, JSX, JSON, CSS and GraphQL.

First we need to add it to our package.json:

npm install --save-dev --save-exact @biomejs/biome

Then it’s just a one line addition to our hk.pkl config:

local linters = new Mapping<String, Step> {
    // ...
    ["biome"] = Builtins.biome
}

Adding Herb

Let’s now look at how we could add support for a tool which isn’t currently natively supported by hk.

hk has a builtin for erb linting, but there’s a better, modern linter and formatter for ERB files - herb. Its focus on performance makes it a great match for hk.

Although there is a herb Ruby gem, the tools we need, herb-lint and herb-format, are actually npm packages, so we’ll first add those to package.json as development dependencies:

npm install --save-dev --save-exact @herb-tools/formatter
npm install --save-dev --save-exact @herb-tools/linter

And as hk doesn’t have a builtin for herb, we’ll need to add some custom configuration in hk.pkl:

local linters = new Mapping<String, Step> {
    // ...
    
    ["herb_lint"] {
        glob = List("**/*.html.erb", "**/*.html", "**/*.rhtml", "**/*.turbo_stream.erb")
        exclude = List("node_modules/**/*")
        check = "node_modules/.bin/herb-lint "
        fix = "node_modules/.bin/herb-lint --fix "
    }
    
    ["herb_format"] {
        glob = List("**/*.html.erb", "**/*.html", "**/*.rhtml", "**/*.turbo_stream.erb")
        exclude = List("node_modules/**/*")
        check = "node_modules/.bin/herb-format --check "
        fix = "node_modules/.bin/herb-format "
    }
}

Note that we prefix the executable calls with node_modules/.bin/ to prevent unintentionally falling back to globally installed versions, which could be different per machine.

With the above all set up, you’ll now have linting and formatting for almost every file in a typical Rails app.

Wrapping Up

Along with mise, hk has become one the tools that I rely on every day as a developer. Whether your writing code by hand, or using an agent, it will catch linting and formatting issues quickly and effectively, allowing you to focus on the more interesting things.

Anthropic recently added support for custom slash commands, allowing you to define commonly used prompts as reusable macros.

Based on my experience as a Ruby developer, I’ve created several custom commands for typical Ruby project workflows, such as:

• Configuring CI with GitHub Actions (including Ruby matrix builds)
• Adding RuboCop or Standard
• Bumping the Ruby version across gemspecs, Gemfiles, and CI configs
• Adding common Ruby gems with appropriate configuration

Although Claude does a reasonable job for these with a zero-shot prompt, the custom commands allow for better adherence to modern best practices, which are often preferable over what the model was trained on.

Each command has been iteratively refined based on real-world usage across different Ruby projects. (I’ve found that using bullet-point checklists makes Claude more systematic about following instructions).

As these patterns may be valuable to the broader Ruby community, I’ve published a claude_code_slash_commands gem (mostly written by Claude Code of course).

The gem provides a simple install command that copies the slash commands to your local ~/.claude/commands directory. The commands are designed with Ruby development expertise in mind, incorporating common patterns and approaches.

If you have ideas for additional Ruby-focused slash commands, I’d love to see them! Feel free to open a PR on the repository to contribute your own commands that could benefit the Ruby community.

Zed is a modern, high-performance code editor that’s gaining popularity. After several years of using VS Code, I’ve been trying it out for writing Ruby and I’ve been impressed. With recent rapid development in AI, Zed’s close collaboration with Anthropic makes it a strong contender to VS Code derived editors such as Cursor.

In this post you’ll learn how to set up Ruby LSP with Zed, and how to troubleshoot if things aren’t working. I’ll also share some alternatives for features that aren’t currently available in Zed.

Setting up Ruby Support

Zed’s Ruby support comes from the official Ruby extension, created by Vitaly Slobodin. You can enable it through zed: extensions.

As with all Zed extensions, it is written in Rust. Its documentation can be found here, as part of the official docs.

Configuring Ruby LSP

Zed has good built-in support for the Language Server Protocol, meaning there’s a lot of tooling already available that can be used.

Zed defaults to using Solargraph as its language server for Ruby, but my preference is to use Ruby LSP, since I’m a contributor.

You’ll also be able to take advantage of Ruby LSP add-ons such as ruby-lsp-rails and ruby-lsp-rspec.

It can configured in Zed’s settings as follows:

{
  "languages": {
    "Ruby": {
      "language_servers": ["ruby-lsp"]
    }
  }
}

(The docs suggest disabling each language server that you don’t want with !, and using "..." to enable the rest, but I find it simpler to just list the ones you do want).

Note: I’ve noticed that some configuration changes don’t seem to apply until you fully quit and reload the editor (workspace: reload isn’t enough), so you may need to do that in some situations.

To verify things are working, open a Ruby file, then choose debug: open language server logs from the command menu. The output should look something like this:

If there are multiple language servers running, then you’ll need to first select the ruby-lsp log from the menu at the top left.

If ever it seems that Ruby LSP is not running, this is the first place to check for errors.

Enabling Diagnostics (linting)

Update: This section previously described a workaround for the lack of pull diagnostics support in Zed, but this has now been implemented and diagnostics are working.

Disable onTypeFormatting

~There is known issue in Ruby LSP with cursor placement when trying to type a | for block arguments, so you may want to disable onTypeFormatting for now~

Update: This was changed to be disabled by default in v0.13 of the extension.

Global vs Local Settings

So far I’ve shown settings as being added to the Zed’s global configuration.

If you only ever work on a single Ruby project, then it doesn’t really matter if you all your settings are global. But many of us work on codebases with different configurations, such as for linting and formatting, so having more granular control is often necessary.

You can add project-specific settings to .zed/settings.json in your project directory. These settings will be merged with the global settings, so normally you’ll only need a few lines of configuration. For example, you might have some projects that use RuboCop but others that use Standard.

Running tests

One very useful feature when using Ruby LSP in VS Code is Code Lens, which adds a Run in Terminal link to each test, and shows the result in the integrated terminal.

This LSP feature is not supported by Zed, but we can use the powerful Tasks feature to do something similar.

For example, to add a task for running Rails tests, we can create a .zed/tasks.json file:

[
  {
    "label": "test $ZED_RELATIVE_FILE:$ZED_ROW",
    "command": "bundle exec rails",
    "args": ["test", "\"$ZED_RELATIVE_FILE:$ZED_ROW\""],
    "tags": ["ruby-test"]
  }
]

The test can be run by clicking on the ▷ in the gutter, or with the Command-Shift-R keybinding.

Advanced LSP Troubleshooting

It can sometimes be useful see the underlying requests and responses for the language server. In the debug: language server logs window, click the second menu, then enable RPC Messages:

What’s Missing

• If you’re coming from VS Code with Ruby LSP, you might notice some features are not available. There’s two main reasons behind this:

  • Some Ruby LSP features depends on custom behaviour in the VS Code extension. Those would need to be reimplemented for Zed within the Ruby extension.

  • Some parts of the LSP specification are not yet implemented in Zed. You can follow this Zed issue to learn more.

• Changes aren't indexed until Zed is restarted.

  (#3384). This is now working.

• A debugger is in beta, and there’s a PR open for supporting rdbg.

• Zed supports Snippets but the Ruby extension doesn’t yet have any. I have a PR in progress to add them.

Other Useful Resources

• For ERB linting, support for Herb has been merged and should ship soon.
• For ERB formatting, erb-formatter works well.
• To toggle between a test and its implementation, try zed-test-toggle.
• For working with Hotwire, there is the Zed Stimulus extension.
• Support for Sorbet was previously available in a separate extension but is now built-in as of v0.9.0 of the Ruby extension.

It has the ability to automatically embed transcripts into the recordings. I wanted to extract these out to use with an automated workflow for OmniFocus, a task manager.

With a little bit of investigation, I could see the transcript was represented as a Base64 string contained in JSON. Here’s how to extract it:

strings recording.m4a | tail -n 1 | sed 's/^[^\{]*//' | jq -r '._root.txscriptv2.tx._data' | base64 --decode

A brief explanation of how each command is used:

• strings to extract any text found within the file
• tail to keep only the last line (the one with the JSON)
• sed to discard the part of the line before the JSON structure
• jq to extract the specific part of the JSON containing the encoded text (the -r flag removes the quotes).
• base64 to decode it

In this post we introduce the Ruby LSP add-on system. We’ll explain the problem it solves, discuss its architecture, showcase some example add-ons, and share our vision for a future addon ecosystem that enhances the Ruby development experience.

https://railsatscale.com/2024-10-03-the-ruby-lsp-addon-system/

Since Jumpstart Pro is a commercial product, I can’t share the full code, but if you’re a Jumpstart customer you can view the changes in this branch of my fork. I recommend viewing it as individual commits to understand it step-by-step. The order may not exactly match the blog post, but the end result should be the same.

For this post, I’ll assume you are starting from a freshly generated Jumpstart app. If you have already built your app on top of Jumpstart then it may take some more effort but the overall approach is the same.

I’ll demonstrate the process in incremental steps, so your app can continue to be deployed while type information is still being added. This follows Sorbet’s philosophy of Gradual Typing.

Preparation

Start by creating a sorbet branch for the Sorbet migration. This will be fairly short-lived, and only needed for the initial setup.

Setting up CI

Although Jumpstart Pro provides a GitHub Actions CI script, we’ll instead use setup-rails since it will detect if Sorbet is in use and run additional checks. We’ll also enable the standard option, since that’s what Jumpstart uses instead of RuboCop.

name: Verify
on: [push, pull_request]

jobs:
  verify:
    uses: setup-rails/setup-rails/.github/workflows/verify.yml@main
    with:
      run-before-tests: sudo apt-get install -y -qq libvips
      standard: true

(I also had to disable parallel testing by commenting-out the parallelize line in test_helper.rb, as I found it was causing the tests to hang. I haven’t had a chance yet to look into the cause.)

Basic Setup

Overall, the setup for Jumpstart Pro is not so different than for any other Rails app, but the optional dependencies complicate things a little: If there is code that references a gem that isn’t installed, then typechecking will fail, even if it’s within a defined? check. To simplify things for this guide, we will open the Jumpstart configuration page and enable the following features:

• Payment Processor: Stripe
• Background Queue: Sidekiq
• ActsAsTenant
• Facebook Omniauth Provider

This will result in some additions to Gemfile.lock which you should commit.

Next, we’ll add the sorbet-static-and-runtime and tapioca gems to the Gemfile, run bundle then bundle exec tapioca init.

The init command can take a long time to run (10 minutes or more), and it may seem like it has frozen. Have patience!

You may be alarmed by the huge number of RBI files this creates, but you will very rarely need to interact with them.

After this is complete, we can commit everything. Let’s now run the typechecker:

$ bundle exec srb tc

We should see about 20 errors. It’s common to encounter errors when setting up Sorbet initially, usually due to known limitations in Sorbet or Tapioca.

In the case of Jumpstart, several are due potentially ambiguous definitions, which are easily fixed by using the full version of the definition. For example instead of:

module Admin
  class User::ImpersonatesController < Admin::ApplicationController
  end
end

we need to write:

module Admin
  module User
    class ImpersonatesController < Admin::ApplicationController
    end
  end
end

Other errors are because some parts of the gem are not required by default. We need to add an entry to Tapioca’s require.rb:

# sorbet/tapioca/require.rb
require "administrate/base_dashboard"

and then re-run bundle exec tapioca gem administrate.

After this there should be only handful of remaining errors, which are due to the Sorbet limitation that “include must only contain constant literals”. We can work around this by marking those calls as unsafe:

T.unsafe(self).include Engine.routes.url_helpers

At this point you can push to CI and everything should be green again. If you wish, you can merge the sorbet branch into main and continue the remaining work in other branches.

Clearing the TODO list.

Although we are no longer seeing any typechecking errors, some things are being ignored because they are listed in todo.rbi which was generated by sorbet init. We should aim to eliminate these before continuing.

We intentionally never manually edit todo.rbi - we’ll make a change, and then regenerate it, to gradually reduce the number of entries.

Many of the remaining entries in todo.rbi are due to optional gems, where they are conditionally referenced in an initializer. We could just delete those, but that would make it a little tricker pulling in changes from upstream in Jumpstart Pro. The approach I suggest is using Ruby’s __END__ keywords. It indicates that the code in the file has ended, and so Ruby (and Sorbet) will ignore it:

__END__

Bugsnag.configure do |config|
  config.api_key = Rails.application.credentials.dig(:bugsnag, :api_key)
end

Next, we have some entries in todo.rbi that relate to the Devise and Noticed gems. For gems that make use of metaprogramming, we often need to give Sorbet some help by adding shims.

# sorbet/shims.rbi
class Devise::OmniauthCallbacksController; end
class Devise::RegistrationsController; end
class Devise::SessionsController; end

class Noticed::NotificationChannel; end

For Minitest::Mock and Sidekiq::Web, we again need to add entries to require.rb then regenerate the RBIs.

# sorbet/tapioca/require.rb
require "minitest/mock"
require "sidekiq/web"

At this point, there should be no more entries in todo.rbi and running tapioca todo will delete it.

Standard

Although Jumpstart uses Standard rather than RuboCop, there are some useful cops in rubocop-sorbet, so we will add that as a dependency.

Then in .standard.yml, we’ll use Standard’s extend_config feature to reference a RuboCop Sorbet configuration file:

# .standard.yml
extend_config:
  - .rubocop_sorbet.yml

The config will look like this:

# .rubocop_sorbet.yml
require: rubocop-sorbet

AllCops:
  NewCops: disable
  Exclude:
    - lib/jumpstart/test/dummy/**/*
Sorbet/ConstantsFromStrings:
  Exclude:
    - 'app/models/connected_account.rb'

We’ll ignore the Dummy app used by the internal jumpstart gem, since that should be treated as a separate application.

We also we need to disable the ConstantsFromStrings check for one file, due to Sorbet’s limitations for const_get.

With that done, we can now run bundle exec standardrb --fix which will add a typed: false entry to each file. This happens because rubocop-sorbet’s default configuration enables the Sorbet/FalseSigil cop, which ensures all files are at a strictness of a least false.

On its own that doesn’t do anything, but it prepares the way so that we can use Spoom.

Spoom

Spoom consists of several tools, one of which is the bump command:

bundle exec spoom bump

This helps us discover which files can be ‘bumped’ up a level of typing.

You should see that a large number are now marked as # typed: true, without us having to do any work.

Next Steps

At this point, you can search for # typed: false in *.rb and you’ll see there are around 100 files remaining that aren’t yet typed. Resolving all those is outside the scope of this post, but you now have a strong starting point.

You’ll notice that we haven’t written any signatures yet. But even without those, we can start benefiting from Sorbet’s checks for things such as calls to non-existing methods, or unreachable code.

Over time, I made few updates and adjustments to it, so whenever I started a new project I would copy the config from one of my older projects. But this meant each project gradually became inconsistent, and some got updated more than others.

I wanted to have one single base workflow for all my apps, so that if I made a change, all the apps could easily benefit from it.

Reusable Workflows

In November 2021, GitHub announced that Reusable Workflows was generally available.

Although GitHub Actions has supported composite actions for a long time, Reusable Workflows allows for a much more concise configuration, and the ability to reference a whole workflow from another repository, rather than having to build up each step individually.

Read more about it on GitHub’s blog.

Introducing setup-rails

Using the Reusable Workflows feature, I’ve created setup-rails for quickly and easily enabling CI for Rails apps.

By creating a single file in your repo, e.g. .github/workflows/verify.yml, with the contents below, you should have a working CI workflow which configures the database and runs your app’s tests:

name: Verify
on: [push]

jobs:
  verify:
    uses: andyw8/setup-rails/.github/workflows/verify.yml@v1

You can take a look at this example app to see it in action.

The first time you run the workflow may be slow, but subsequent runs should be much faster once the dependencies are cached.

I’ve also shared a Railsbyte so that you can set this up with one command:

rails app:template LOCATION="https://railsbytes.com/script/VMys8A"

Principles and Configuration

I designed setup-rails so it should work at a basic level with no configuration needed for most apps.

There are a few options you can enable depending on your app, such as RuboCop, Bundler Audit and RSpec - see the README for details.

Currently only Postgres is supported but I’d like to expand to cover at least MySQL.

Enhancements

Building upon Matt’s great starting point, I made a few updates:

• Uses the latest versions of setup-node and setup-ruby
• Adds support for rails test (e.g. Minitest) as well as RSpec
• Enabled Dependabot for updates of the actions that setup-rails depends on
• Uses setup-node’s JavaScript caching rather than a custom approach
• Skips development gems when running Bundler to avoid unnecessary work.

Get Involved

I’m already using this on most of my apps, but I’d love to get wider feedback.

Please try setup-rails on your app and let me know how it works for you. Issues and pull requests are welcome!

I noticed that whenever I was starting on a new kata, I was doing the same basic setup repeatedly before being able to write a first test. I also felt I was missing some of the configuration that my other ‘real’ projects benefited from.

This led me to create ruby-kata-template. By clicking on Use this template, I get a new blank project in seconds, configured to my preferences.

I don’t expect my preferences to match everyone else’s, so I encourage you to fork it and customize to your own ideal template.

Features

Starting Point

There is an empty Project (project.rb) and a corresponding test (project_test.rb). I expect the first step in many katas will be to rename these.

Directory Structure

I’ve followed the standard Ruby convention of the implementation being in lib/ and the tests in test/

Minitest

Although Minitest is already provided as a Bundled gem with Ruby, it’s included in the Gemfile to ensure we’re on the latest version. (I’ve used RSpec extensively in the past, but my current preference is Minitest).

ActiveSupport::TestCase

ActiveSupport::TestCase is part of Rails but here we are using it independently. It allows you to write ‘declarative’ tests, e.g. test "it works" do... rather than def test_it_works, which I feel is more readable.

Rake Task

It’s common on Ruby apps to have rake or rake test, so we provide that. It has support for both MiniTest naming conventions (test_*.rb and *_test.rb)

Standard

Standard is an opinionated RuboCop configuration.

For me, the real value of Standard (or RuboCop) is only apparent when you have two things configured in your editor:

• Immediate feedback (your editor highlights problems as you code)
• Auto-formatting (you can fix issues with one single shortcut, or automatically when the file is saved).

There are various ways to set up this, but the template uses rubocop-lsp.

rubocop-lsp

rubocop-lsp is a gem which implements the Language Server Protocol. It allows for a close integration between your editor with RuboCop. It avoids the overhead of starting RuboCop, meaning linting or auto-correction is near-instant.

To use it, you’ll also need an plugin or extension for your editor. The template is set up to recommend the VS Code Shopify.rubocop-lsp extension.

Solargraph

Solargraph adds IDE-like experience for your editor. It provides helpful features such as a content-aware autocompletion, and documentation for the Ruby language.

However, I often run into problems with it, so I was on the fence about including it.

It’s not as powerful as Sorbet, so it’s unable to infer types unless they are a Ruby primitive (String, Array, etc.)

And more

Take a look at the README to learn what else is included.

A failing build is demoralizing and disruptive for the team. Developers and testers will lose confidence in the correctness of the system. They may be unable to know if a failing test was due to their change, or to something else.

Keeping the master build passing should take priority over almost everything else. The whole team should feel responsible for it, and when the build fails, the whole team should be alerted. It shouldn’t be left to a ‘devops’ team, or only to senior developers. One option is to configure your CI to post notifications to your team’s Slack channel for high visibility.

We can adopt several practices to help ensure master stays passing:

• Performing code reviews to detect potentially problematic tests
• Running linters to catch common problem areas, such as rubocop-rspec
• Using features such as GitHub Checks to enforce a passing build before the branch can be merged into master.

But even with these practices, things can still go wrong:

• We can have intermittent failures due to factors such as time of day or concurrency.
• We can have a semantic conflict, where behaviour is correct on individual branches but incorrect when they’re combined.
• We can have infrastructure failures unrelated to the code.

It’s important to establish a clear process for what should be done when the master build fails. The details of this should be discussed and agreed by your team, but I’ll discuss one starting point.

In most cases, the most recent merge will be the one that broke the build. If the author of the most recent merge hasn’t reacted to the failure, send a gentle nudge.

The first thing the author should do is pull the latest master, and check if the test passes locally. If it fails, that gives a good starting point. If it passes, we’ll have to broaden the investigation.

While this in progress, there are two key things to keep in mind:

• Getting the build back to passing as soon as possible
• Keeping the team informed, and sharing an ETA if feasible

If the team isn’t aware of work going on, a developer might assume that a failure was due to their change. Or another developer may start investigating the failure, unaware that someone else is already on it. Both could result in wasted time.

The next step is more nuanced. It may need discussion with the team, and could depend on the nature of your project:

• Should you revert?
• Should you temporarily disable the test?
• Should you delete a flawed test?

Have a clear written policy for this is useful, for example in your wiki or README.

If the fix is going to take some time to resolve, you should aim to give updates at least every hour or so.

Once the problem is resolved, take some time to reflect. Was there a particular practice which caused this? Could you make some change to improve things? There’s almost always some learning opportunity.