DEV Community: Vladimir Dementyev

Keynote tips: syntax highlighting

Vladimir Dementyev — Mon, 04 Aug 2025 05:37:10 +0000

It's been 9 years since I started my public speaking journey. Different cities, countries, and continents, presenting in front of a handful of people eating pizza or giving an opening keynote for hundreds of engineers, shaking like Elvis, and almost oversleeping my talk. The only thing that stayed constant—I used Apple's Keynote to craft all of my ~40 slides.

Keynote is a popular presentation software (among Mac users), no doubt. Still, many software engineers prefer other, usually Markdown-driven, tools for building their slides. Why so? Partially due to the everything-should-be-code lifestyle, but I think most are attracted by the simplicity with which you can add beautiful code snippets to your presentation. In Markdown, you just write code and add the language specifier!

How can one add highlighted code snippets to a Keynote presentation? Let's do a quick overview of options, finishing with the one I've ended up with.

Option #1. Screenshots

The first option is trivial—just take a screenshot of the code editor and paste it into your slide (that's how I started my Keynote journey). Simple? Yes. Maintainable? Not really.

Still, it's an option (a last resort one). If you have to do that, consider using some specialized code-to-image tool like carbon and not just crop an image of your editor.

Option #2. HTML

Did you know that Keynote can consume HTML content? Copy some HTML and paste it onto a slide, and you'll see it being transformed into a text box with styles preserved. Compared to screenshots, you can edit the text, change its characteristics (e.g., size), and so on.

The question is: where to get an HTML version of the code?

If you are a VS Code user, you can just copy the code from the editor. That's it. VS Code automatically saves an HTML version into the clipboard buffer.

If your editor copies only the plain text (I'm looking at you, Zed), there is Code to Markup at your service!

Although it is as simple as screen capturing, this approach has a couple of downsides. First, you have to switch between Keynote and an editor/website to highlight code snippets (not-so-ideal UX).

Another thing that bothers me is the fact that aforementioned (maybe, all similar?) HTML generators preserve background color for code lines but not for gaps between them. That results in the following representation:

You should either adjust your slide background or manually update it.

Option #3: RTF & Automator

HTML is not the only format that can preserve code styling. There is also RTF (Rich Text Format). It is not as expressive as HTML, but it has everything we need to highlight code snippets. And from my experience, pasting code-as-RTF turned out to work the best with Keynote. And this experience is based on the setup described below.

First, to turn a plain text code into its highlighted RTF representation, I use the tool called (surprise!)... highlight! It's a very old one, but it still works perfectly (people used to know how to write software that lasts).

You can install it with Homebrew: brew install highlight.

It's a command-line tool, our target code snippet lives on a Keynote slide—how to connect them? Using Automator.

Automator is a macOS tool that allows you to customize your OS features. For example, you can create a quick action—an action that can be triggered either from the context menu or via a hotkey combination. Do you see where I'm going? We will create a quick action to get selected text, turn it into RTF, and paste it back where it belongs. This way, we can highlight code in Keynote by pressing a key combination!

Here is a step-by-step how-to:

Open Automator, go to New -> Quick Action.
Select "text" in "Workflow receives current" (we will operate on the selected text). You can also limit the visibility of this action to particular applications (say, Keynote).
Open the action library and add the "Copy to Clipboard" to the workflow:

Add the "Run AppleScript" action:

Update the script as follows (feel free to tune the options to your taste):

on run {input, parameters}

    set command to "/opt/homebrew/bin/highlight --out-format rtf --syntax=ruby --style base16/chalk  --font \"Martian Mono\" --font-size 32"

    do shell script "/bin/bash -c 'pbpaste | " & command & "| pbcopy'"
    delay 0.5
    tell application "System Events" to keystroke "v" using command down
end run

Save the workflow and go to Keynote to give it a try!

Go to System Settings -> Keyboard -> Shortcuts -> Services -> Text, find your action, and assign a keyboard combination to it. Now, you can highlight any code in Keynote by just pressing the specified keys!

This workflow is not ideal, but it has served me well for many years. You have to hardcode the theme, the font size, and the language (or have multiple actions). But you do that once per presentation (so, a few times a year max)—more than "good enough" for me.

Sometimes the magic "tell application" command doesn't work, and I have to hit Cmd+V myself—again, not a big deal.

I'm pretty sure the setup could be optimized further: highlight replaced with some fancy and faster Rust CLI; AppleScript with JavaScript (why not?); maybe, Automator gurus know how to add options selection (language, theme) to the context menu. The core idea would stay the same—and that's what I wanted to share with you in this post.

Happy conferencing!
Share your Keynote vs. code tips!

P.S. How to know what's been stored in the clipboard buffer after you hit Cmd+C? Run the following command in your terminal:

osascript -e 'the clipboard as record' | less

DIY multi-regional uptime monitoring with Fly.io and Uptime Kuma

Vladimir Dementyev — Wed, 31 Aug 2022 22:03:45 +0000

Two things happened recently that led to this post:

Heroku had a DNS problem (incident#2453, and many websites went down.
Heroku announced their next chapter (spoiler: no more free ~~cookies~~ dynos).

I was affected by both (well, the second one has not come into effect yet). And I found this set of circumstances an excellent opportunity to try something new.

Introducing Uptime Kuma

The first event made me think of setting up an uptime monitoring (with DNS checks support), and an OSS project bubbled in my mind—Uptime Kuma.

Uptime Kuma calls itself a "fancy monitoring tool". And I absolutely agree with that. It has both a great feature set and a slick UI. Here is my dashboard:

You can find the complete list of features in the repo; I was only interested in the basic HTTP and DNS checks. As for notifications, there are dozens of integrations. I chose Slack for simplicity and plan to add a Telegram integration for personal projects later.

What about deployment? There is an official Docker image (louislam/uptime-kuma), so all you need is a platform capable of spinning up Docker containers and taking care of them. Heroku could be a candidate, but I prefer not to pay for pet/research projects. So, I turned to the alternatives.

Deploying Uptime Kuma to Fly

Fly.io is a modern deployment platform focused on multi-regional availability ("close to your users", their main page says). By "modern", I mean providing a great developer experience: CLI-first, sensible defaults and configuration, and a generous free tier.

You can deploy a Docker image to Fly with a single command:



flyctl launch --image louislam/uptime-kuma:1

That could be it for some apps, but for Uptime Kuma we need persistent storage to keep configuration and application settings (such as admin username and password). For that, we can use volumes.

Let's first create an application to generate the default fly.toml file:



fly create
# answer the questions, don't install PostgreSQL 🙂

In the resulting fly.toml file, update the service port (Uptime Kuma uses 3001 by default):



[[services]]
  http_checks = []
  internal_port = 3001

And add the mounts section:



[mounts]
  source="kuma_data" # choose whatever name you want
  destination="/app/data"

Now we need to create a volume manually:



fly volumes create kuma_data --region lhr --size 1

We use the smallest possible size (1 GB), which is too much for Uptime Kuma, but fly doesn't allow passing floats 🤷‍♂️

Now, we're ready to deploy our application!



fly deploy

After the app has been deployed, you can open it and configure the monitors:



fly open

Going multi-regional

I decided to go further and turn my DIY monitoring into a high-available solution by creating a second application instance in another region.

The tricky part here is dealing with volumes: a volume could only be attached to a single application instance. So it's just a private storage, non-shared.

If we want to deploy more instances, we must create new volumes. Let's create one in Chicago:



fly volumes create kuma_data --region lhr --size 0.1

We can check the status of our volumes by running the following command:



$ fly volumes list

ID        STATE    NAME      SIZE  REGION  ATTACHED VM
vol_xxxx  created  kuma_data 1GB   lhr     abc123    
vol_yyyy  created  kuma_data 1GB   yyz

Now, we need to add a new region to our application. First, I tried to follow the documentation and add a new region to the pool but failed:



$ fly regions add yyz

Error App 'uptime_kuma' uses volumes to control regions. Add or remove volumes to change region placement.

The error message itself wasn't really helpful (I created a volume, what's wrong?), but it led me to the community discussion which explains that you don't need to add regions manually when using volumes. All you need is to scale the app, and Fly will choose a proper region based on the free volume:



fly scale count 2

Awesome! Now we have two apps. But they are independent; how can we sync the configuration?

To deal with configuration syncing, I decided to use the built-in Backups features of Uptime Kuma: export in one region and import into another.

It turned out that there is no way to access an app deployed in the specific region, Fly takes care of geolocation-based routing itself, and you have no control over it. Solution? VPN!

So, here is the step-by-step instruction on how to "sync" Uptime Kuma instances:

Open the app closest to your current location: fly open.
Download the configuration backup.
Connect to a VPN server closer to the second location and run fly open again.
During the first launch, a fresh Uptime Kuma instance prompts you to enter admin login details again—just use the same as for the first app.
Go to Backups, choose the "Overwrite" option and upload a dump from the first app. That's it!

It took me about ~30 minutes to run a multi-regional monitoring system on Fly.io, and I hope it will last for years until Fly hits its next chapter forcing me to look for an alternative 🙂

Faster RuboCop runs for Rails apps

Vladimir Dementyev — Tue, 12 Apr 2022 18:07:08 +0000

Recently, Nate Berkopec shared an interesting observation: running bundle exec whatever could take seconds to boot if the Gemfile is huge (even when the executable itself requires a handful of dependencies).

// Detect dark theme var iframe = document.getElementById('tweet-1494685271387881472-785'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1494685271387881472&theme=dark" }

That could be explained by the fact that Bundler has to verify the Gemfile.lock file consistency (all the gems are installed). Thus, that's an expected behaviour (that doesn't mean we shouldn't try to improve it; see, for example, Matthew Draper's Gel).

Rails developers usually put all the deps in the Gemfile, including dev tools, such as RuboCop. RuboCop is a linter, and linters must be fast. RuboCop itself complies with this statement but running it via Bundler may not.

How can we overcome this? Using a separate Gemfile!

I've been using this technique for a long time for gems development—to speed up CI RuboCop runs (by installing only the linter dependencies). Here is my typical rubocop.gemfile:

# gemfiles/rubocop.gemfile
source "https://rubygems.org" do
  gem "rubocop-md", "~> 1.0"
  gem "rubocop-rspec"
  gem "standard", "~> 1.0"
end

To use it with Bundler, we need to specify the BUNDLER_GEMFILE env variable:

# first, install the deps
BUNDLE_GEMFILE=gemfiles/rubocop.gemfile bundle install

# then, run the executable
BUNDLE_GEMFILE=gemfiles/rubocop.gemfile bundle exec rubocop

This verbose approach works well enough for machines (CI), but not for humans: maintaining a separate lockfile and using env vars in development is far from the perfect user experience.

For Rails applications development, we came up with the following trick to run commands backed by custom gemfiles—adding a simple bin/whatever wrapper. Here is our bin/rubocop:

#!/bin/bash

cd $(dirname $0)/..

export BUNDLE_GEMFILE=./gemfiles/rubocop.gemfile
bundle check > /dev/null || bundle install

bundle exec rubocop $@

The magic $@ argument proxies everything you pass to bin/rubocop, thus, making this wrapper quack like RuboCop.

We also do bundle check || bundle install to make sure all the deps are present (so, you don't need to run bundle install yourself).

That's it.

P.S. Why not use inline gemfiles (as Xavier Noria suggested)? We could write our bin/rubocop like this:

require 'bundler/inline'

gemfile(true, quiet: true) do
  gem "rubocop-md", "~> 1.0"
  gem "rubocop-rspec"
  gem "standard", "~> 1.0"
end

require 'rubocop'
RuboCop::CLI.new.run

However, with this approach, there is no lockfile at all. We want to make sure everyone is using the same versions of dependencies (to avoid "works on my computer" situations). Of course, we can use the exact version in the gemfile do ... end block, but, IMO, managing deps with Bundler is more convenient (e.g., you can run bundle update).

P.P.S. One of the benefits of this approach is the ability to run linters (and other tools, e.g., Kuby) locally while using Docker for application development; no need to spin up containers to run RuboCop. It's especially helpful if you want to use Git hooks or editor integrations.

Rails-docker-box, or developing Rails within a dockerized environment

Vladimir Dementyev — Tue, 22 Mar 2022 13:13:25 +0000

⚠️ Attention! This post is not about using Docker to develop Rails applications, but about using Docker to develop the Rails framework itself. For the former one, please, visit the Ruby on Whales article.

From boxes to containers, or a bit of history

I've been contributing to Rails (from time to time) since 2015. Developing such a massive framework as Rails very differs from working on a web application built with it. First of all, you need to cover all the possible configurations: databases, cache servers, etc.; many system dependencies (e.g., libxml2 or ffmpeg) must be installed.

Secondly, unlike for a private project, where each team member has to deal with this setup, an open-source project should be...hm...open for everyone willing to contribute. The more complicated it is to configure a proper environment the more likely potential contributors would give up. And we don't want this, right?

Luckily, the Rails team (and Xavier Noria in particular) found a way to solve this problem—rails-dev-box. Rails Dev Box is a Vagrant configuration, which allows you to spin up a virtual machine with everything you need inside. Cool, right?

Yeah, that was really cool. In 2015.

I gave up on VM-based development in 2017, when I found that running a VM along with a couple of Electron-based apps no longer fit my laptop. I turned to containers.

Since then, I started using Docker not only for applications development but also for hacking around with Rails.

Since I mostly dealt with Active Record and Action Cable, my Docker configuration wasn't complete. Also, back in the days, the Rails codebase wasn't container-friendly (e.g., some tests relied on a Redis or PostgreSQL instance running on the same machine). Thus, I just kept my setup around (in a few commits], and haven't tried to promote to the upstream or whatever.

Lately, I've been working a new PR to Action Cable and had to re-visit my configuration (since many things have changed in the last year). I liked what I got in the end, so I decided to share it with the community.

Below is the compatibility table—which libraries are currently supported (i.e., rake test passes):

actioncable ✅
actionmailbox ✅
actionmailer ✅
actionpack ✅
actiontext ✅
actionview ✅
activejob ✅
activemodel ✅
activerecord:
- rake test:sqlite3 ✅ ⚠️: 26761 assertions, 2 failures, 2 errors, 27 skips (sqlite3: not found)
- rake test:postgresql ✅ ⚠️: 28766 assertions, 0 failures, 2 errors, 18 skips (couldn't connect to /var/run/postgresql/.s.PGSQL.5432)
- rake test:mysql2 🚫 (no mysql database configured)
activestorage ⚠️ (some system deps missing)
activesupport ✅ ⚠️ (evented file checker tests fail 🤔)
railties 🚫 (No such file or directory - yarn

NOTE: JavaScript tests are not supported (no Node/Yarn env configured).

Docker, Compose, and Dip walks into a bar

It's all started with just two files: Dockerfile and docker-compose.yml. Although that was good enough to "build" a project and run tests, the overall developer experience was barely satisfying.

So, I went the old-fashioned way and added Dip to the mix.
Now I can run all the familiar commands (bundle, rake, etc.) from my host system (with a dip prefix) without thinking about all the docker-compose --rm --it bla-bla. Moreover, I can cd into a subfolder (say, actioncable), and execute commands from there just like on a host machine:

# Installing deps at the project's root level
dip bundle install
# Run all Rails tests (I never tried 🙂)
dip rake test

# That's what I usually do
cd actioncable
# Install Action Cable dev deps
dip bundle
# Run Action Cable tests
dip rake
# Or run a particular test file
dip test test/connection/streams_test.rb

The dip test command is an alias for bundle exec ruby -Ilib:test—and that's my favourite one ♥️

Want to give this setup a try? You can grab it right from this post (or from the gist!

Here is the configuration I keep at the project's root:

.dockerdev/
  Aptfile
  .bashrc
  Dockerfile
  compose.yml
  # Active Record configs
  config.yml
<some rails files>
dip.yml

And the contents of all the files:

.dockerdev/Dockerfile

ARG RUBY_VERSION
ARG DISTRO_NAME=bullseye

FROM ruby:$RUBY_VERSION-slim-$DISTRO_NAME
ARG DISTRO_NAME

# Common dependencies
RUN apt-get update -qq \
  && DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
    build-essential \
    gnupg2 \
    curl \
    less \
    git \
  && apt-get clean \
  && rm -rf /tmp/* /var/tmp/* \
  && truncate -s 0 /var/log/*log

ARG PG_MAJOR
RUN curl -sSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
  && echo deb http://apt.postgresql.org/pub/repos/apt/ $DISTRO_NAME-pgdg main $PG_MAJOR > /etc/apt/sources.list.d/pgdg.list
RUN apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get -yq dist-upgrade && \
  DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
    libpq-dev \
    postgresql-client-$PG_MAJOR && \
    apt-get clean && \
    rm -rf /tmp/* /var/tmp/* && \
    truncate -s 0 /var/log/*log

# Application dependencies
# We use an external Aptfile for this, stay tuned
COPY Aptfile /tmp/Aptfile
RUN apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get -yq dist-upgrade && \
  DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
    $(grep -Ev '^\s*#' /tmp/Aptfile | xargs) && \
    apt-get clean && \
    rm -rf /tmp/* /var/tmp/* && \
    truncate -s 0 /var/log/*log

ENV LANG C.UTF-8
ENV GEM_HOME /bundle
ENV BUNDLE_PATH=$GEM_HOME \
  BUNDLE_APP_CONFIG=$BUNDLE_PATH \
  BUNDLE_BIN=$BUNDLE_PATH/bin \
  BUNDLE_JOBS=4 \
  BUNDLE_RETRY=3
ENV PATH /app/bin:$BUNDLE_BIN:$PATH

ARG BUNDLER_VERSION
RUN gem update --system && \
    gem install bundler

RUN mkdir -p /app
WORKDIR /app

CMD ["/usr/bin/bash"]

.dockerdev/Aptfile

vim
# Build tools
autoconf
libtool
libncurses5-dev
libxml2-dev
# ActiveRecord deps
libsqlite3-dev
default-libmysqlclient-dev

.dockerdev/compose.yml

x-app: &app
  build:
    context: .
    args:
      RUBY_VERSION: '3.0.2'
      PG_MAJOR: '14'
  image: rails-dev:7.1.0
  tmpfs:
    - /tmp

services:
  runner:
    <<: *app
    stdin_open: true
    tty: true
    volumes:
      - ..:/app:cached
      - bundle:/bundle
      - history:/usr/local/hist
      - ./.psqlrc:/root/.psqlrc:ro
      - ./.bashrc:/root/.bashrc:ro
    environment:
      REDIS_URL: redis://redis:6379/
      DATABASE_URL: postgres://postgres:postgres@postgres/
      HISTFILE: /usr/local/hist/.bash_history
      XDG_DATA_HOME: /app/tmp/caches
      EDITOR: vi
      # Use PostgreSQL by default for AR tests
      ARCONN: ${ARCONN:-postgresql}
    working_dir: ${WORK_DIR:-/app}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:14
    volumes:
      - .psqlrc:/root/.psqlrc:ro
      - postgres:/var/lib/postgresql/data
      - history:/user/local/hist
    environment:
      PSQL_HISTFILE: /user/local/hist/.psql_history
      POSTGRES_PASSWORD: postgres
      # For createdb
      PGPASSWORD: postgres
    ports:
      - 5432
    healthcheck:
      test: pg_isready -U postgres -h 127.0.0.1
      interval: 5s

  redis:
    image: redis:6.2-alpine
    volumes:
      - redis:/data
    ports:
      - 6379
    healthcheck:
      test: redis-cli ping
      interval: 1s
      timeout: 3s
      retries: 30

volumes:
  history:
  postgres:
  redis:
  bundle:

.dockerdev/.bashrc (put your favorite Bash extensions there)

alias be="bundle exec"

dip.yml

version: '7.1'

environment:
  WORK_DIR: /app/${DIP_WORK_DIR_REL_PATH}

compose:
  files:
    - .dockerdev/compose.yml
  project_name: rails_dev

interaction:
  # This command spins up a Rails container with the required dependencies (such as databases),
  # and opens a terminal within it.
  runner:
    description: Open a Bash shell within a Rails container (with dependencies up)
    service: runner
    command: /bin/bash

  # Run a Rails container without any dependent services (useful for non-Rails scripts)
  bash:
    description: Run an arbitrary script within a container (or open a shell without deps)
    service: runner
    command: /bin/bash
    compose_run_options: [ no-deps ]

  # A shortcut to run Bundler commands
  bundle:
    description: Run Bundler commands
    service: runner
    command: bundle
    compose_run_options: [ no-deps ]

  rake:
    description: Run Rake commands
    service: runner
    command: bundle exec rake

  ruby:
    description: Run Ruby with Bundler activated
    service: runner
    command: bundle exec ruby

  rubocop:
    description: Run RuboCop
    service: runner
    command: bundle exec rubocop
    compose_run_options: [ no-deps ]

  test:
    description: Run a single test file (an alias for ruby -Ilib:test)
    service: runner
    command: bundle exec ruby -Ilib:test

  psql:
    description: Run Postgres psql console
    service: postgres
    default_args: anycasts_dev
    command: psql -h postgres -U postgres

  createdb:
    description: Create a PostgreSQL database
    service: postgres
    command: createdb -h postgres -U postgres

  'redis-cli':
    description: Run Redis console
    service: redis
    command: redis-cli -h redis

provision:
  - dip compose down --volumes
  - dip compose up -d postgres redis
  - dip bundle install
  - (test -f activerecord/test/config.yml) || (cp .dockerdev/config.yml activerecord/test/config.yml)
  - dip createdb activerecord_unittest
  - dip createdb activerecord_unittest2

Bonus: Git ignore without `.gitignore`

The final question: since we keep it in the project's directory, and this is not an official setup (at least, yet), we need to make sure we do not accidentally commit it to the repo. In other words, how to Git-ignore our configuration without updating the .gitignore file? And the answer is—.git/info/exclude. That's a specific, local, Git configuration file, which works similarly to .gitignore. So, just open this file (say, code .git/info/exclude) and drop the following lines:

# .git/info/exclude

dip.yml
.dockerdev/

That's it!

P.S. For hacking with Ruby (MRI), I also have a dockerized environment: ruby-dip.

Climbing Steep hills, or adopting Ruby 3 types

Vladimir Dementyev — Fri, 11 Dec 2020 07:53:55 +0000

With Ruby 3.0 just around the corner, let's take a look at one of the highlights of the upcoming release: Ruby Type Signatures. Yes, types come to our favourite dynamic language—let's see what could work out of that!

It is not the first time I'm writing about types for Ruby: more than a year ago, I tasted Sorbet and shared my experience in the Martian Chronicles. At the end of the post, I promised to give another Ruby type checker a try: Steep. So, here I am, paying my debts!

I'd highly recommend taking a look at the "Sorbetting a gem" post first since I will refer to it multiple times today.

RBS in a nutshell

RBS is a language to describe the structure of Ruby programs (from Readme). The "structure" includes class and method signatures, type definitions, etc.

Since it's a separate language, not Ruby, separate .rbs files are used to store typings.

Let's jump right into an example:

# martian.rb
class Martian < Alien
  def initialize(name, evil: false)
    super(name)
    @evil = evil
  end

  def evil?
    @evil
  end
end

# martian.rbs
class Alien
  attr_reader name : String

  def initialize : (name: String) -> void
end

class Martian < Alien
  @evil : bool

  def initialize : (name: String, ?evil: bool) -> void
  def evil? : () -> bool
end

The signature looks pretty similar to the class definition itself, except that we have types specified for arguments, methods, and instance variables. So far, looks pretty Ruby-ish. However, RBS has some entities which are missing in Ruby, for example, interfaces. We're gonna see some examples later.

RBS itself doesn't provide any functionality to perform type checking*; it's just a language, remember? That's where Steep comes into a stage.

* Actually, that's not 100% true; there is runtime type checking mode. Continue reading to learn more.

In the rest of the article, I will describe the process of adding RBS and Steep to Rubanok (the same project as I used in the Sorbet example, though the more recent version).

Getting started with RBS

It could be hard to figure out how to start adding types to an existing project. Hopefully, RBS provides a way to generate a types scaffold for your code.

RBS comes with a CLI tool (rbs) which has a bunch of commands, but we're interested only in the prototype:

$ rbs prototype -h
Usage: rbs prototype [generator...] [args...]

Generate prototype of RBS files.
Supported generators are rb, rbi, runtime.

Examples:

  $ rbs prototype rb foo.rb
  $ rbs prototype rbi foo.rbi
  $ rbs prototype runtime String

The description is pretty self-explanatory; let's try it:

$ rbs prototype rb lib/**/*.rb

# Rubanok provides a DSL ... (all the comments from the source file) 
module Rubanok
  attr_accessor ignore_empty_values: untyped
  attr_accessor fail_when_no_matches: untyped
end

module Rubanok
  class Rule
    # :nodoc:
    UNDEFINED: untyped

    attr_reader fields: untyped
    attr_reader activate_on: untyped
    attr_reader activate_always: untyped
    attr_reader ignore_empty_values: untyped
    attr_reader filter_with: untyped

    def initialize: (untyped fields, ?activate_on: untyped activate_on, ?activate_always: bool activate_always, ?ignore_empty_values: untyped ignore_empty_values, ?filter_with: untyped? filter_with) -> untyped
    def project: (untyped params) -> untyped
    def applicable?: (untyped params) -> (::TrueClass | untyped)
    def to_method_name: () -> untyped

    private

    def build_method_name: () -> ::String
    def fetch_value: (untyped params, untyped field) -> untyped
    def empty?: (untyped val) -> (::FalseClass | untyped)
  end
end

# <truncated>

The first option (prototype rb) generates a signature for all the entities specified in the file (or files) you pass using static analysis (more precisely, via parsing the source code and analyzing ASTs).

This command streams to the standard output all the found typings. To save the output, one can use redirection:

rbs prototype rb lib/**/*.rb > sig/rubanok.rbs

I'd prefer to mirror signature files to source files (i.e., have multiple files). We can achieve this with some knowledge of Unix:

find lib -name \*.rb -print | cut -sd / -f 2- | xargs -I{} bash -c 'export file={}; export target=sig/$file; mkdir -p ${target%/*}; rbs prototype rb lib/$file > sig/${file/rb/rbs}'

In my opinion, it would be much better if we had the above functionality by default (or maybe that's a feature—keeping all the signatures in the same file 🤔).

Also, copying comments from source files to signatures makes the latter less readable (especially if there are many comments, like in my case). Of course, we can add a bit more Unix magic to fix this...

Let's try runtime mode:

$ RUBYOPT="-Ilib" rbs prototype runtime -r rubanok Rubanok::Rule

class Rubanok::Rule
  public

  def activate_always: () -> untyped
  def activate_on: () -> untyped
  def applicable?: (untyped params) -> untyped
  def fields: () -> untyped
  def filter_with: () -> untyped
  def ignore_empty_values: () -> untyped
  def project: (untyped params) -> untyped
  def to_method_name: () -> untyped

  private

  def build_method_name: () -> untyped
  def empty?: (untyped val) -> untyped
  def fetch_value: (untyped params, untyped field) -> untyped
  def initialize: (untyped fields, ?activate_on: untyped, ?activate_always: untyped, ?ignore_empty_values: untyped, ?filter_with: untyped) -> untyped
end

In this mode, RBS uses Ruby introspection APIs (Class.methods, etc.) to generate the specified class or module signature.

Let's compare signatures for the Rubanok::Rule class generated with rb and runtime modes:

First, runtime generator does not recognize attr_reader (for instance, activate_on and activate_always).
Second, runtime generator sorts methods alphabetically while static generator preserves the original layout.
Finally, the first signature has a few types defined, while the latter has everything untyped.

So, why one may find runtime generator useful? I guess there are only one reason for that: dynamically generated methods. Like, for example, in Active Record.

Thus, both modes have their advantages and disadvantages and using them both would provide a better signature coverage. Unfortunately, there is no good way to diff/merge RBS files yet; you have to that manually. Another manual work is to replace untyped with the actual typing information.

But wait to make your hands dirty. There is one more player in this game–Type Profiler.

Type Profiler infers a program type signatures dynamically during the execution. It spies all the loaded classes and methods and collects the information about which types have been used as inputs and outputs, analyzes this data, and produces RBS definitions. Under the hood, it uses a custom Ruby interpreter (so, the code is not actually executed). You can find more in the official docs.

The main difference between TypeProf and RBS is that we need to create a sample script to be used as a profiling entry-point.

Let's write one:

# sig/rubanok_type_profile.rb
require "rubanok"

processor = Class.new(Rubanok::Processor) do
  map :q do |q:|
    raw
  end

  match :sort_by, :sort, activate_on: :sort_by do
    having "status", "asc" do
      raw
    end

    default do |sort_by:, sort: "asc"|
      raw
    end
  end
end

processor.project({q: "search", sort_by: "name"})
processor.call([], {q: "search", sort_by: "name"})

Now, let's run typeprof command:

$ typeprof -Ilib sig/rubanok_type_profile.rb --exclude-dir lib/rubanok/rails --exclude-dir lib/rubanok/rspec.rb

# Classes
module Rubanok
  VERSION : String

  class Rule
    UNDEFINED : Object
    @method_name : String
    attr_reader fields : untyped
    attr_reader activate_on : Array[untyped]
    attr_reader activate_always : false
    attr_reader ignore_empty_values : untyped
    attr_reader filter_with : nil
    def initialize : (untyped, ?activate_on: untyped, ?activate_always: false, ?ignore_empty_values: untyped, ?filter_with: nil) -> nil
    def project : (untyped) -> untyped
    def applicable? : (untyped) -> bool
    def to_method_name : -> String
    private
    def build_method_name : -> String
    def fetch_value : (untyped, untyped) -> Object?
    def empty? : (nil) -> false
  end

  # ...
end

Nice, now we have some types defined (though most of them are still untyped), we can see methods visibility and even instance variables (something we haven't seen before). The order of methods stayed the same as in the original file—that's good!

Unfortunately, despite being a runtime analyzer, TypeProf has not so good metaprogramming support. For example, the methods defined using iteration won't be recognized:

# a.rb
class A
  %w[a b].each.with_index { |str, i| define_method(str) { i } }
end

p A.new.a + A.new.b

$ typeprof a.rb

# Classes
class A
end

(We can handle this with rbs prototype runtime 😉)

So, even if you have an executable that provides 100% coverage of your APIs but uses metaprogramming, using just TypeProf is not enough to build a complete types scaffold for your program.

To sum up, all three different ways to generate initial signatures have their pros and cons, but combining their results could give a very good starting point in adding types to existing code. Hopefully, we'll be able to automate this in the future.

In Rubanok's case, I did the following:

Generating initial signatures using rbs prototype rb.
Ran typeprof and used its output to add missing instance variables and update some signatures.
Finally, ran rbs prototype runtime for main classes.

While I was writing this article, a PR with attr_reader self.foo support has been merged.

The latter one helped to find a bug in the signature generated at the first step:

 module Rubanok
-  attr_accessor ignore_empty_values: untyped
-  attr_accessor fail_when_no_matches: untyped
+  def self.fail_when_no_matches: () -> untyped
+  def self.fail_when_no_matches=: (untyped) -> untyped
+  def self.ignore_empty_values: () -> untyped
+  def self.ignore_empty_values=: (untyped) -> untyped
 end

Introducing Steep

So far, we've only discussed how to write and generate type signatures. That would be useless if we don't add a type checker to our dev stack.

As of today, the only type checker supporting RBS is Steep.

`steep init`

Let's add the steep gem to our dependencies and generate a configuration file:

steep init

That would generate a default Steepfile with some configuration. For Rubanok, I updated it like this:

# Steepfile
target :lib do
  # Load signatures from sig/ folder
  signature "sig"
  # Check only files from lib/ folder
  check "lib"

  # We don't want to type check Rails/RSpec related code
  # (because we don't have RBS files for it)
  ignore "lib/rubanok/rails/*.rb"
  ignore "lib/rubanok/railtie.rb"
  ignore "lib/rubanok/rspec.rb"

  # We use Set standard library; its signatures
  # come with RBS, but we need to load them explicitly
  library "set"
end

`steep stats`

Before drowning in a sea of types, let's think of how we can measure our signatures' efficiency. We can use steep stats to see how good (or bad?) our types coverage is:

$ bundle exec steep stats --log-level=fatal

Target,File,Status,Typed calls,Untyped calls,All calls,Typed %
lib,lib/rubanok/dsl/mapping.rb,success,7,2,11,63.64
lib,lib/rubanok/dsl/matching.rb,success,26,18,50,52.00
lib,lib/rubanok/processor.rb,success,34,8,49,69.39
lib,lib/rubanok/rule.rb,success,24,12,36,66.67
lib,lib/rubanok/version.rb,success,0,0,0,0
lib,lib/rubanok.rb,success,8,4,12,66.67

This command outputs surprisingly outputs CSV 😯. Let's add some Unix magic and make the output more readable:

$ bundle exec steep stats --log-level=fatal | awk -F',' '{ printf "%-28s %-9s %-12s %-14s %-10s\n", $2, $3, $4, $5, $7 }'
File                         Status    Typed calls  Untyped calls  Typed %   
lib/rubanok/dsl/mapping.rb   success   7            2              63.64     
lib/rubanok/dsl/matching.rb  success   26           18             52.00     
lib/rubanok/processor.rb     success   34           8              69.39     
lib/rubanok/rule.rb          success   24           12             66.67     
lib/rubanok/version.rb       success   0            0              0         
lib/rubanok.rb               success   8            4              66.67

Ideally, we would like to have everything typed. So, I opened my .rbs files and started replacing untyped with the actual types one by one.

It took me about a dozen minutes to get rid of untyped definitions (most of them). I'm not going to describe this process in detail; it was pretty straightforward except for the one thing I'd like to pay attention to.

Let's recall what Rubanok is. It provides a DSL to define data (usually, user input) transformers of a form (input, params) -> input. A typical use case is to customize an Active Record relation depending on request parameters:

class PagySearchyProcess < Rubanok::Processor
  map :page, :per_page, activate_always: true do |page: 1, per_page: 20|
   # raw is a user input
   raw.page(page).per(per_page)
  end

  map :q do |q:|
    raw.search(q)
  end
end

PagySearchyProcessor.call(Post.all, {q: "rbs"})
#=> Post.search("rbs").page(1).per(20)

PagySearchyProcessor.call(Post.all, {q: "rbs", page: 2})
#=> Post.search("rbs").page(2).per(20)

Thus, Rubanok deals with two external types: input (which could be anything) and params (which is a Hash with String or Symbol keys). Also, we have a notion of field internally: a params key used to activate a particular transformation. A lot of Rubanok's methods use these three entities, and to avoid duplication, I decided to use the type aliases feature of RBS:

module Rubanok
  # Transformation parameters
  type params = Hash[Symbol | String, untyped]
  type field = Symbol
  # Transformation target (we assume that input and output types are the same)
  type input = Object?

  class Processor
    def self.call: (params) -> input
                 | (input, params) -> input
    def self.fields_set: () -> Set[field]
    def self.project: (params) -> params

    def initialize: (input) -> void
    def call: (params) -> input
  end

  class Rule
    attr_reader fields: Array[field]

    def project: (params) -> params
    def applicable?: (params) -> bool
  end

  # ...
end

That allowed me to avoid duplication and indicate that they are not just Hashes, Strings, or whatever passing around, but params, fields and inputs.

Now, let's check our signatures!

Fighting with signatures, or make `steep check` happy

It's very unlikely that we wrote 100% correct signatures right away. I got ~30 errors:

$ bundle exec steep check --log-level=fatal

lib/rubanok/dsl/mapping.rb:24:8: MethodArityMismatch: method=map (def map(*fields, **options, &block))
lib/rubanok/dsl/mapping.rb:38:10: NoMethodError: type=(::Object & ::Rubanok::DSL::Mapping::ClassMethods), method=define_method (define_method(rule.to_method_name, &block))
lib/rubanok/dsl/mapping.rb:40:10: NoMethodError: type=(::Object & ::Rubanok::DSL::Mapping::ClassMethods), method=add_rule (add_rule rule)
lib/rubanok/dsl/matching.rb:25:10: MethodArityMismatch: method=initialize (def initialize(id, fields, values = [], **options, &block))
lib/rubanok/dsl/matching.rb:26:26: UnexpectedSplat: type= (**options)
lib/rubanok/dsl/matching.rb:29:12: IncompatibleAssignment:  ... 
lib/rubanok/dsl/matching.rb:30:32: NoMethodError: type=::Array[untyped], method=keys (@values.keys)
lib/rubanok/dsl/matching.rb:42:8: MethodArityMismatch: method=initialize (def initialize(*, **))
lib/rubanok/dsl/matching.rb:70:8: MethodArityMismatch: method=match (def match(*fields, **options, &block))
lib/rubanok/dsl/matching.rb:71:17: IncompatibleArguments: ...
lib/rubanok/dsl/matching.rb:73:10: BlockTypeMismatch: ...
lib/rubanok/dsl/matching.rb:75:10: NoMethodError: type=(::Object & ::Rubanok::DSL::Matching::ClassMethods), method=define_method (define_method(rule.to_method_name) do |params = {}|)
lib/rubanok/dsl/matching.rb:83:12: NoMethodError: type=(::Object & ::Rubanok::DSL::Matching::ClassMethods), method=define_method (define_method(clause.to_method_name, &clause.block))
lib/rubanok/dsl/matching.rb:86:10: NoMethodError: type=(::Object & ::Rubanok::DSL::Matching::ClassMethods), method=add_rule (add_rule rule)
lib/rubanok/dsl/matching.rb:96:15: NoMethodError: type=(::Object & ::Rubanok::DSL::Matching), method=raw (raw)
lib/rubanok/processor.rb:36:6: MethodArityMismatch: method=call (def call(*args))
lib/rubanok/processor.rb:56:13: NoMethodError: type=(::Class | nil), method=<= (superclass <= Processor)
lib/rubanok/processor.rb:57:12: NoMethodError: type=(::Class | nil), method=rules (superclass.rules)
lib/rubanok/processor.rb:67:13: NoMethodError: type=(::Class | nil), method=<= (superclass <= Processor)
lib/rubanok/processor.rb:68:12: NoMethodError: type=(::Class | nil), method=fields_set (superclass.fields_set)
lib/rubanok/processor.rb:78:21: ArgumentTypeMismatch: receiver=::Hash[::Symbol, untyped], expected=::Array[::Symbol], actual=::Set[::Rubanok::field] (*fields_set)
lib/rubanok/processor.rb:116:6: NoMethodError: type=::Rubanok::Processor, method=input= (self.input =)
lib/rubanok/processor.rb:134:6: NoMethodError: type=::Rubanok::Processor, method=input= (self.input = prepared_input)
lib/rubanok/rule.rb:11:6: IncompatibleAssignment: ...
lib/rubanok/rule.rb:20:8: UnexpectedJumpValue (next acc)
lib/rubanok/rule.rb:48:12: NoMethodError: type=(::Method | nil), method=call (filter_with.call(val))
lib/rubanok/rule.rb:57:8: MethodArityMismatch: method=empty? (def empty?)
lib/rubanok/rule.rb:63:8: MethodArityMismatch: method=empty? (def empty?)
lib/rubanok/rule.rb:69:4: MethodArityMismatch: method=empty? (def empty?(val))

Let's take a closer look at these errors and try to fix them.

1. Refinements always break things.

Let's start with the last three reported errors:

lib/rubanok/rule.rb:57:8: MethodArityMismatch: method=empty? (def empty?)
lib/rubanok/rule.rb:63:8: MethodArityMismatch: method=empty? (def empty?)
lib/rubanok/rule.rb:69:4: MethodArityMismatch: method=empty? (def empty?(val))

Why Steep detected three #empty? methods in the Rule class? It turned out that it considers an anonymous refinement body to be a part of the class body:

using(Module.new do
  refine NilClass do
    def empty?
      true
    end
  end

  refine Object do
    def empty?
      false
    end
  end
end)

def empty?(val)
  return false unless ignore_empty_values

  val.empty?
end

I submitted an issue and moved refinements to the top of the file to fix the errors.

2. Superclass don't cry 😢

Another interesting issue relates to superclass usage:

lib/rubanok/processor.rb:56:13: NoMethodError: type=(::Class | nil), method=<= (superclass <= Processor)
lib/rubanok/processor.rb:57:12: NoMethodError: type=(::Class | nil), method=rules (superclass.rules)
lib/rubanok/processor.rb:67:13: NoMethodError: type=(::Class | nil), method=<= (superclass <= Processor)

The corresponding source code:

@rules =
  if superclass <= Processor
    superclass.rules.dup
  else
    []
  end

It's a very common pattern to inherit class properties. Why doesn't it work? First, the superclass signature says the result is either Class or nil (though it could be nil only for the BaseObject class, as far as I know). Thus, we cannot use <= right away (because it's not defined on NilClass.

Even if we unwrap superclass, the problem with .rules would still be there—Steep's flow sensitivity analysis currently doesn't recognize the <= operator. So, I decided to hack the system and explicitly define the .superclass signature for the Processor class:

# processor.rbs
class Processor
  def self.superclass: () -> singleton(Processor)
  # ...
end

This way, my code stays the same; only the types suffer 😈.

3. Explicit over implicit: handling splats.

So far, we've seen pretty much the same problems as I had with Sorbet. Let's take a look at something new.

Consider this code snippet:

def project(params)
  params = params.transform_keys(&:to_sym)
  # params is a Hash, fields_set is a Set
  params.slice(*fields_set)
end

It produces the following type error:

lib/rubanok/processor.rb:78:21: ArgumentTypeMismatch: receiver=::Hash[::Symbol, untyped], expected=::Array[::Symbol], actual=::Set[::Rubanok::field]

The Hash#slice method expects an Array, but we pass a Set. However, we also use a splat (*) operator, which implicitly tries to convert an object to an array—seems legit, right? Unfortunately, Steep is not so smart yet: we have to add an explicit #to_a call.

4. Explicit over implicit, pt. 2: forwarding arguments.

I used the following pattern in a few places:

def match(*fields, **options, &block)
  rule = Rule.new(fields, **options)

  # ...
end

A DSL method accepts some options as keyword arguments and then pass them to the Rule class initializer. The possible options are strictly defined and enforced in the Rule#initialize, but we would like to avoid declaring them explicitly just to forward down. Unfortunately, that's only possible if we declare **options as untyped—that would make signatures kinda useless.

So, we have to become more explicit once again:

-        def map(*fields, **options, &block)
-          filter = options[:filter_with]
-          rule = Rule.new(fields, **options)

+        def map(*fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil, &block)
+          filter = filter_with
+          rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always, ignore_empty_values: ignore_empty_values, filter_with: filter_with)

# and more...

I guess it's time to add Ruby Next and use shorthand Hash notation 🙂

5. Variadic arguments: annotations to the rescue!

In the recent Rubanok release, I added an ability to skip input for transformations and only use params as the only #call method argument. That led to the following code:

def call(*args)
  input, params =
  if args.size == 1
    [nil, args.first]
  else
    args
  end

  new(input).call(params)
end

As in the previous case, we needed to make our signature more explicit and specify the actual arguments instead of the *args:

# This is our signature
# (Note that we can define multiple signatures for a method)
def self.call: (input, params) -> input
             | (params) -> input

# And this is our code (first attempt)
UNDEFINED = Object.new

def call(input, params = UNDEFINED)
  input, params = nil, input if params == UNDEFINED

  raise ArgumentError, "Params could not be nil" if params.nil?

  new(input).call(params)
end

This refactoring doesn't pass the type check:

$ bundle exec steep lib/rubanok/processor.rb

lib/rubanok/processor.rb:43:24: ArgumentTypeMismatch: receiver=::Rubanok::Processor, expected=::Rubanok::params, actual=(::Rubanok::input | ::Rubanok::params | ::Object) (params)

So, according to Steep, param could be pretty match anything :( We need to help Steep to make the right decision. I couldn't find a way to do that via RBS, so my last resort was to use annotations.

Yes, even though RBS itself is designed not to pollute your source code, Steep allows you to do that. And in some cases, that's the necessary evil.

I came up with the following:

def call(input, params = UNDEFINED)
  input, params = nil, input if params == UNDEFINED

  raise ArgumentError, "Params could not be nil" if params.nil?

  # @type var params: untyped
  new(input).call(params)
end

We declare params as untyped to silence the error. The #call method signature guarantees that the params variable satisfies the params type requirements, so we should be safe here.

6. Deal with metaprogramming: interfaces.

Since Rubanok provides a DSL, it heavily uses metaprogramming.
For example, we use #define_method to dynamically generate transformation methods:

def map(*fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil, &block)
  # ...
  rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always, ignore_empty_values: ignore_empty_values, filter_with: filter_with)

  define_method(rule.to_method_name, &block)

  add_rule rule
end

And that's the error we see when running steep check:

lib/rubanok/dsl/mapping.rb:38:10: NoMethodError: type=(::Object & ::Rubanok::DSL::Mapping::ClassMethods), method=define_method (define_method(rule.to_method_name, &block))
lib/rubanok/dsl/mapping.rb:40:10: NoMethodError: type=(::Object & ::Module & ::Rubanok::DSL::Mapping::ClassMethods), method=add_rule (add_rule rule)

Hmm, looks like our type checker doesn't know that we're calling the .map method in the context of the Processor class (we call Processor.extend DSL::Mapping).

RBS has a concept of a self type for module: a self type adds requirements to the classes/modules, which include/prepend/extend this module. For example, we can state that we only allow using Mapping::ClassMethods to extend modules (and not objects, for example):

# Module here is a self type
module ClassMethods : Module
  # ...
end

That fixes NoMethodError for #define_method, but we still have it for #add_rule—this is a Processor self method. How can we add this restriction using module self types? It's not allowed to use singleton(SomeClass) as a self type; only classes and interfaces are allowed. Yes, RBS has interfaces! Let's give them a try!

We only use the #add_rule method in the modules, so we can define an interface as follows:

interface _RulesAdding
  def add_rule: (Rule rule) -> void
end

# Then we can use this interface in the Processor class itself
class Processor
  extend _RulesAdding

  # ...
end

# And in our modules
module Mapping
  module ClassMethods : Module, _RulesAdding
    # ...
  end
end

7. Making Steep happy.

Other problems I faced with Steep which I converted into issues:

Method visibility false negatives

Inability to declare block return values in some cases

I added a few more changes to the signatures and the source code to finally make a steep check pass. The journey was a bit longer than I expected, but in the end, I'm pretty happy with the result—I will continue using RBS and Steep.

Here is the final stats for Rubanok:

File                         Status    Typed calls  Untyped calls  Typed %   
lib/rubanok/dsl/mapping.rb   success   11           0              100.00    
lib/rubanok/dsl/matching.rb  success   54           2              94.74     
lib/rubanok/processor.rb     success   52           2              96.30     
lib/rubanok/rule.rb          success   31           2              93.94     
lib/rubanok/version.rb       success   0            0              0         
lib/rubanok.rb               success   12           0              100.00

Runtime type checking with RBS

Although RBS doesn't provide static type checking capabilities, it comes with runtime testing utils. By loading a specific file (rbs/test/setup), you can ask RBS to watch the execution and check that method calls inputs and outputs satisfy signatures.

Under the hood, TracePoint API is used along with the alias method chain trick to hijack observed methods. Thus, it's meant for use in tests, not in production.

Let's try to run our RSpec tests with runtime checking enabled:

$ RBS_TEST_TARGET='Rubanok::*' RUBYOPT='-rrbs/test/setup' bundle exec rspec --fail-fast

I, [2020-12-07T21:07:57.221200 #285]  INFO -- : Setting up hooks for ::Rubanok
I, [2020-12-07T21:07:57.221302 #285]  INFO -- rbs: Installing runtime type checker in Rubanok...
...

Failures:

  1) Rails controllers integration PostsApiController#planish implicit rubanok with matching
     Failure/Error: prepare! unless prepared?

     RBS::Test::Tester::TypeError:
       TypeError: [Rubanok::Processor#prepared?] ReturnTypeError: expected `bool` but returns `nil`

Oh, we forgot to initialize the @prepared instance variable with the boolean value! Nice!

When I tried to use RBS runtime tests for the first time, I encountered a few severe problems. Many thanks to Soutaro Matsumoto for fixing all of them faster than I finished working on this article!

I found a couple of more issues by using rbs/test/setup, including the one I wasn't able to resolve:

Failure/Error: super(fields, activate_on: activate_on, activate_always: activate_always)

RBS::Test::Tester::TypeError:
  TypeError: [Rubanok::Rule#initialize] UnexpectedBlockError: unexpected block is given for `(::Array[::Rubanok::field] fields, ?filter_with: ::Method?, ?ignore_empty_values: bool, ?activate_always: bool, ?activate_on: ::Rubanok::field | ::Array[::Rubanok::field]) -> void`

And here is the reason:

class Clause < Rubanok::Rule
  def initialize(id, fields, values, **options, &block)
    # The block is passed to super implicitly,
    # but is not acceptable by Rule#initialize
    super(fields, **options)
  end
end

I tried to use &nil to disable block propagation, but that broke steep check 😞. I submitted an issue and excluded Rule#initialize from the runtime checking for now using a special comment in the .rbs file:

# rule.rbs
class Rule
  # ...
  %a{rbs:test:skip} def initialize: (
    Array[field] fields,
    ?activate_on: field | Array[field],
    ?activate_always: bool,
    ?ignore_empty_values: bool,
    ?filter_with: Method?
  ) -> void
end

Bonus: Steep meets Rake

I usually run be rake pretty often during development to make sure that everything is correct. The default task usually includes RuboCop and tests.

Let's add Steep to the party:

# Rakefile

# other tasks

task :steep do
  # Steep doesn't provide Rake integration yet,
  # but can do that ourselves 
  require "steep"
  require "steep/cli"

  Steep::CLI.new(argv: ["check"], stdout: $stdout, stderr: $stderr, stdin: $stdin).run
end

namespace :steep do
  # Let's add a user-friendly shortcut
  task :stats do
    exec %q(bundle exec steep stats --log-level=fatal | awk -F',' '{ printf "%-28s %-9s %-12s %-14s %-10s\n", $2, $3, $4, $5, $7 }')
  end
end

# Run steep before everything else to fail-fast
task default: %w[steep rubocop rubocop:md spec]

Bonus 2: Type Checking meets GitHub Actions

As the final step, I configure GitHub Actions to run both static and runtime type checks:

# lint.yml
jobs:
  steep:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: ruby/setup-ruby@v1
      with:
        ruby-version: 2.7
    - name: Run Steep check
      run: |
        gem install steep
        steep check

# rspec.yml
jobs:
  rspec:
    # ...
    steps:
      # ...
    - name: Run RSpec with RBS
      if: matrix.ruby == '2.7'
      run: |
        gem install rbs
        RBS_TEST_TARGET="Rubanok::*" RUBYOPT="-rrbs/test/setup" bundle exec rspec --force-color
    - name: Run RSpec without RBS
      if: matrix.ruby != '2.7'
      run: |
        bundle exec rspec --force-color

Although there are still enough rough edges, I enjoyed using RBS/Steep a bit more than "eating" Sorbet (mostly because I'm not a big fan of type annotations in the source code). I will continue adopting Ruby 3 types in my OSS projects and reporting as many issues to RBS/Steep as possible 🙂.

P.S. You can find the source code in this PR.

Reusable Docker development environment

Vladimir Dementyev — Thu, 19 Nov 2020 08:38:27 +0000

So far, I've been only talking about Docker for development in the context of web applications, i.e., something involving multiple services and specific system dependencies. Today, I'd like to look at the other side and discuss how containerization could help me work on libraries.

Once upon a time...

A recent discussion in our corporate (Evil Martians) Slack triggered me to write this post finally: my colleagues discussed a new tool to manage multiple Node.js versions on the same machine (like nvm but written in Rust—you know, things get cooler when rewritten in Rust 😉).

My first thought was: "Why on Earth in 2020, we still need all these version managers, such as rbenv, nvm, asdf, whatever?" I almost forgot the pleasure of using them: my computer breathes easy without all the environmental pollution these tools bring.

Let's do a twist and talk about my monolithic personal computer (or laptop).

Slides from my Between monoliths and microservices RailsConf talk

About a year ago, I switched to a new laptop. Since I'm not a big fan of backups and other time machines, I had to craft a comfortable working environment from scratch. Instead of installing all the runtimes I usually use (Ruby, Golang, Erlang, Node), I decided to experiment and go with Docker for everything: applications and libraries, commercial and open-source projects. In other words, I only installed Git, Docker, and Dip.

I decided to use Docker for everything: applications and libraries, commercial and open-source projects.

Phase 0: Universal `docker-compose.yml`

You may think that keeping a Docker4Dev configuration (like the one described in the Ruby on Whales post) for every tiny library is a bunch of overhead. Yep, that's true. So, I started with a shared docker-compose.yml configuration, containing a service per project and sharing volumes between them (thus, I didn't have to install all the dependencies multiple times).

Launching a container looked like this:

docker-compose -f ~/dev/docker-compose.yml \
  run --rm some_service

# we can omit -f if our project is somewhere inside the ~/dev folder: docker-compose tries to find the first docker-compose.yml up the tree
docker-compose run --rm some_service

# finally, using an alias
dcr some_service

Not so bad. The only problem is that I had to define a service every time I wanted to run a new project within Docker. I continued investigating and came up with the Reusable Docker Environment (RDE) concept.

Phase 1 (discarded): RDE

The idea of RDE was to completely eliminate the need for Dockerfile and docker-compose.yml files and generate them on-the-fly using predefined templates (or executors).

This is how I imagined it to work:

# Open the current folder within a Ruby executor
$ rde -e ruby
root@1123:/app#

# Execute a command within a JRuby executor
$ rde run -e jruby -- ruby -e "puts RUBY_PLATFORM"
java

This idea left in a gist to gather dust.

Phase 2 (current): Back to `docker-compose.yml` with Dip

It turned out that solving the duplication problem could be done without building a yet-another tool (even in Rust 😉). After discussing the RDE concept with Mikhail Merkushin, we realized that a similar functionality could be achieved with Dip if we add a couple of features:

Lookup configurations in parent directories (so, we can use a single ~/dip.yml for all projects).
Provide an environment variable containing the relative path to the current directory from the configuration directory (so we can use it as a dynamic working_dir).

These features have been added in v5.0.0 (thanks to Misha), and I started exploring the new possibilities.

Let's skip all the intermediate states and finally take a look at the final configuration.

Currently, my ~/dip.yml only contains different Rubies and databases:

version: '5.0'

compose:
  files:
    - ./.dip/docker-compose.yml
  project_name: shared_dip_env

interaction:
  ruby: &ruby
    description: Open Ruby service terminal
    service: ruby
    command: /bin/bash
  jruby:
    <<: *ruby
    service: jruby
  'ruby:latest':
    <<: *ruby
    service: ruby-latest
  psql:
    description: Run psql console
    service: postgres
    command: psql -h postgres -U postgres
  createdb:
    description: Run PostgreSQL createdb command
    service: postgres
    command: createdb -h postgres -U postgres
  'redis-cli':
    description: Run Redis console
    service: redis
    command: redis-cli -h redis

Whenever I want to work on a Ruby gem, I just launched dip ruby from the project's directory and run all the commands (e.g., bundle install, rake) within a container:

~ $ cd ~/my_ruby_project
~/my_ruby_project $ dip ruby:latest

[../my_ruby_project] ruby -v
ruby 3.0.0dev (2020-10-20T12:46:54Z master 451836f582) [x86_64-linux]

See, I can run Ruby 3 without any hassle 🙂

There is only one special trick I have in the docker-compose.yml which allows me to re-use the same container for all projects without manual volumes mounting—PWD! Yes, all you need is PWD, the absolute path to the current working directory on the host machine. Here is how I use this sacred knowledge in my configuration:

version: '2.4'

services:
  ruby: &ruby
    command: bash
    image: ruby:2.7
    volumes:
      # That's all the magic!
      - ${PWD}:/${PWD}:cached
      - bundler_data:/usr/local/bundle
      - history:/usr/local/hist
      # I also mount different configuration files
      # for better DX
      - ./.bashrc:/root/.bashrc:ro
      - ./.irbrc:/root/.irbrc:ro
      - ./.pryrc:/root/.pryrc:ro
    environment:
      DATABASE_URL: postgres://postgres:postgres@postgres:5432
      REDIS_URL: redis://redis:6379/
      HISTFILE: /usr/local/hist/.bash_history
      LANG: C.UTF-8
      PROMPT_DIRTRIM: 2
      PS1: '[\W]\! '
      # Plays nice with gemfiles/*.gemfile files for CI
      BUNDLE_GEMFILE: ${BUNDLE_GEMFILE:-Gemfile}
    # And that's the second part of the spell
    working_dir: ${PWD}
    tmpfs:
      - /tmp
  jruby:
    <<: *ruby
    image: jruby:latest
    volumes:
      - ${PWD}:/${PWD}:cached
      - bundler_jruby:/usr/local/bundle
      - history:/usr/local/hist
      - ./.bashrc:/root/.bashrc:ro
      - ./.irbrc:/root/.irbrc:ro
      - ./.pryrc:/root/.pryrc:ro
  ruby-latest:
    <<: *ruby
    image: rubocophq/ruby-snapshot:latest
    volumes:
      - ${PWD}:/${PWD}:cached
      - bundler_data_edge:/usr/local/bundle
      - history:/usr/local/hist
      - ./.bashrc:/root/.bashrc:ro
      - ./.irbrc:/root/.irbrc:ro
      - ./.pryrc:/root/.pryrc:ro
  postgres:
    image: postgres:11.7
    volumes:
      - history:/usr/local/hist
      - ./.psqlrc:/root/.psqlrc:ro
      - postgres:/var/lib/postgresql/data
    environment:
      PSQL_HISTFILE: /usr/local/hist/.psql_history
      POSTGRES_PASSWORD: postgres
      PGPASSWORD: postgres
    ports:
      - 5432
  redis:
    image: redis:5-alpine
    volumes:
      - redis:/data
    ports:
      - 6379
    healthcheck:
      test: redis-cli ping
      interval: 1s
      timeout: 3s
      retries: 30

volumes:
  postgres:
  redis:
  bundler_data:
  bundler_jruby:
  bundler_data_edge:
  history:

Whenever I need PostgreSQL or Redis to build the library, I do the following:

# Launch PostgreSQL in the background
dip up -d postgres
# Create a database
dip createdb my_library_db
# Run psql
dip psql
# And, for example, run tests
dip ruby -c "bundle exec rspec"

Databases "live" within the same Docker network as other containers (since we're using the same docker-compose.yml) and accessible via their names (postgres and redis). My code should only recognize the DATABASE_URL and REDIS_URL, respectively.

Let's consider a few more examples.

Using with VS Code

If you're a VC Code user and want to use the power of IntelliSense, you can combine this approach with Remote Containers: just run dip up -d ruby and attach to a running container!

Node.js example: Docsify

Let's take a look at beyond-Ruby example: running Docsify documentation servers.

Docsify is a JavaScript / Node.js documentation site generator. I'm using it for all my open-source projects. It requires Node.js and the docsify-cli package to be installed. But we don't to install anything, remember? Let's pack it into Docker!

First, we declare a base Node service in our docker-compose.yml:

services:
  # ...
  node: &node
    image: node:14
    volumes:
      - ${PWD}:/${PWD}:cached
      # Where to store global packages
      - npm_data:${NPM_CONFIG_PREFIX}
      - history:/usr/local/hist
      - ./.bashrc:/root/.bashrc:ro
    environment:
      NPM_CONFIG_PREFIX: ${NPM_CONFIG_PREFIX}
      HISTFILE: /usr/local/hist/.bash_history
      PROMPT_DIRTRIM: 2
      PS1: '[\W]\! '
    working_dir: ${PWD}
    tmpfs:
      - /tmp

It's recommended to keep global dependencies in a non-root user directory. Also, we want to make sure we "cache" these packages by putting them into a volume.

We can define the env var (NPM_CONFIG_PREFIX) in the Dip config:

# dip.yml
environment:
  NPM_CONFIG_PREFIX: /home/node/.npm-global

Since we want to run a Docsify server to access a documentation website, we need to expose ports. Let's define a separate service for that and also define a command to run a server:

services:
  # ...
  node: &node
    # ...

  docsify:
    <<: *node
    working_dir: ${NPM_CONFIG_PREFIX}/bin
    command: docsify serve ${PWD}/docs -p 5000 --livereload-port 55729
    ports:
      - 5000:5000
      - 55729:55729

To install the docsify-cli package globally, we should run the following command:

dip compose run node npm i docsify-cli -g

We can simplify the command a bit if we define the node command in the dip.yml:

interaction:
  # ...
  node:
    description: Open Node service terminal
    service: node

Now we can type fewer characters: dip node npm i docsify-cli -g 🙂

Now to run a Docsify server we just need to invoke dip up docsify in the project's folder.

Erlang example: keeping build artifacts

The final example I'd like to share is from the world of compiled languages—let's talk some Erlang!

As before, we define a service in the docker-compose.yml and the corresponding shortcut in the dip.yml:

# docker-compose.yml
services:
  # ...
  erlang: &erlang
    image: erlang:23
    volumes:
      - ${PWD}:/${PWD}:cached
      - rebar_cache:/rebar_data
      - history:/usr/local/hist
      - ./.bashrc:/root/.bashrc:ro
    environment:
      REBAR_CACHE_DIR: /rebar_data/.cache
      REBAR_GLOBAL_CONFIG_DIR: /rebar_data/.config
      REBAR_BASE_DIR: /rebar_data/.project-cache${PWD}
      HISTFILE: /usr/local/hist/.bash_history
      PROMPT_DIRTRIM: 2
      PS1: '[\W]\! '
    working_dir: ${PWD}
    tmpfs:
      - /tmp

# dip.yml
interactions:
  # ...
  erl:
    description: Open Erlang service terminal
    service: erlang
    command: /bin/bash

What differs this configuration from the Ruby one is that we the same pwd trick to store dependencies and build files:

REBAR_BASE_DIR: /rebar_data/.project-cache${PWD}

That change the default _build location to the one within the mounted volume (and ${PWD} ensures we have no collisions with other projects).

This helps us to speed up the compilation by not writing to the host (which is especially useful for MacOS users).

Bonus: multiple compose files

One benefit of using Dip is the ability to specify multiple compose files to load services from. That allows us to group services by their nature and avoid putting everything into the same docker-compose.yml:

# dip.yml
compose:
  files:
    - ./.dip/docker-compose.base.yml
    - ./.dip/docker-compose.databases.yml
    - ./.dip/docker-compose.ruby.yml
    - ./.dip/docker-compose.node.yml
    - ./.dip/docker-compose.erlang.yml
  project_name: shared_dip_env

That's it! The example setup could be found in a gist. Feel free to use and share your feedback!

P.S. I should admit that my initial plan of not installing anything on a local machine failed: I gave up and ran brew install ruby (though that was long before the Phase 2).

P.P.S. Recently, I got access to GitHub Codespaces. I still haven't figured out all the details, but it looks like it could become my first choice for library development in the future (and the hacks described in this post will no longer be needed 🙂).

Smooth PostgreSQL upgrades in DockerDev environments with Lefthook

Vladimir Dementyev — Wed, 30 Sep 2020 16:38:25 +0000

It's not a secret that I'm a big fan of Docker for local development: I'm building large Rails apps with it and hacking Ruby itself.

The main reason why I love Dockerized environments is the simplicity of synchronizing configuration between developers/machines: all you need is to update a Dockerfile or docker-compose.yml and bump an image version.

Unfortunately, that's not always the case: imaging a situation of upgrading a database (PostgreSQL in our case) to a new major version. Simply changing postgres:12 to postgres:13 would break our dev env:

FATAL: database files are incompatible with server

Let's see how we can make such upgrades painless with the help of Lefthook.

Upgrading PostgreSQL in Docker

Although PostgreSQL has an official upgrade tool (pg_upgrade), it's hardly possible to use it with Docker since it requires both versions of PostgreSQL to be installed on the same machine:

Upgrading between major versions? #37

roosmaa posted on Nov 23, 2014

There doesn't seem to be a good way to upgrade between major versions of postgres. When sharing the volume with a new container with a newer version of postgres it won't run as the data directory hasn't been upgraded. pg_upgrade on the other hand requires (?) old installation binary files, so upgrading the data files from new server container is also difficult.

It would be nice if there was some suggested way of doing this in the readme. Maybe even some meta container which does the upgrading from version to version?

View on GitHub

You can find a straightforward workaround in the linked thread: create a SQL dump with the previous version and restore it into the new one. Let's do that!

First, we need to update our docker-compose.yml to define two PostgreSQL services (see Ruby on Whales for the complete configuration):

services:
  # ...
  # That's the old version of a service
  postgres-old:
    image: postgres:12
    volumes:
      - .psqlrc:/root/.psqlrc:ro
      - postgres:/var/lib/postgresql/data
      - ./log:/root/log:cached
    environment:
       PSQL_HISTFILE: /root/log/.psql_history
       POSTGRES_PASSWORD: postgres
    healthcheck:
      test: pg_isready -U postgres -h 127.0.0.1
      interval: 5s

  postgres:
    image: postgres:13
    volumes:
       - ./.psqlrc:/root/.psqlrc:ro
       # NOTE: we have a version suffix in a new volume name
       - postgres12:/var/lib/postgresql/data
       - ../log:/root/log:cached
     environment:
       PSQL_HISTFILE: /root/log/.psql_history
       POSTGRES_PASSWORD: postgres
     ports:
       - 5432
     healthcheck:
      test: pg_isready -U postgres -h 127.0.0.1
      interval: 5s

volumes:
  - postgres
  - postgres12
  # ...

NOTE: If you using PostgreSQL tools in your application container, you also need to upgrade them:

  app: &app
    build:
      context: .dockerdev
      dockerfile: Dockerfile
      args:
        RUBY_VERSION: '2.6.3'
-       PG_MAJOR: '12'
+       PG_MAJOR: '13' 
        NODE_MAJOR: '11'
        YARN_VERSION: '1.13.0'
        BUNDLER_VERSION: '2.0.2'
    # IMPORTANT: Bump a minor version of a dev image
    # to re-build it for everyone
-   image: my-app-dev:1.0.0
+   image: my-app-dev:1.1.0
    tmpfs:
      - /tmp

Now, let's start our postgres services and "migrate" the data:

# make sure containers are not running
docker-compose stop

# then, start them
docker-compose up -d postgres-old postgres

# make sure that both containers are up and running (e.g., via `docker ps`)
# that could take some time, because we need to download a new image

# finally, run the migration command
docker exec my-app-dev_postgres-old_1 pg_dumpall -U postgres | \
  docker exec -i my-app-dev_postgres_1 psql -U postgres

NOTE: Replace my-app with your Docker Compose project name.

The last command looks a bit complicated and requires some hidden knowledge: the names of the PostgreSQL containers.

If you're using Dip (like I do), you can define custom commands instead:

# dip.yml

interaction:
  # ...
  psql:
    description: Run psql console
    service: postgres
    default_args: zipline_light_development
    command: env PGPASSWORD=postgres psql -h postgres -U postgres -d
  pg_dump_old:
    description: Dump a database for a previous PostgreSQL version
    service: postgres-old
    command: pg_dumpall -U postgres -h postgres-old

And now the migration command transforms into:

dip pg_dump_old | dip psql

Hopefully, the process above succeeds, and you get all your
local data successfully migrated.

Now, let's talk about how to automate this process and help your co-workers to avoid this not-so-pleasant experience.

Automating upgrades with Lefthook

Lefthook is my top choice for managing Git hooks.
Which hook could help us solve the problem? I think the post-checkout hook is a good fit here: whenever a user switches to a branch with the upgraded PostgreSQL, we can automatically perform the required migration actions.

Let's create a new script under .lefthook/post-checkout called postgres-upgrade:

#!/bin/bash

# Do not run for irrelevant checkout (i.e., when we do `git checkout` but do not switch branches)
BRANCH_CHANGE=$3
[[ $BRANCH_CHANGE -eq 0 ]] && exit
PREV_HEAD=$1
CURR_HEAD=$2
[ $PREV_HEAD == $CURR_HEAD ] && exit

# Only run when Dip is installed: users without Dip are likely not using Docker dev env at all.
if ! which dip >/dev/null; then
  exit 0
fi

# Only run if Docker is running
if ! $(docker info > /dev/null 2>&1); then
  echo "Docker is not running. Skipping postgres-upgrade hook"
  exit 0
fi

# If there is no new postgres volume, then we haven't used a branch with the upgrade before
if docker volume ls | grep my-app-dev_postgres13 >/dev/null; then
  # Already created
  exit 0
fi

# Drop the old container if any (otherwise, there could be a conflict when we mount a folder with a new version)
if docker container ls | grep my-app-dev_postgres_1 > /dev/null; then
  dip compose rm -f postgres
fi

echo "Preparing a new PostgreSQL container to upgrade to version 13..."

dip up -d postgres-old postgres

# Wait for a new container to become healthy
until docker container ls | grep my-app-dev_postgres_1 | grep healthy;
  do
    sleep 1
  done

echo "Migrating data from the old PostgreSQL instance to a new one..."

dip pg_dump_old | dip psql

# Stop the old container, we don't need it anymore
dip stop postgres-old

echo "Done ✅"

exit 0

Finally, let's add our script to the Lefthook configuration:

post-checkout:
  scripts:
    postgres-upgrade:
      runner: "bash"

NOTE: If that's the first post-checkout hook, you also need to run lefthook install to activate it.

That's it!

Cables profiling returns: GC.compact & jemalloc

Vladimir Dementyev — Fri, 28 Aug 2020 10:49:03 +0000

This post introduces a new series—Unfinished plays. I have many drafts and incomplete posts I do not plan to finish in the nearest future. Since they still could be interesting/helpful to the community, I decided to release them almost as-is. This is the first one.

In the first part, we compared Action Cable memory usage with different VM configurations: MALLOC_ARENA_MAX, malloc_trim. I promised to continue researching in this direction and evaluate GC.compact and jemalloc (via Fullstaq Ruby) as well. So, here we are.

The Benchmark

This time I decided to analyze a little bit different scenario: "A sudden attack during a constant pressure".

"Constant pressure" means a uniform load: clients are connecting, communicating, and disconnecting during the benchmark, but the total number of concurrent users stays about the same.

I have a specific tool for writing such scenarios called wsdirector. It allows you to define a scenario in YML format and run it using a different scale factor.

"A sudden attack" emulates a situation when the number of concurrent connections unexpectedly spikes and then returns to normal. We do that by performing the "WebSocket shootout" scenario from the first part.

The source code of the benchmark is available here: https://github.com/anycable/simple-cable-app (see simiulate.yml and simulate.rb).

The server is running within a Docker container. During the benchmark, we capture the container's memory usage and generate a chart in the end (with the help of the awesome unicode_plot library, see monitor_docker.rb).

The exact command I used for the benchmarks below is as follows:

# first, start the app
dip up rails

# or for Fullstaq
dip up rails-fs

# or for Fullstaq with malloc_trim
dip up rails-fs-trim

# pressure
TOTAL=20 SAMPLE=50 N=4 SCALE=200 ruby benchmarks/simulate.rb

# spike (runs twice during the pressure)
cat benchmarks/broadcast.opts | xargs websocket-bench broadcast

Below you can find the results I got on my machine (Windows 10 + WSL2, AMD Ryzen 3200G 3.6GHz, 16GB RAM). But first, let's talk about the heap compaction for a bit.

`GC.compact`

GC compaction has been finally released in Ruby 2.7 (thanks to Aaron Patterson). To learn more about this feature, watch one of the latest Aaron's talks, for example, this one from RubyConf 2019:

First, I tried to visualize the effect of the GC.compact after running a simulation with 1k connected clients:

Without compaction

After GC.compact

Awesome! Compaction works! Or does it 🤔

I tried to run the pressure scenario with added GC.compact calls after each wave (while other waves are active, i.e., we continue accepting connections, broadcasting messages, etc.) and, unfortunately, found myself in the segmentation fault situation. Likely, the problem is with C extensions (we have at least Puma and nio4r).

Calling GC.compact while there are no active Action Cable clients works fine. So, I had to update the scenario a bit and add a "stop-the-world"-like feature to perform compaction in isolation.

Fullstaq Ruby & jemalloc

Jemalloc is an alternative memory allocator which could be used instead of malloc (used by default in MRI).

Here are a couple of articles to learn more about jemalloc for Rails applications: one and two.

We're going to use a Fullstaq Ruby distribution with jemalloc built-in (via Docker images provided by Evil Martians).

Benchmark results

NOTE: Since this is an unfinished play, I'm not providing any explanations/bikeshedding here—just plain results. Feel free to start a discussion in the comments!

We have 6 different setups:

baseline: MRI 2.7.1
compact: MRI 2.7.1 w/ compaction
jemalloc: Fullstaq Ruby 2.7.1 w/ jemalloc
jemalloc_compact: Fullstaq Ruby 2.7.1 w/ jemalloc and compaction
trim: Fullstaq Ruby 2.7.1 w/ malloc_trim
trim_compact: Fullstaq Ruby 2.7.1 w/ malloc_trim and compaction.

Below you can find the results of the benchmarks in different combinations (to better demonstrate the difference).

Without compaction

With compaction

Ruby 2.7.1

FullstaqRuby 2.7.1 with jemalloc

FullstaqRuby 2.7.1 with malloc_trim

All results combined

RuboCoping with legacy

Vladimir Dementyev — Tue, 24 Mar 2020 21:38:35 +0000

Originally posted in Martian Chronicles.

You will hardly find a Ruby developer who hasn't heard about RuboCop, the Ruby linter and formatter. And still, it is not that hard to find a project where code style is not enforced. Usually, these are large, mature codebases, often successful ones. Fixing linting and formatting can be a challenge if it wasn't set up correctly from the get-go. So, your RuboCop sees red! Here's how to fix it.

In this post, I will show you how we at Evil Martians touch up codebases of our customers in 2020: from quick and dirty hacks to proper Standard-enforced style guides, and our own ~~patented~~ way to use Standard and RuboCop configs together.

Style matters

Let's pretend I have to convince you to follow code style guidelines (I know, I know I don't have to!)

Here are the arguments I would use:

Developers understand each other much better when they ~~speak~~ write the same language.
Onboarding new engineers becomes much easier when the code style is standardized.
Linters help to detect and squash bugs in time.
No more "single vs. double quotes" holy wars (double FTW)!

That was all the theory for today. Time for practice!

TODO or not TODO

So, you have joined a project with no style guide or with a .rubocop.yml that was added years ago. You run RuboCop, and you see something like:

$ bundle exec rubocop

3306 files inspected, 12418 offenses detected

Flocks of noble ~~knights~~ developers tried to ~~slay the beast~~ fix the offenses but gave up. But that doesn't stop you—you know the magic spell:

$ bundle exec rubocop --auto-gen-config
Added inheritance from `.rubocop_todo.yml` in `.rubocop.yml`.
Created .rubocop_todo.yml.

$ bundle exec rubocop
3306 files inspected, no offenses detected

That was simple! Toss the coin to your...

Let's take a closer look at what --auto-gen-config flag does:

First, it collects all the offenses and their counts;
then, it generates a .rubocop_todo.yml where all the current offenses are ignored;
and finally, it makes .rubocop.yml inherit from .rubocop_todo.yml.

That is the way to set the status quo and only enforce style checks for new code. Sounds smart, right? Not exactly.

The way .rubocop_todo.yml handles "ignores" depends on the cop types and the total number of current offenses:

For metrics cops (such as Layout/LineLength), the limit (Max) is set to the maximum value for the current codebase.
All cops could be disabled if the total number of offenses hits the threshold (only 15 by default).

So, you end up with anything goes situation, and that defeats the purpose.

This article covers this problem in more detail.

What does it mean for a typical legacy codebase? Most of the new code would be ignored by RuboCop, too. We made the tool happy, but are we happy with it?

Hopefully, there is a way to generate a better TODO config by adding more options to the command:

bundle exec rubocop –-auto-gen-config \
  --auto-gen-only-exclude \
  --exclude-limit=10000

Where --auto-gen-only-exclude force-excludes metrics cops instead of changing their Max value, and --exclude-limit sets the threshold for the exclusion (set to some large enough number to avoid disabling cops completely).

Now your .rubocop_todo.yml won't affect your new files or entirely new offenses in the old ones.

RuboCop doesn't only help with style—it also saves you from common mistakes that can break your code in production. What if you had some bugs and ignored them in your TODO config? What are the cops that should never be ignored? Let me introduce the RuboCop strict configuration pattern.

You shall not pass: introducing `.rubocop_strict.yml`

There are a handful of cops that must be enabled for all the files independently of the .rubocop_todo.yml. For example:

Lint/Debugger—don't leave debugging calls (e.g., binding.pry).
RSpec/Focus (from rubocop-rspec)—don't forget to clear focused tests (to make sure CI runs the whole test suite).

We put such cops into a .rubocop_strict.yml configuration file like this:

inherit_from:
  - .rubocop_todo.yml

Lint/Debugger: # don't leave binding.pry
  Enabled: true
  Exclude: []

RSpec/Focus: # run ALL tests on CI
  Enabled: true
  Exclude: []

Rails/Output: # Don't leave puts-debugging
  Enabled: true
  Exclude: []

Rails/FindEach: # each could severely affect the performance, use find_each
  Enabled: true
  Exclude: []

Rails/UniqBeforePluck: # uniq.pluck and not pluck.uniq
  Enabled: true
  Exclude: []

Then, we replace the TODO config with the Strict config in our base .rubocop.yml configuration file:

 inherit_from:
-  - .rubocop_todo.yml
+  - .rubocop_strict.yml

The Exclude: [] is crucial here: even if our .rubocop_todo.yml contained exclusions for strict cops, we nullify them here, thus, re-activating these cops for all the files.

One Standard to rule them all

One of the biggest problems in adopting a code style is to convince everyone on the team to always use double-quotes for strings, or to add trailing commas to multiline arrays, or ro <choose-your-own-controversal-style-rule>? We are all well familiar with bikeshedding.

RuboCop provides a default configuration based on the Ruby Style Guide. And you know what? It's hard to find a project which follows all of the default rules, there are always reconfigured or disabled cops in the .rubocop.yml.

That's okay. RuboCop's default configuration is not a golden standard; it was never meant to be the one style to fit them all.

Should Ruby community have the only style at all? It seems that yes, we need it.

I think the main reason for that is the popularity of auto-formatters in other programming languages: JavaScript, Go, Rust, Elixir. Auto-formatters are usually very strict and allow almost none or zero configuration. And developers got used to that! People like writing code without worrying about indentation, brackets, and spaces; robots would sort it all out!

Checkout out the lightning talk and let Justin Searls convince you to switch to Standard.

Thankfully, Ruby's ecosystem has got you covered: there is a project called Standard, which claims to be the one and only Ruby style guide.

From the technical point of view, Standard is a wrapper over RuboCop with its custom configuration and CLI (standard).

Unfortunately, Standard lacks some RuboCop features that are essential at the early stages of a style guide's adoption: it is not possible to use .rubocop_todo.yml or any other local configuration. It also doesn't support RuboCop plugins or custom cops.

But we can still use Standard as a style guide while continuing to use RuboCop as a linter and formatter!

For that, we can use RuboCop's inherit_gem directive:

# .rubocop.yml

# We want Exclude directives from different
# config files to get merged, not overwritten
inherit_mode:
  merge:
    - Exclude

require:
  # Performance cops are bundled with Standard
  - rubocop-performance
  # Standard's config uses this custom cop,
  # so it must be loaded
  - standard/cop/semantic_blocks

inherit_gem:
  standard: config/base.yml

inherit_from:
  - .rubocop_strict.yml

# Sometimes we enable metrics cops
# (which are disabled in Standard by default)
#
# Metrics:
#   Enabled: true

That is the configuration I use in most of my OSS and commercial projects. I can't say I agree with all the rules, but I definitely like it more than the RuboCop's default. That is a tiny trade-off if you think about the benefit of not arguing over the style anymore.

Don't forget to add standard to your Gemfile and freeze its minor version to avoid unexpected failures during upgrades:

gem "standard", "~> 0.2.0", require: false

Although the approach above allows you to tinker with the Standard configuration, I would not recommend doing that. Use this flexibility to extend the default behavior, not change it!

Beyond the Standard

RuboCop has a lot of plugins distributed as separate gems: rubocop-rspec, rubocop-performance, rubocop-rails, rubocop-md, to name a few.

Standard only includes the rubocop-performance plugin. We usually add rubocop-rails and rubocop-rspec to our configuration.

For each plugin, we keep a separate YAML file: .rubocop_rails.yml, .rubocop_rspec.yml, etc.

Inside the base config we add these files to inherit_from:

inherit_from:
  - .rubocop_rails.yml
  - .rubocop_rspec.yml
  - .rubocop_strict.yml

Our .rubocop_rails.yml is based on the configuration that existed in Standard before they dropped Rails support.

There is no standard RSpec configuration, so we had to figure out our own: .rubocop_rspec.yml.

We also usually enable a select few custom cops, for example, Lint/Env.

In the end, our typical RuboCop configuration for Rails projects looks like this👇

# .rubocop.yml
inherit_mode:
  merge:
    - Exclude

require:
  - rubocop-performance
  - standard/cop/semantic_blocks
  - ./lib/cops/lint/env.rb

inherit_gem:
  standard: config/base.yml

inherit_from:
  - .rubocop_rails.yml
  - .rubocop_rspec.yml
  - .rubocop_strict.yml

Lint/Env:
  Enabled: true
  Include:
    - '**/*.rb'
  Exclude:
    - '**/config/environments/**/*'
    - '**/config/application.rb'
    - '**/config/environment.rb'
    - '**/config/puma.rb'
    - '**/config/boot.rb'
    - '**/spec/*_helper.rb'
    - '**/spec/**/support/**/*'
    - 'lib/generators/**/*'

Feel free to use it as an inspiration for your projects that could use some RuboCop's tough love.

RuboCop plays a vital role in the Ruby world and will stay TOP-1 for linting and formatting code for quite a long time (though competing formatters are evolving, for example, rubyfmt and prettier-ruby). Don't ignore RuboCop; write code in style 😎

Read more dev articles on https://evilmartians.com/chronicles!

GitHub Actions: First impressions

Vladimir Dementyev — Fri, 06 Sep 2019 10:16:33 +0000

GitHub Actions are coming on strong—in my team, almost everyone who has applied for a beta program, me included, had recently got access to GitHub's latest "killer feature" that threatens to make life harder for Travis CI and CircleCI: Continuous Integration with GitHub Actions. Here are my first impressions.

// Detect dark theme var iframe = document.getElementById('tweet-1164301670429409281-5'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1164301670429409281&theme=dark" }

For the ultimate test, I decided to reuse the documentation generator setup from my previous article: "Keeping OSS documentation with Docsify, Lefthook, and friends"). To lint a documentation website for AnyCable, I used Lefthook locally and CircleCI for production. For my next documentation project, the one for TestProf, I decided to move all the CI functionality to GitHub Actions (sorry, Travis and CircleCI, of course I still love you).

Check the PR with the final implementation: palkan/test-prof#156

Warming up: dealing with the stale issues

The first thing I found impressive about GitHub Actions is that they could be used not only to deal with code pushes and pull requests but also react on other GitHub events or run on schedule!

One of the actions that GitHub offers you when you first open the "Actions" tab of your project is Stale: it allows you to mark issues and pull requests with a "stale" label and close them. That's what I usually did by hand (and was hoping to automate with the help of the Stale GitHub App).

It took me a few minutes to add this action:

# .github/workflows/stale.yml
name: Mark stale issues

on:
  schedule:
  - cron: "0 * * * *"

jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/stale@v1
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}
        stale-issue-message: >
          ⚠ Marking this issue as stale since there has been no activity in the last 30 days.
          Remove stale label or comment or this issue will be closed in 15 days ⌛️
        stale-issue-label: stale
        days-before-stale: 30
        days-before-close: 15

After some time, I received a lot of notifications—the action took action:

I quickly realized that it wasn't a good idea: GitHub marked all the issues intentionally kept open (for discussion) as stale and spammed all the participants with the comment notification. I'm sorry, guys 😿.

It turned out that there is no ignore mechanism (e.g., by labels). There is one now, but still be careful: it is easy to get burned.

Migrating Markdown linters

Reimplementing the Markdown linting configuration I've already had for CircleCI was a pretty straightforward task:

name: Lint Docs

on:
  push:
    branches:
    - master
    paths:
    - "**/*.md"
  pull_request:
    paths:
    - "**/*.md"

jobs:
  markdownlint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: Set up Ruby 2.6
      uses: actions/setup-ruby@v1
      with:
        ruby-version: 2.6.x
    - name: Run Markdown linter
      run: |
        gem install mdl
        mdl docs
  rubocop:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: Set up Ruby 2.6
      uses: actions/setup-ruby@v1
      with:
        ruby-version: 2.6.x
    - name: Lint Markdown files with RuboCop
      run: |
        gem install bundler
        bundle install --gemfile gemfiles/rubocop.gemfile --jobs 4 --retry 3
        bundle exec --gemfile gemfiles/rubocop.gemfile rubocop -c .rubocop-md.yml
  forspell:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: Install Hunspell
      run: |
        sudo apt-get install hunspell
    - name: Set up Ruby 2.6
      uses: actions/setup-ruby@v1
      with:
        ruby-version: 2.6.x
    - name: Run Forspell
      run: |
        gem install forspell
        forspell docs/
  liche:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: Set up Go
      uses: actions/setup-go@v1
      with:
        go-version: 1.12.x
    - name: Run liche
      # see https://github.com/actions/setup-go/issues/14
      run: |
        export PATH=$PATH:$(go env GOPATH)/bin
        go get -u github.com/raviqqe/liche
        liche -r docs -d docs

A few noticeable differences compared to a CircleCI config:

Ability to trigger actions only when matching files have changed (See the paths: ["**/*.md"] declaration).
Inability to share the setup (checkout, dependency installation) between the jobs from the same action; there is no cache, or anything akin to CircleCI "workspaces".

Adding Neo and Trinity for RSpec

Adding the "Lint Docs" action went smoothly, so I decided to continue with migrating RSpec tests.

I'm running gems tests against multiple Ruby and frameworks versions to make sure most of the users are covered. I've been doing this successfully for years with Travis' Build Matrix feature:

matrix:
  fast_finish: true
  include:
    - rvm: 2.6.3
      gemfile: gemfiles/railsmaster.gemfile
    - rvm: jruby-9.2.7.0
      gemfile: gemfiles/jruby.gemfile 
    - rvm: 2.6.3
      gemfile: gemfiles/activerecord6.gemfile
    - rvm: 2.6.3
      gemfile: Gemfile
    - rvm: 2.5.3
      gemfile: Gemfile
    - rvm: 2.4.2
      gemfile: gemfiles/default_factory_girl.gemfile
    - rvm: 2.4.2
      gemfile: gemfiles/rspec35.gemfile
    - rvm: 2.4.2
      gemfile: gemfiles/activerecord42.gemfile
   allow_failures:
    - rvm: 2.6.2
      gemfile: gemfiles/railsmaster.gemfile
    - rvm: jruby-9.2.7.0
      gemfile: gemfiles/jruby.gemfile

GitHub Actions have a similar feature—strategy.matrix. And it's even stated in the documentation that the include-only variant works the same way as in Travis. However, that's not exactly true yet.

So, I had to take a detour and use the exclude option:

strategy:
  matrix:
    ruby: ["2.5.x", "2.6.x", "2.4.x"]
    gemfile: [
       "gemfiles/railsmaster.gemfile",
       "gemfiles/activerecord6.gemfile",
       "gemfiles/activerecord42.gemfile",
       "gemfiles/default_factory_girl.gemfile",
       "gemfiles/rspec35.gemfile"
    ]
    exclude:
    - ruby: "2.6.x"
      gemfile: "gemfiles/activerecord42.gemfile"
    - ruby: "2.6.x"
      gemfile: "gemfiles/rspec35.gemfile"
    - ruby: "2.6.x"
      gemfile: "gemfiles/default_factory_girl.gemfile"
    - ruby: "2.5.x"
      gemfile: "gemfiles/railsmaster.gemfile"
    - ruby: "2.5.x"
      gemfile: "gemfiles/activerecord42.gemfile"
    - ruby: "2.5.x"
      gemfile: "gemfiles/rspec35.gemfile"
    - ruby: "2.5.x"
      gemfile: "gemfiles/default_factory_girl.gemfile"
    - ruby: "2.4.x"
      gemfile: "gemfiles/railsmaster.gemfile"
    - ruby: "2.4.x"
      gemfile: "gemfiles/activerecord6.gemfile"

This configuration works exactly the same as the one from Travis (except the missing JRuby, we'll discuss it later), but unfortunately is much less readable.

Another thing I'd like to point out is that with GitHub Actions (compared to Travis) you have to deal with setting up a correct Gemfile yourself:

- name: Configure Gemfile
  run: |
    bundle config --global gemfile ${{ matrix.gemfile }}

Also, there is no allow_failures option. There is a steps.continue-on-failure toggle which could be used to achieve something similar, but with the strategy matrix.

Dealing with JRuby

You cannot use JRuby with the actions/setup-ruby action (or you can, but I couldn't find how?). It requires special treatment.

Here I applied another GitHub Actions feature—ability to use Docker containers to perform actions. That makes it works very similar to CircleCI.

I took the official JRuby image and added a separate job:

rspec-jruby:
  runs-on: ubuntu-latest
  container:
    image: jruby:9.2.8
    env:
      BUNDLE_GEMFILE: gemfiles/jruby.gemfile
  steps:
  - uses: actions/checkout@v1
  # I need git 'cause I use `git ls-files` in my .gemspec
  # to generate the list of the gem's files
  - name: Install git
    run: |
      apt-get update
      apt-get install -y --no-install-recommends git
  - name: Install deps and run RSpec
    run: |
      gem install bundler
      bundle install --jobs 4 --retry 3
      bundle exec rspec

And it just works!

Bonus: multiple badges

After merging the PR I've started looking for a way to add a build status badge to Readme (since I remove the old one from Travis).

The answer was found on Reddit pretty soon: https://github.com/{github_id}/{repository}/workflows/{workflow_name}/badge.svg.

What's interesting here is that you have a separate badge for each workflow. That means that, for example, you shouldn't be afraid of a "red" status due to the yet-another minor RuboCop release.

Another useful application of this "feature" is an ability to show that your library supports specific runtimes. For example, I split rspec workflow into two parts: one for different MRI version and another for JRuby. Now it's clear from the README that TestProf has been tested on JRuby and it's (hopefully) green!

GitHub Actions look very promising, especially for open source projects. The lack of some features (e.g., caching) would stop from using it as the primary CI/CD tool for commercial projects for now.

But that is just the beginning; we will see what's coming in the final release!

Read more dev articles on https://evilmartians.com/chronicles!

Keeping OSS documentation with Docsify, Lefthook, and friends

Vladimir Dementyev — Mon, 02 Sep 2019 18:28:51 +0000

"A program is only as good as its documentation."—Joe Armstrong, the author of the Erlang programming language

What makes a good open source project? If you are into Ruby, you can check out all the best practices in one place at Gem Check (created by yours truly). But even regardless the language or the stack—one thing is vital for all OSS projects: documentation.

Kelsey Hightower

@kelseyhightower

So you built it. Nobody's using it. Did you forget the docs? Aha!

01:08 AM - 22 Aug 2017

130 440

All open source projects, independently of the size, must be documented (even the now-deprecated, infamous left-pad is documented). In most cases, a well-crafted README is more than enough, but you can go further and create an "awesome readme".

However, as the project grows, README-backed documentation stops working. We might say "~~Rails~~ README doesn't scale!". And we will be right.

This brings us to a question: "What scales better than a single markdown page?"

In this text, I am sharing my answer to that.

In the Beginning, There Was Chaos

Before we start talking about docsify, let me show you some other tools I used, before settling on the one and only.

GitHub Wiki

My first project to outgrow its README was AnyCable. Without giving it much thought, I started moving bits of documentation into the GitHub's built-in wiki (it's still there, for older versions of the gem). If we already have the tool—that's the way to go, right? Well, not necessarily.

It turned out that the fact that GitHub wiki is built-in is the only advantage, while the list of cons drags on:

Updating code and docs independently is likely to lead to inconsistency.
Web editor has much to be desired; you cannot easily upload images, for example (technically it is possible, but it requires cloning the wiki repo).
Cross-references are easy to break just by changing a title; there is no way to have a permanent URL (or I was missing something).

`docs` folder

One way to resolve all the Wiki weak points (see the pun?) at once is to create a docs folder in the repo and populate it with markdown files. GitHub displays .md files with formatting when you open them in your browser. And you can also edit the contents right from the web UI! If that's the case, why use the wiki feature at all?

So, we found a good way to store the documentation contents. But what about the UI/UX? Don't we want to make our documentation more user-friendly (for example, add searching functionality)? Yes, we do.

Let's convert our GitHub-driven docs to web format.

Jekyll & GitHub Pages

GitHub helps with setting up a documentation website backed by Jekyll in a few clicks: go to "Settings" -> "GitHub Pages," choose the source for the website (we use the docs folder) and pick a Jekyll theme to your liking.

Now visit the URL from the Settings page and find your brand new documentation website there!

Unfortunately, the GitHub Pages Jekyll integration is limited, especially in terms of the available plugins. You cannot go far with it. And, in my opinion, Jekyll is a bit too complicated if you want to customize the looks of your page or add some interactivity.

Let's check out modern tools.

Docusaurus

The first modern documentation generator I have tried was Docusaurus. We built the Clowne's gem documentation with it.

But I have to admit that the experience was not so pleasant:

Given the fact that the library is built with React, I expected it to have more straightforward customization options. However, you don't really get access to internals and library authors don't want you to do the serious tweaking.
At the time of my first usage, it did not have the support for live reload, which is crucial for local development (now it seems to be fixed).
It requires a separate building step (yarn run build).

So I started looking for other options and found docsify.

Docsifying documentation

Docsify uses a different approach, compared to Jekyll or Docusaurus, to "generating" a website: it renders markdown files on the fly, and does not require a build phase.

There is also support for Server-side rendering and even for offline mode.

To "docsify" your docs, you need to do the following:

Add docs/.nojekyll file to disable Jekyll.
Add index.html that loads and configure docsify:

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      loadSidebar: true,
      subMaxLevel: 2,
      repo: 'palkan/docs-example',
      basePath: '/docs-example/',
      auto2top: true,
      homepage: 'https://raw.githubusercontent.com/palkan/docs-example/master/README.md'
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>
</body>
</html>

And that is it! Now you have something like this:

Note that I have added some specific configuration options:

basePath: '/docs-example/ defines the root path of your website (which is the repo name for personal projects on GitHub Pages);
homepage: '...' is set to the repo's README (by default docsify uses the docs/README.md file); that allows us to keep both home pages (GitHub and web) in sync.

And that's just the beginning! One of the main advantages of docsify is the simplicity of adding useful features via plugins.

Let's add a searching functionality.

All we need is to add these two lines of code:

 window.$docsify = {
   loadSidebar: true,
   subMaxLevel: 2,
+  search: 'auto',
   repo: 'palkan/docs-example',
   basePath: '/docs-example/',
   auto2top: true,
   homepage: 'https://raw.githubusercontent.com/palkan/docs-example/master/README.md'
   }
 </script>
 <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
 <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
 <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
 <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>

And voilà! We can search through our documentation! The searching is implemented on the client side and is backed by indexes saved to localStorage.

Another thing I like about docsify is the ease of customizing styles: the library uses CSS properties, thus making it possible to change colors and layouts without building your own CSS!

You can change the color and font sizes right in your index.html:

<style>
  :root {
    --theme-color: #ff5e5e;
    --theme-color-light: #fd7373;
    --theme-color-dark: #f64242;
    --theme-color-secondary: #ff5e5e;
    --theme-color-secondary-dark: #f64242;
    --theme-color-secondary-light: #fd7373;
    --text-color-base: #363636;
    --text-color-secondary: #646473;
  }
</style>
<body>
  ...
</body>

Isn't it awesome?

The code for the example above could be found on GitHub: palkan/docs-example.

Check out AnyCable documentation website and the corresponding repo for a more advanced example!

Bonus*: you can find the implementation of the floating action button for "Edit on GitHub" functionality in this gist.

Keeping docs healthy with linters

In the second part of this tutorial, I would like to share my approach to keeping documentation in a healthy state. And by the "healthy state," I mean:

Style consistency for source files (Markdown) and code examples (Ruby).
Correct spelling.
Valid code examples (from the syntax point of view).
Valid links (no link should lead to 4xx/5xx).

It's not surprising that for all of the above there is an open source tool (and sometimes many).

Markdownlint helps me to enforce Markdown files style (there is also a NodeJS version and a VS Code plugin).

I also usually disable a couple of rules:

Line length (MD013)—modern editors (such as VS Code) could handle this by wrapping long lines.
HTML fragments—sometimes Markdown is not enough.

To do that I put a .mdlrc file in the project's root with the following contents:

rules "~MD013", "~MD033"

To deal with Ruby syntax I use RuboCop along with the rubocop-md plugin that I wrote specifically for this task. As a default style configuration, I've recently started using standard.

To make this setup work you need to:

Install standard and rubocop-md gems (gem install standard and gem install rubocop-md)
Add a .rubocop.yml with the following contents:

require:
  - standard/cop/semantic_blocks
  - rubocop-md

inherit_gem:
  standard: config/base.yml

Standard/SemanticBlocks:
  Enabled: false

Run RuboCop.

For spellchecking, there is yet another Ruby tool—Forspell. It is a wrapper over a well-known Hunspell package.

Due to the number of technical terms, you may see a lot of warnings from Forspell during the first run:

$ forspell docs/

docs/development/lefthook.md:5: lefthook (suggestions: left hook, left-hook, leftmost)
docs/development/lefthook.md:9: lefthook (suggestions: left hook, left-hook, leftmost)
docs/development/lefthook.md:11: Hombrew (suggestions: Hombre, Hombres, Hombre w)
docs/development/lefthook.md:17: Golang (suggestions: Golan, Golan g, Angolan)

That could be easily fixed by running Forspell with the --gen-dictionary flag: it generates a forspell.dict file with all the unknown words. Don't forget to scan this file with your eyes and remove the actual typos.

Finally, to make sure that our documentation does not have any broken links, I use liche—a link checker for Markdown and HTML written in Go:

$ liche -r docs/

 ERROR    https://githb.com/palkan/anyway_config
                Dialing to the given TCP address timed out

Liche lacks some features I wish it had: for example, it does not warn about URLs responding with 404. Nevertheless, I found it a bit better than other existing tools.

In order to manage all these linters, I use Lefthook for local development and CircleCI for pull requests.

Here is the contents of my lefthook.yml, a file that stores Lefthook's configuration:

pre-commit:
  commands:
    mdl:
      glob: "**/*.md"
      run: mdl {staged_files}
    liche:
      glob: "**/*.md"
      run: liche -r docs
    forspell:
      glob: "**/*.md"
      run: forspell {staged_files}
    rubocop:
      glob: "**/*.md"
      run: rubocop {staged_files}

CirclCI configuration is a little bit more verbose, but does pretty much the same:

version: 2.1

workflows:
  version: 2
  build_and_test:
    jobs:
      - checkout
      - md_lint:
          requires:
            - checkout
      - links_lint:
          requires:
            - checkout
      - spelling:
          requires:
            - checkout
      - rubocop:
          requires:
            - checkout

executors:
  golang:
    docker:
      - image: circleci/golang:1.12.4-stretch
  ruby:
    docker:
      - image: circleci/ruby:2.5-stretch

jobs:
  checkout:
    executor: ruby
    steps:
      - restore_cache:
          keys:
            - project-source-v1-{{ .Branch }}-{{ .Revision }}
            - project-source-v1-{{ .Branch }}
            - project-source-v1
      - checkout
      - save_cache:
          key: project-source-v1-{{ .Branch }}-{{ .Revision }}
          paths:
            - .git
      - persist_to_workspace:
          root: .
          paths: .
  md_lint:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install mdl
          command: gem install mdl
      - run:
          name: Markdown lint
          command: mdl docs
  links_lint:
    executor: golang
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install liche
          command: go get -u github.com/raviqqe/liche
      - run:
          name: Check links
          command: liche -r docs
  spelling:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install hunspell
          command: sudo apt-get install hunspell
      - run:
          name: Install forspell
          command: gem install forspell
      - run:
          name: Check spelling
          command: forspell docs/
  rubocop:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install standard
          command: gem install standard
      - run:
          name: Install rubocop-md
          command: gem install rubocop-md
      - run:
          name: Check Ruby style
          command: rubocop

The complete example can be found in the docs.anycable.io repo (see PRs #14 and #15).

It took me a while to come with this setup (literally, years). Now I can spin up a new documentation website in minutes. Hope you found this article useful and will consider using a similar approach next time you need web-based docs for your projects.

Documentation for the win!

Read more dev articles on https://evilmartians.com/chronicles!

Ruby on Whales: Dockerizing Ruby and Rails development

Vladimir Dementyev — Wed, 24 Jul 2019 19:27:13 +0000

Originally posted in Martian Chronicles.

This post is a b-side of my recent RailsConf talk "Terraforming legacy Rails applications" (video, slides).

In this post, I am not going to convince you to switch to Docker for application development (though you can check the RailsConf video for some arguments). My goal is to share the configuration I currently use for Rails projects, and which was born in ~~production~~ development at Evil Martians. Feel free to use it!

I've started using Docker in my development environment about three years ago (instead of Vagrant which was too heavy for my 4GB RAM laptop). It wasn't all roses since the start, of course—I spent two years trying to find a configuration that is good enough, suitable not only for myself but also for my team.

Let me present this config here and explain (almost) every line of it, because we've all had enough of cryptic tutorials that just assume you know stuff.

The source code could be found in the evilmartians/terraforming-rails repository on GitHub.

We use the following stack in this example:

Ruby 2.6.3
PostgreSQL 11
NodeJS 11 & Yarn (for Webpacker-backed assets compilation)

`Dockerfile`

Dockerfile defines the environment for our Ruby application: this is where we run servers, console (rails c), tests, Rake tasks, interact with our code in any way as developers:

ARG RUBY_VERSION
# See explanation below
FROM ruby:$RUBY_VERSION

ARG PG_MAJOR
ARG NODE_MAJOR
ARG BUNDLER_VERSION
ARG YARN_VERSION

# Add PostgreSQL to sources list
RUN curl -sSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
  && echo 'deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main' $PG_MAJOR > /etc/apt/sources.list.d/pgdg.list

# Add NodeJS to sources list
RUN curl -sL https://deb.nodesource.com/setup_$NODE_MAJOR.x | bash -

# Add Yarn to the sources list
RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
  && echo 'deb http://dl.yarnpkg.com/debian/ stable main' > /etc/apt/sources.list.d/yarn.list

# Install dependencies
# We use an external Aptfile for that, stay tuned
COPY .dockerdev/Aptfile /tmp/Aptfile
RUN apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get -yq dist-upgrade && \
  DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
    build-essential \
    postgresql-client-$PG_MAJOR \
    nodejs \
    yarn=$YARN_VERSION-1 \
    $(cat /tmp/Aptfile | xargs) && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
    truncate -s 0 /var/log/*log

# Configure bundler and PATH
ENV LANG=C.UTF-8 \
  GEM_HOME=/bundle \
  BUNDLE_JOBS=4 \
  BUNDLE_RETRY=3
ENV BUNDLE_PATH $GEM_HOME
ENV BUNDLE_APP_CONFIG=$BUNDLE_PATH \
  BUNDLE_BIN=$BUNDLE_PATH/bin
ENV PATH /app/bin:$BUNDLE_BIN:$PATH

# Upgrade RubyGems and install required Bundler version
RUN gem update --system && \
    gem install bundler:$BUNDLER_VERSION

# Create a directory for the app code
RUN mkdir -p /app

WORKDIR /app

This configuration contains the essentials only and could be used as a starting point. Let me show what we are doing here.

The first two lines could look a bit strange:

ARG RUBY_VERSION
FROM ruby:$RUBY_VERSION

Why not just FROM ruby:2.6.3, or whatever Ruby stable version du jour it is? We want to make our environment configurable from the outside using Dockerfile as a sort of a template:

the exact versions of runtime dependencies are specified in the docker-compose.yml (see below);
the list of apt-installable dependencies is stored in a separate file (also see below).

The following three lines define arguments for PostgreSQL, NodeJS, Yarn, and Bundler versions:

ARG PG_MAJOR
ARG NODE_MAJOR
ARG BUNDLER_VERSION
ARG YARN_VERSION

Since we do not expect anyone to use this Dockerfile without Docker Compose, we do not provide default values.

Installing PostgreSQL, NodeJS, Yarn via apt requires adding their deb packages repos to the sources list.

For PostgreSQL (based in the official documentation):

RUN curl -sSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add - \
  && echo 'deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main' $PG_MAJOR > /etc/apt/sources.list.d/pgdg.list

For NodeJS (from NodeSource repo):

RUN curl -sL https://deb.nodesource.com/setup_$NODE_MAJOR.x | bash -

For Yarn (from the official website):

RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
  && echo 'deb http://dl.yarnpkg.com/debian/ stable main' > /etc/apt/sources.list.d/yarn.list

Now it's time to install the dependencies, i.e. run apt-get install:

COPY .dockerdev/Aptfile /tmp/Aptfile
RUN apt-get update -qq && DEBIAN_FRONTEND=noninteractive apt-get -yq dist-upgrade && \
  DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
    build-essential \
    postgresql-client-$PG_MAJOR \
    nodejs \
    yarn \
    $(cat /tmp/Aptfile | xargs) && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
    truncate -s 0 /var/log/*log

First, let's talk about the Aptfile trick:

COPY .dockerdev/Aptfile /tmp/Aptfile
RUN apt-get install \
    $(cat /tmp/Aptfile | xargs)

I borrowed this idea from heroku-buildpack-apt, which allows installing additional packages on Heroku. If you're using this buildpack, you can even re-use the same Aptfile for local and production environment (though the buildpack's one provides more functionality).

Our default Aptfile contains only a single package (we use Vim to edit Rails Credentials):

vim

In one of the previous project I worked on, we generated PDFs using LaTeX and TexLive. Our Aptfile might look like this (those days I didn't use this trick):

vim
texlive
texlive-latex-recommended
texlive-fonts-recommended
texlive-lang-cyrillic

This way, we keep the task-specific dependencies in a separate file, making our Dockerfile more universal.

With regards to DEBIAN_FRONTEND=noninteractive, I kindly ask you to take a look at answer on Ask Ubuntu.

The --no-install-recommends switch helps us to save some space (and make our image slimmer) by not installing recommended packages. See more here.

The last part of this RUN (apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && truncate -s 0 /var/log/*log) also serves the same purpose—clears out the local repository of retrieved package files (we installed everything, we don't need them anymore) and all the temporary files and logs created during the installation. We need this cleanup to be in the same RUN statement to make sure this particular Docker layer doesn't contain any garbage.

The final part is mostly devoted to Bundler:

ENV LANG=C.UTF-8 \
  GEM_HOME=/bundle \
  BUNDLE_JOBS=4 \
  BUNDLE_RETRY=3
ENV BUNDLE_PATH $GEM_HOME
ENV BUNDLE_APP_CONFIG=$BUNDLE_PATH \
  BUNDLE_BIN=$BUNDLE_PATH/bin
ENV PATH /app/bin:$BUNDLE_BIN:$PATH

# Upgrade RubyGems and install required Bundler version
RUN gem update --system && \
    gem install bundler:$BUNDLER_VERSION

The LANG=C.UTF-8 sets the default locale to UTF-8. Otherwise Ruby uses US-ASCII for strings and bye-bye those sweet sweet emojis 👋

We set the path for gem installations via GEM_HOME=/bundle. What is /bundle? That's the path where we're going to mount as a volume later to persist the dependencies on the host system, i.e., your development machine (see below in docker-compose.yml).

The BUNDLE_PATH and BUNDLE_BIN variables tell Bundler where to look for gems and Ruby executables.

Finally, we expose Ruby and application binaries globally:

ENV PATH /app/bin:$BUNDLE_BIN:$PATH

That allows us to run rails, rake, rspec and other binstubbed commands without prefixing them with bundle exec.

`docker-compose.yml`

Docker Compose is a tool to orchestrate our containerized environment. It allows us to link containers to each other, define persistent volumes and services.

Below is the compose file for a typical Rails application development with PostgreSQL as a database, and Sidekiq background job processor:

version: '3.4'

services:
  app: &app
    build:
      context: .
      dockerfile: ./.dockerdev/Dockerfile
      args:
        RUBY_VERSION: '2.6.3'
        PG_MAJOR: '11'
        NODE_MAJOR: '11'
        YARN_VERSION: '1.13.0'
        BUNDLER_VERSION: '2.0.2'
    image: example-dev:1.0.0
    tmpfs:
      - /tmp

  backend: &backend
    <<: *app
    stdin_open: true
    tty: true
    volumes:
      - .:/app:cached
      - rails_cache:/app/tmp/cache
      - bundle:/bundle
      - node_modules:/app/node_modules
      - packs:/app/public/packs
      - .dockerdev/.psqlrc:/root/.psqlrc:ro
    environment:
      - NODE_ENV=development
      - RAILS_ENV=${RAILS_ENV:-development}
      - REDIS_URL=redis://redis:6379/
      - DATABASE_URL=postgres://postgres:postgres@postgres:5432
      - BOOTSNAP_CACHE_DIR=/bundle/bootsnap
      - WEBPACKER_DEV_SERVER_HOST=webpacker
      - WEB_CONCURRENCY=1
      - HISTFILE=/app/log/.bash_history
      - PSQL_HISTFILE=/app/log/.psql_history
      - EDITOR=vi
    depends_on:
      - postgres
      - redis

  runner:
    <<: *backend
    command: /bin/bash
    ports:
      - '3000:3000'
      - '3002:3002'

  rails:
    <<: *backend
    command: bundle exec rails server -b 0.0.0.0
    ports:
      - '3000:3000'

  sidekiq:
    <<: *backend
    command: bundle exec sidekiq -C config/sidekiq.yml

  postgres:
    image: postgres:11.1
    volumes:
      - .psqlrc:/root/.psqlrc:ro
      - postgres:/var/lib/postgresql/data
      - ./log:/root/log:cached
    environment:
      - PSQL_HISTFILE=/root/log/.psql_history
    ports:
      - 5432

  redis:
    image: redis:3.2-alpine
    volumes:
      - redis:/data
    ports:
      - 6379

  webpacker:
    <<: *app
    command: ./bin/webpack-dev-server
    ports:
      - '3035:3035'
    volumes:
      - .:/app:cached
      - bundle:/bundle
      - node_modules:/app/node_modules
      - packs:/app/public/packs
    environment:
      - NODE_ENV=${NODE_ENV:-development}
      - RAILS_ENV=${RAILS_ENV:-development}
      - WEBPACKER_DEV_SERVER_HOST=0.0.0.0

volumes:
  postgres:
  redis:
  bundle:
  node_modules:
  rails_cache:
  packs:

We define eight services. Why so many? Some of them only define shared configuration for others (abstract services, e.g., app and backend), others are used to specific commands using the application container (e.g., runner).

With this approach, we do not use docker-compose up command to run our application, but always specify the exact service we want to run (e.g., docker-compose up rails). That makes sense: in development, you rarely need all of the services up and running (Webpacker, Sidekiq, etc.).

Let's take a thorough look at each service.

`app`

The main purpose of this service is to provide all the required information to build our application container (the one defined in the Dockerfile above):

build:
  context: .
  dockerfile: ./.dockerdev/Dockerfile
  args:
    RUBY_VERSION: '2.6.3'
    PG_MAJOR: '11'
    NODE_MAJOR: '11'
    YARN_VERSION: '1.13.0'
    BUNDLER_VERSION: '2.0.2'

The context directory defines the build context for Docker: this is something like a working directory for the build process, it's used by the COPY command, for example.

We explicitly specify the path to Dockerfile since we do not keep it in the project root, packing all Docker-related files inside a hidden .dockerdev directory.

And, as we mentioned earlier, we specify the exact version of dependencies using args declared in the Dockerfile.

One thing that we should pay attention to is the way we tag images:

image: example-dev:1.0.0

One of the benefits of using Docker for development is the ability to synchronize the configuration changes across the team automatically. You only need to upgrade the local image version every time you make changes to it (or to the arguments or files it relies on). The worst thing you can do is to use example-dev:latest as your build tag.

Keeping an image version also helps to work with two different environments without any additional hassle. For example, when you work on a long-running "chore/upgrade-to-ruby-3" branch, you can easily switch to master and use the older image with the older Ruby, no need to rebuild anything.

The worst thing you can do is to use latest tags for images in your docker-compose.yml.

We also tell Docker to use tmpfs for /tmp folder within a container to speed things up:

tmpfs:
  - /tmp

`backend`

We reached the most interesting part of this post.

This service defines the shared behavior of all Ruby services.

Let's talk about the volumes first:

volumes:
  - .:/app:cached
  - bundle:/bundle
  - rails_cache:/app/tmp/cache
  - node_modules:/app/node_modules
  - packs:/app/public/packs
  - .dockerdev/.psqlrc:/root/.psqlrc:ro

The first item in the volumes list mounts the current working directory (the project's root) to the /app folder within a container using the cached strategy. This cached modifier is the key to efficient Docker development on MacOS. We're not going to dig deeper in this post (we're working on a separate one on this subject 😉), but you can take a look at the docs.

The next line tells our container to use a volume named bundle to store /bundle contents. This way we persist our gems data across runs: all the volumes defined in the docker-compose.yml stay put until we run docker-compose down --volumes.

The following three lines are also there to get rid of the "Docker is slow on Mac" curse. We put all the generated files into Docker volumes to avoid heavy disk operations on the host machine:

- rails_cache:/app/tmp/cache
- node_modules:/app/node_modules
- packs:/app/public/packs

To make Docker fast enough on MacOS follow these two rules: use :cached to mount source files and use volumes for generated content (assets, bundle, etc.).

The last line adds a specific psql configuration to the container. We mostly need it to persist the commands history by storing it in the app's log/.psql_history file. Why psql in the Ruby container? It's used internally when you run rails dbconsole.

Our .psqlrc file contains the following trick to make it possible to specify the path to the history file via the env variable (allow specifying the path to history file via PSQL_HISTFILE env variable, and fallback to the defaukt $HOME/.psql_history otherwise):

\set HISTFILE `[[ -z $PSQL_HISTFILE ]] && echo $HOME/.psql_history || echo $PSQL_HISTFILE`

Let's talk about the environment variables:

environment:
  - NODE_ENV=${NODE_ENV:-development}
  - RAILS_ENV=${RAILS_ENV:-development}
  - REDIS_URL=redis://redis:6379/
  - DATABASE_URL=postgres://postgres:postgres@postgres:5432
  - WEBPACKER_DEV_SERVER_HOST=webpacker
  - BOOTSNAP_CACHE_DIR=/bundle/bootsnap
  - HISTFILE=/app/log/.bash_history
  - PSQL_HISTFILE=/app/log/.psql_history
  - EDITOR=vi
  - MALLOC_ARENA_MAX=2
  - WEB_CONCURRENCY=${WEB_CONCURRENCY:-1}

There are several things here, and I'd like to focus one.

First, the X=${X:-smth} syntax. It could be translated as "For X variable within the container use the host machine X env variable value if present and another value otherwise". Thus, we make it possible to run a service in a different environment provided along with the command, e.g., RAILS_ENV=test docker-compose up rails.

The DATABASE_URL, REDIS_URL, and WEBPACKER_DEV_SERVER_HOST variables connect our Ruby application to other services. The DATABASE_URL and WEBPACKER_DEV_SERVER_HOST variables are supported by Rails (ActiveRecord and Webpacker respectively) out-of-the-box. Some libraries support REDIS_URL as well (Sidekiq) but not all of them (for instance, Action Cable must be configured explicitly).

We use bootsnap to speed up the application load time. We store its cache in the same volume as the Bundler data because this cache mostly contains the gems data; thus, we should drop everything altogether in case we do another Ruby version upgrade, for instance.

The HISTFILE=/app/log/.bash_history is the significant setting from the developer's UX point of view: it tells Bash to store its history in the specified location, thus making it persistent.

The EDITOR=vi is used, for example, by rails credentials:edit command to manage credentials files.

Finally, the last two settings, MALLOC_ARENA_MAX and WEB_CONCURRENCY, are there to help you keep Rails memory handling in check.

The only lines in this service yet to cover are:

stdin_open: true
tty: true

They make this service interactive, i.e., provide a TTY. We need it, for example, to run Rails console or Bash within a container.

It is the same as running a Docker container with the -it options.

`webpacker`

The only thing I want to mention here is the WEBPACKER_DEV_SERVER_HOST=0.0.0.0 setting: it makes Webpack dev server accessible from the outside (by default it runs on localhost).

`runner`

To explain what is this service for, let me share the way I use Docker for development:

I start a Docker daemon running a custom docker-start script:

#!/bin/sh

if ! $(docker info > /dev/null 2>&1); then
  echo "Opening Docker for Mac..."
  open -a /Applications/Docker.app
  while ! docker system info > /dev/null 2>&1; do sleep 1; done
  echo "Docker is ready to rock!"
else
  echo "Docker is up and running."
fi

Then I run dcr runner (dcr is an alias for docker-compose run) in the project directory to log into the container's shell; this is an alias for:

$ docker-compose run --rm runner

I run (almost) everything from within this container: tests, migrations, Rake tasks, whatever.

As you can see, I do not spin a new container every time I need to run a task, and I'm always using the same one.

Thus, I'm using dcr runner the same way I used vagrant ssh years ago.

The only reason why it's called runner and not shell, for example, is that it also could be used to run arbitrary commands within a container.

Note: The runner service is a matter of taste, it doesn't bring anything new comparing to the web service, except from the default command (/bin/bash); thus, docker-compose run runner is exactly the same as docker-compose run web /bin/bash (but shorter 😉).

Bonus: dip.yml

If you still think that the Docker Compose way is too complicated, there is a tool called Dip developed by one of my colleages at Evil Martians that aims to make the developer experience smoother.

It is especially useful if you have multiple compose files or platform-dependent configurations because it could glue them together and provide a universal interface to manage the Docker development environment.

We're going to tell you more about it in the future. Stay tuned!

P.S. Special thanks to Sergey Ponomarev and Mikhail Merkushin for sharing their tips on the subject. 🤘

Read more dev articles on https://evilmartians.com/chronicles!

DEV Community: Vladimir Dementyev

Keynote tips: syntax highlighting

Option #1. Screenshots

Option #2. HTML

Option #3: RTF & Automator

DIY multi-regional uptime monitoring with Fly.io and Uptime Kuma

Introducing Uptime Kuma

Deploying Uptime Kuma to Fly

Going multi-regional

Faster RuboCop runs for Rails apps

Rails-docker-box, or developing Rails within a dockerized environment

From boxes to containers, or a bit of history

Docker, Compose, and Dip walks into a bar

Bonus: Git ignore without .gitignore

Climbing Steep hills, or adopting Ruby 3 types

RBS in a nutshell

Getting started with RBS

Introducing Steep

steep init

steep stats

Fighting with signatures, or make steep check happy

1. Refinements always break things.

2. Superclass don't cry 😢

3. Explicit over implicit: handling splats.

4. Explicit over implicit, pt. 2: forwarding arguments.

5. Variadic arguments: annotations to the rescue!

6. Deal with metaprogramming: interfaces.

7. Making Steep happy.

Runtime type checking with RBS

Bonus: Steep meets Rake

Bonus 2: Type Checking meets GitHub Actions

Reusable Docker development environment

Once upon a time...

Phase 0: Universal docker-compose.yml

Phase 1 (discarded): RDE

Phase 2 (current): Back to docker-compose.yml with Dip

Using with VS Code

Node.js example: Docsify

Erlang example: keeping build artifacts

Bonus: multiple compose files

Smooth PostgreSQL upgrades in DockerDev environments with Lefthook

Upgrading PostgreSQL in Docker

Upgrading between major versions? #37

Automating upgrades with Lefthook

Cables profiling returns: GC.compact & jemalloc

The Benchmark

GC.compact

Fullstaq Ruby & jemalloc

Benchmark results

RuboCoping with legacy

Style matters

TODO or not TODO

You shall not pass: introducing .rubocop_strict.yml

One Standard to rule them all

Beyond the Standard

GitHub Actions: First impressions

Warming up: dealing with the stale issues

Migrating Markdown linters

Adding Neo and Trinity for RSpec

Dealing with JRuby

Bonus: multiple badges

Keeping OSS documentation with Docsify, Lefthook, and friends

In the Beginning, There Was Chaos

GitHub Wiki

docs folder

Jekyll & GitHub Pages

Docusaurus

Docsifying documentation

Keeping docs healthy with linters

Ruby on Whales: Dockerizing Ruby and Rails development

Dockerfile

docker-compose.yml

app

backend

webpacker

runner

Bonus: dip.yml

Bonus: Git ignore without `.gitignore`

`steep init`

`steep stats`

Fighting with signatures, or make `steep check` happy

Phase 0: Universal `docker-compose.yml`

Phase 2 (current): Back to `docker-compose.yml` with Dip

`GC.compact`

You shall not pass: introducing `.rubocop_strict.yml`

`docs` folder

`Dockerfile`

`docker-compose.yml`

`app`

`backend`

`webpacker`

`runner`