DEV Community: Peter H. Boling

Why flag_shih_tzu is changing its default SQL for bit flags

Peter H. Boling — Tue, 26 May 2026 22:22:00 +0000

flag_shih_tzu stores many boolean attributes in one integer column. Each boolean gets one bit 〰️ well that used to be true 〰️ v1.0.0 supports multi-bit flags, ternary, or even more for enum flags! 〰️ anyways, not the point of this article, so let's keep going:

class User < ApplicationRecord
  include FlagShihTzu

  has_flags 1 => :warpdrive,
    2 => :shields
end

Historically, the gem's default SQL for querying one flag used an IN() list.
For warpdrive, the condition looked like this:

users.flags in (1,3)

That is correct while the application knows about exactly two flags. The
possible values where bit 1 is enabled are 1 and 3.

The problem appears when flags are added during a rolling deploy.

The deploy that breaks old queries

Suppose the next version of the app adds a new flag:

class User < ApplicationRecord
  include FlagShihTzu

  has_flags 1 => :warpdrive,
    2 => :shields,
    3 => :premium
end

In the same deploy, a migration or background job sets the new bit for existing
rows:

UPDATE users
SET flags = flags | 4
WHERE created_at < '2026-01-01'

A user that previously had only warpdrive moved from flags = 1 to
flags = 5.

During a rolling deploy, old application processes may still be serving
requests. Those old processes still think only two flags exist, so they still
query warpdrive with:

users.flags in (1,3)

That query no longer returns the flags = 5 row, even though the warpdrive
bit is still set.

That is the bug. Nothing is wrong with the row. The old query is too dependent
on knowing every possible future flag combination.

Bit operators match the model

The next major flag_shih_tzu release changes the default query mode to
:bit_operator.

The same warpdrive query becomes:

users.flags & 1 = 1

That condition asks the database the same question the application asks:
"is this bit set?"

It keeps working if the row is 1, 3, 5, 7, or any future value with
the warpdrive bit enabled.

For negated scopes, the generated SQL becomes:

users.flags & 1 = 0

Chained flag conditions also use bit checks by default, so a query for
warpdrive and shields becomes:

users.flags & 1 = 1 AND users.flags & 2 = 2

This is a breaking change

This changes generated SQL, so it belongs in a major release.

Most application code should not need to change. Calls like
User.warpdrive, User.not_warpdrive, and User.warpdrive_condition keep the
same Ruby API. The SQL string and database query plan may change.

If your application depends on the old SQL shape, you can opt back in globally:

FlagShihTzu.default_flag_query_mode = :in_list

Or per model declaration:

has_flags 1 => :warpdrive,
  2 => :shields,
  flag_query_mode: :in_list

The old mode is still supported. It is just no longer the safest default.

Performance tradeoff

An IN() list can be faster for some databases and indexes when the set of
flags is small and fixed. A bit operation may not use the same index strategy.

That tradeoff is real. But defaults should protect correctness first.

If your app has a fixed set of flags and you have measured that IN() lists
perform better for your workload, keep using :in_list.

If your app may add flags over time, especially during rolling deploys, the new
default avoids a subtle class of production bugs.

Why this matters

Bit flags are attractive because they let applications add boolean features
without changing table schemas. That benefit is only complete if the query
strategy also tolerates new flags appearing while old app processes are still
alive.

flags & bit = bit does that. flags in (known_combinations) does not.

That is why flag_shih_tzu is making :bit_operator the default.

Support & Funding Info

I am a full-time OSS maintainer. If you find my work valuable I ask that you become a sponsor. Every dollar helps!

Support OSS Work &	Access my "Sponsors" channel	on Galtzo.com	Discord 👇️

yard-yaml 0.1.1: safer UTF-8 handling for YAML documentation

Peter H. Boling — Mon, 25 May 2026 04:24:26 +0000

yard-yaml 0.1.1 is available.

yard-yaml is a RubyGem that plugs into YARD and helps Ruby projects document YAML files alongside the rest of their API docs. It can discover .yml, .yaml, and Citation File Format (.cff) files, convert them to HTML pages, and expose inline documentation tags such as @yaml and @yaml_file.

This release is mostly about making the converter more resilient around file encodings, plus keeping the generated project tooling current.

What changed

The main user-facing fix is in Yard::Yaml::Converter.from_file.

In 0.1.1 it now:

preserves valid UTF-8 text
scrubs malformed UTF-8 safely in non-strict mode
rejects binary-ish inputs cleanly instead of raising raw encoding crashes

That matters for documentation pipelines because YAML-like files are often edited by different tools, copied between systems, or generated by automation. A documentation build should fail clearly when the input is not text, and it should handle recoverable encoding issues predictably when strict mode is disabled.

Documentation and CI maintenance

This release also includes generated project maintenance from the current kettle-jem template:

refreshed generated project tooling
refreshed CI support
refreshed documentation support
generated CI coverage for rdoc ~> 6.11 and >= 7.0

For contributors working across sibling repositories, 0.1.1 also adds documentation_local.gemfile support under KETTLE_RB_DEV, which makes local documentation development smoother in a multi-repo workspace.

Quick usage

Install the gem:

bundle add yard-yaml

Then enable the YARD plugin in .yardopts:

--plugin yaml

From there, yard-yaml can participate in yard doc generation and convert YAML documents, including .cff files, into documentation output.

The plugin also supports inline docstring tags:

# @yaml
# ---
# title: Example YAML
# description: This is an example YAML block.
# ---

And file references:

# @yaml_file path/to/example.yml

Release links

Release: https://github.com/galtzo-floss/yard-yaml/releases/tag/v0.1.1
Changelog compare: https://github.com/galtzo-floss/yard-yaml/compare/v0.1.0...v0.1.1
RubyDoc: http://rubydoc.info/gems/yard-yaml
Source: https://github.com/galtzo-floss/yard-yaml

Thanks to everyone building Ruby documentation tooling and keeping project docs close to the code they describe.

yard-fence 0.9.0: cleaner YARD docs when Markdown braces get in the way

Peter H. Boling — Sun, 24 May 2026 06:29:36 +0000

🤺 yard-fence 0.9.0 is out.

This is the first blog post I have written for the gem, so I will start with the short version:

yard-fence is a Ruby gem that helps YARD generate cleaner documentation from Markdown files that contain braces.

If you have ever had README examples, inline code, or template placeholders like {issuer} or {{TOKEN}} cause noisy YARD InvalidLink warnings, yard-fence exists for that problem.

The problem

YARD is great at generating Ruby API documentation, and it can include Markdown content like a README in the generated docs. The trouble starts when Markdown content contains brace-heavy examples.

That can happen in a lot of normal documentation:

Use `{issuer}` as the issuer placeholder.

```ruby
config.headers = { "Authorization" => "Bearer {{TOKEN}}" }
```

Those braces are ordinary text to the author, but YARD can interpret brace content as reference/link syntax. The result is documentation noise, usually in the form of InvalidLink warnings.

Ignoring those warnings is tempting, but it weakens the signal from the documentation build. Once a build always emits known warnings, new warnings are easier to miss.

What yard-fence does

yard-fence puts a small preprocessing fence around the Markdown files YARD reads.

During the Rake-based YARD workflow, it:

Copies top-level Markdown and text files into tmp/yard-fence/
Replaces ASCII braces inside fenced code blocks, inline code spans, and simple placeholders with visually similar fullwidth braces
Points YARD at the staged files instead of the originals
Lets YARD generate HTML without treating those braces as links
Restores the generated HTML back to normal ASCII {} braces afterward

The important part: your generated docs still contain copy-pastable code examples.

The conversion is temporary staging for YARD, not a change to your source files.

What changed in 0.9.0

The main 0.9.0 change is that documentation processing is now explicitly Rake-driven.

Projects should define their YARD task, then call:

Yard::Fence.install_rake_tasks!(:yard)

That wires yard:fence:prepare before the selected YARD task and runs HTML post-processing after the YARD task completes.

This release also removes global at_exit post-processing. That is intentional. Raw yard or bin/yard does not run the full yard-fence workflow anymore unless the caller invokes the Rake-integrated documentation task.

The practical fix in 0.9.0: loading YARD during unrelated rake tasks no longer clears or rewrites docs/.

Installation

With Bundler:

bundle add yard-fence

Or install the gem directly:

gem install yard-fence

Basic usage

Use the Rake integration so the prepare and postprocess steps run around the YARD build:

require "yard"
require "yard/fence"

YARD::Rake::YardocTask.new(:yard) { |t| t.files = [] }
Yard::Fence.install_rake_tasks!(:yard)

Then build docs with:

bundle exec rake yard

If your project exposes bin/yard, treat it the same as raw yard: it runs YARD itself, but it does not run the yard-fence Rake integration.

Recommended .yardopts

Point YARD at the staged Markdown/TXT files:

--plugin fence
-e yard/fence/hoist.rb
--readme tmp/yard-fence/README.md
--charset utf-8
--markup markdown
--markup-provider kramdown
--output docs
'lib/**/*.rb'
-
'tmp/yard-fence/*.md'
'tmp/yard-fence/*.txt'

This keeps YARD away from the unsanitized originals during the documentation build.

Environment variables

yard-fence has a few small controls:

Variable	Default	Description
`YARD_FENCE_DISABLE`	`false`	Disable all `yard-fence` processing
`YARD_FENCE_CLEAN_DOCS`	`false`	Clear `docs/` before regeneration
`YARD_DEBUG`	`false`	Enable debug output

For example, if Markdown files were removed and you want to avoid stale generated pages:

YARD_FENCE_CLEAN_DOCS=true bundle exec rake yard

The tmp/yard-fence/ staging directory is always cleared automatically before regeneration.

Release links

Release: https://github.com/galtzo-floss/yard-fence/releases/tag/v0.9.0
Source: https://github.com/galtzo-floss/yard-fence
Docs: http://rubydoc.info/gems/yard-fence

🤺 If your YARD docs have noisy brace-related InvalidLink warnings, give yard-fence a try.

yard-timekeeper: Stop YARD Timestamp Churn in Checked-In Docs

Peter H. Boling — Sun, 24 May 2026 00:35:28 +0000

🕰️ I just released yard-timekeeper v0.1.0, a small RubyGem for Ruby projects that check generated YARD HTML into git.

It solves a very specific kind of documentation noise: timestamp-only churn.

The Problem

If your project publishes generated YARD documentation from a checked-in docs/ directory, you have probably seen this:

You run the docs task.
YARD regenerates HTML.
Git reports changed files.
You inspect the diff.
The only change is the footer timestamp.

That is not a documentation change. It is build noise.

For projects that keep generated docs under version control, this creates unnecessary diffs, noisier pull requests, and extra review work. It also makes it harder to notice when documentation actually changed.

What `yard-timekeeper` Does

yard-timekeeper runs after YARD generates HTML and checks tracked files under docs/**/*.html.

If a file's only change is the generated footer timestamp, it restores that file from git.

If the page has real content changes, it leaves the file alone.

The goal is not to hide documentation changes. The goal is to remove timestamp-only churn while preserving the signal that matters.

Install

gem install yard-timekeeper

Or add it with Bundler:

bundle add yard-timekeeper

Configuration

The supported workflow is through rake yard, so the post-process hook can run after YARD finishes.

In your Rakefile or documentation task setup:

require "yard/timekeeper"

Yard::Timekeeper.install_rake_tasks!(:yard)

Then generate docs with:

bin/rake yard

No .yardopts plugin entry is required for this integration. If you were experimenting with --plugin timekeeper, remove it for this workflow and use the rake integration instead.

Behavior

yard-timekeeper is intentionally conservative:

It only post-processes docs/**/*.html.
It only restores files already tracked by git.
It only restores files whose diff is timestamp-only.
It preserves real generated documentation changes.
It can be disabled with YARD_TIMEKEEPER_DISABLE=true.

That means new documentation pages, deleted pages, and pages with real content edits remain visible to git.

Why This Exists

I maintain a lot of Ruby gems, and many of them publish YARD docs from checked-in HTML. I want documentation generation to be repeatable without filling commits with timestamp changes.

Small tooling like this is not glamorous, but it improves the daily maintenance loop. Cleaner diffs mean easier review. Easier review means fewer mistakes.

💎REL: oauth2 v2.0.18

Peter H. Boling — Wed, 01 Apr 2026 05:59:42 +0000

oauth2 v2.0.18 was released... almost five months ago. And I never got around to posting about it. Being unemployed is a LOT of work...

As a participant in Session 3 of GitHub Secure Open Source Fund I was able to learn about implementing:

an incident response plan
threat model analysis

These are critical tools to have in place so you have a guide when things go awry. ;) Those are the main changes in v2.0.18.

Another release is coming soon...

Ruby #GitHub #Security

Cover Photo (Cropped) by Dasha Yukhymyuk on Unsplash

🐠 ANN: appraisal2 v3.0.6 - support frozen appraisal lockfiles

Peter H. Boling — Wed, 18 Feb 2026 06:20:33 +0000

An issue was reported by Richard Kramer, and made me aware of a use case that I had never personally used, or even considered - which is committing the lockfiles for appraisals. I have always added gemfiles/*.gemfile.lock to my .gitignore.

In fact, when I had use cases where I wanted to run a CI workflow against a frozen lockfile I would avoid using appraisal2. But no more. We now have first class support for frozen lockfiles, and the implied active bundler version switching that can happen at runtime.

No breaking changes. No code changes needed for implementations. Just update, and go. Report back if anything breaks!

I need your support. Please sponsor me here on OpenCollective, or on:

Thanks,
@pboling

Hostile Takeover of RubyGems: My Thoughts

Peter H. Boling — Fri, 06 Feb 2026 01:00:32 +0000

I'll keep this post evergreen, as the situation evolves. Also, when you are done reading - hire me.

👣🔍️ First some background reading 🕵️

RubyGems (the GitHub org, not the website) suffered a hostile takeover in September 2025.
Ultimately 4 maintainers were hard removed and a (dubious) reason has been given for only 1 of those, while 2 others resigned in protest.
It is a complicated story which is difficult to parse quickly.
Simply put - there was active policy for adding or removing maintainers/owners of rubygems and bundler, and those policies were not followed.
I'm adding a note linking to this post to all of my gems because I don't condone theft of repositories or gems from their rightful owners.
If a similar theft happened with my repos/gems, I'd hope some would stand up for me.
Disenfranchised former-maintainers have started gem.coop.
Once available I will publish there, or to my own server, exclusively; unless RubyCentral & Ruby Core make amends with the community.
The "Technology for Humans: Joel Draper" podcast episode by reinteractive is the most cogent summary I'm aware of.
See here, here and here for more info on what comes next.

My thoughts

I no longer trust Ruby Central.
I no longer trust certain members, but primarily HSBT, of the RubyGems core team.
I no longer trust certain members, but primarily HSBT and Matz, of the Ruby core team.

Q: In what sense do I not trust them?
A: 📃 Governance 📃

To be more specific, I no longer trust that they:

Hold people accountable for their actions according to written agreements and documentation around governance policy.
Understand the community upset over point 1.
Will ever do anything about it.

If they are added to your repository, you may wake up to find you have lost access to your own project.

I'm not OK with this having already happened to others, and have taken steps to ensure it will not happen to me.

Within my open source projects, I will reduce, to the degree possible, my reliance, on any project hosted under the Ruby org on GitHub. Since most of my projects are Ruby projects, I'll never get to complete exclusion, but I will be focusing much more on JRuby and Truffleruby.

It has been pointed out to me in other discussions about this that we never had reason to trust them, but we did anyway, implicitly. We normally assume other people live by the same code of ethics that we ourselves live by. I will miss being able to rest on that assumption, but it is probably for the best that it get binned.

What I'm doing about it

appraisal2 is a hard fork of the old, and nearly-dead, namesake Thoughtbot project, to which I've added many features, including support for:
- Bundler's eval_gemfile
- frozen appraisal lockfiles w/ bundler version switching
- all versions of Ruby back to v1.8
- ore (see below)
- More on the reasons behind the hard fork
ore installs gems without Ruby, without bundler, and without rubygems. It is a GoLang implementation of (some parts of) Bundler (and adds some features bundler lacks). A project by @seuros - and I'm now on the core team. It is much faster than bundler.
setup-ruby-flash is an alternative to the venerable setup-ruby GHA we've all been using for years. setup-ruby-flash relies on rv and ore for Ruby and Gem installs, and it falls back to setup-ruby on unsupported platforms/engines. I wrote more about it here.
A (WIP) proposal for bundler/gem scopes
A (WIP) proposal for a federated gem server

⚡️ setup-ruby-flash

Peter H. Boling — Mon, 19 Jan 2026 03:03:27 +0000

Find out how fast my workflows can go!
-You, possibly

GH Marketplace	Dogfood	Current Tag	License	Source	Stars

A fast GitHub Action for fast Ruby environment setup using rv for Ruby installation and ore for gem management.

⚡ Install Ruby in under 2 seconds — no compilation required!

⚡ Install Gems 50% faster — using ORE ✅️!

Features

🚀 Lightning-fast Ruby installation via prebuilt binaries from rv
📦 Rapid gem installation with ore (Bundler-compatible, ~50% faster)
💾 Intelligent caching for both Ruby and gems
🔒 Security auditing via ore audit
🐧 Linux & macOS support (x86_64 and ARM64)
☕️ Gitea Actions support
🦊 Forgejo Actions support
🧊 Codeberg Actions support
🐙 GitHub Actions support

Requirements

Operating Systems: Ubuntu 22.04+, macOS 14+
Architectures: x86_64, ARM64
Ruby Versions: 3.2, 3.3, 3.4, 4.0

#	Important	Alternative
1	Windows is not supported	ruby/setup-ruby
2	Ruby <= 3.1 is not supported	ruby/setup-ruby

Key Differences with setup-ruby

Feature	setup-ruby	setup-ruby-flash
Ruby Install	~5 seconds	< 2 seconds
Gem Install	Bundler	ore (~50% faster)
`ruby-version: ruby`	✅ latest stable	✅ latest stable
`rubygems: latest`	✅	✅
`bundler: latest`	✅	✅
Windows	✅	❌
Ruby < 3.2	✅	❌
JRuby	✅	❌ (planned)
TruffleRuby	✅	❌ (planned)
Security Audit	❌	✅ (`ore audit`)

Basic Usage

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'

With Gem Installation

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ore-install: true

Using Version Files

When ruby-version is set to default (the default), setup-ruby-flash reads from:

.ruby-version
.tool-versions (asdf format)
mise.toml

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ore-install: true

Enough Talk, Where?

Inputs

Input	Description	Default
`ruby-version`	Ruby version to install (e.g., `3.4`, `3.4.1`). Use `ruby` for latest stable version, or `default` to read from version files.	`default`
`rubygems`	RubyGems version: `default`, `latest`, or a version number (e.g., `3.5.0`)	`default`
`bundler`	Bundler version: `Gemfile.lock`, `default`, `latest`, `none`, or a version number	`Gemfile.lock`
`ore-install`	Run `ore install` and cache gems	`false`
`working-directory`	Directory for version files and Gemfile	`.`
`cache-version`	Cache version string for invalidation	`v1`
`rv-version`	Version of rv to install (ignored if `rv-git-ref` is set)	`latest`
`rv-git-ref`	Git branch, tag, or commit SHA to build rv from source	`''`
`ore-version`	Version of ore to install (ignored if `ore-git-ref` is set)	`latest`
`ore-git-ref`	Git branch, tag, or commit SHA to build ore from source	`''`
`skip-extensions`	Skip building native extensions	`false`
`without-groups`	Gem groups to exclude (comma-separated)	`''`
`ruby-install-retries`	Number of retry attempts for Ruby installation (with exponential backoff)	`3`
`no-document`	Skip generating documentation (ri/rdoc) for installed gems. Creates `~/.gemrc` with `gem: --no-document` if file doesn't exist	`true`
`token`	GitHub token for API calls	`${{ github.token }}`

Outputs

Output	Description
`ruby-version`	The installed Ruby version
`ruby-prefix`	The path to the Ruby installation
`rv-version`	The installed rv version
`rubygems-version`	The installed RubyGems version
`bundler-version`	The installed Bundler version
`ore-version`	The installed ore version
`cache-hit`	Whether gems were restored from cache

Examples

Matrix Build

name: CI
on: [push, pull_request]

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        ruby: ["3.2", "3.3", "3.4", "4.0"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v5
      - uses: appraisal-rb/setup-ruby-flash@v1
        with:
          ruby-version: ${{ matrix.ruby }}
          ore-install: true
      - run: bundle exec rake test

Production Gems Only

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ore-install: true
    without-groups: 'development,test'

Latest Ruby with Latest RubyGems and Bundler

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: ruby
    rubygems: latest
    bundler: latest
    ore-install: true

Specific RubyGems Version

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    rubygems: '3.5.0'
    ore-install: true

Skip Native Extensions

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ore-install: true
    skip-extensions: true

Custom Working Directory

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ore-install: true
    working-directory: './my-app'

Specific Tool Versions

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4.1'
    rv-version: '0.4.0'
    ore-version: '0.1.0'
    ore-install: true

Custom Retry Configuration

If you experience intermittent failures due to GitHub API rate limiting, you can adjust the number of retry attempts:

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ruby-install-retries: '5'

Enable Documentation Generation

Include documentation (ri/rdoc) for installed gems (default skips documentation for faster installation):

- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: "3.4"
    ore-install: true
    no-document: false

Building rv or ore from Source

You can build rv or ore from a git branch, tag, or commit SHA instead of using a released version.
This is useful for testing unreleased features or bug fixes. Required toolchains (Rust for rv, Go for ore)
are automatically installed. Fork syntax (pboling:feat/myexperiment) is supported to test out feature branches in forks of ore or rv.

# Test an ore feature branch
- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: "3.4"
    ore-install: true
    ore-git-ref: "feat/bundle-gemfile-support"

# Test a pre-release rv tag
- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: "3.4"
    rv-git-ref: "v0.5.0-beta1"

# Test both from main branches
- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: "3.4"
    rv-git-ref: "main"
    ore-install: true
    ore-git-ref: "main"

Migration from setup-ruby

setup-ruby-flash is designed to be a near drop-in replacement for ruby/setup-ruby on supported platforms:

# Before (setup-ruby)
- uses: ruby/setup-ruby@v1
  with:
    ruby-version: '3.4'
    bundler-cache: true
- run: bundle exec rake test

# After (setup-ruby-flash)
- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: '3.4'
    ore-install: true
- run: bundle exec rake test

With Latest RubyGems and Bundler

# Before (setup-ruby)
- uses: ruby/setup-ruby@v1
  with:
    ruby-version: ruby
    rubygems: latest
    bundler: latest

# After (setup-ruby-flash)
- uses: appraisal-rb/setup-ruby-flash@v1
  with:
    ruby-version: ruby
    rubygems: latest
    bundler: latest

Acknowledgements

setup-ruby the venerable mainstay for many years, and inspiration for this project.
rv by Spinel Cooperative
ore by Contriboss

Support & Funding Info

I am a full-time FLOSS maintainer. If you find my work valuable I ask that you become a sponsor. Every dollar helps!

🥰 Support FLOSS work 🥰	Get access	"Sponsors" channel	on Galtzo FLOSS	Discord 👇️

About rv and ore

rv

rv is an extremely fast Ruby version manager written in Rust. It downloads prebuilt Ruby binaries, eliminating the need for compilation. Created by @indirect, long-time project lead for Bundler and RubyGems.

ore

ore is a fast gem installer written in Go. It's Bundler-compatible but performs downloads significantly faster using Go's concurrency features. Use bundle exec to run gem commands after ore installs your gems. Created by @seuros, a long time Rubyist, and prolific writer.

Cover photo (cropped) by Kyle Hinkson on Unsplash

💲FLOSS Funding

Peter H. Boling — Thu, 06 Nov 2025 23:39:10 +0000

Two things are true.

Many open source contributors have been laid off recently, and have not been able to find new roles. Many of these have become the fabled "person in Nebraska", made famous by XKCD #2347.
Every RubyGem, NPM, pip, cargo, etc, package you have ever used is worth at least $1 to you and the careers and products they helped build. Many people would contribute more financially to open source if more systems were in place to facilitate that.

All modern digital infrastructure (depending on) a project some random person in Nebraska has been thanklessly maintaining since 2003 - xkcd.com/2347

You may be saying:

Systems do exist to enable donations or subscriptions to developers. In fact, I can name several!

Yes, fine, three things are true. Those systems are excellent, and underutilized. Why?

Finding the funding path for a project is hard. Unless you are the meticulous type to memorize a Gemfile.lock, yarn.lock, or package-lock.json, many, if not most, of the projects at the bottom of the tree get overlooked. Since they know they will be overlooked, they often don't even bother setting up paths for donations.

What kinds of dependencies?

The nested, indirect, dependencies loaded by your direct dependencies.
The development and test dependencies which you rely on for AI to validate its work when you are vibe coding
The ones that take just as much effort to build, but fail to get recognized as valuable.

Aren't there tools that automatically dig into the dependency tree to help fund those indirect dependencies?

Yes, those are great, and I encourage people to use them. So apparently four things are true, but:

None dig down more than 3 levels into a dependency tree, and trees can be much deeper than that. In Ruby, for example:

bundle fund doesn't consider indirect dependencies
- In some contexts they only consider runtime dependencies
bundle fund doesn't consider development dependencies in Gemfile during RubyGem development

I love bundle fund, but if the command isn't run, people don't see the requests for help with funding, and it is never run automatically. I expect there are similar issues with npm fund.

Currently, funding for the majority of free (libre) open source code (FLOSS) is hard.

What if it was easy?

What if a project could tell you how to support it precisely when you are using it, and deriving value from it?

New #Ruby gem to fund open source developers whose projects get missed by other #FLOSS #funding tools which don’t cover dev deps, nor indirect deps > 3 levels down.

https://ruby.social/@galtzo/114994584740434327

👉 no tracking
👉 no network calls
👉 never forces or requires payment
👉 supports buy-once, or per-version
👉 easily silenced nags
👉 sets of related libraries share activation keys
👉 nags are opt-in for maintainers, opt-out for users
👉 nags are throttled to customizable frequency
👉 inert in non-TTY shells (i.e. production-like environments)
👉 inert when exit status is non-zero
👉 inert for many edge cases, such as an internal failure
👉 inert when a global silencing ENV variable is set (you're welcome, haters!)

Open source projects in which languages will have this ability?
Ruby
Javascript
Elixir
Python
Perl
... Join the discord if you have more ideas, and want to contribute. A lanugage just needs to have an "atexit()" style hook, i.e. a process termination hook. A bunch of languages meet the criteria, even Bash.

Cover photo by me, CC-SA 4.0.

💎 ANN: omniauth-identity v3.1.5 (Hanami/ROM Support)

Peter H. Boling — Tue, 14 Oct 2025 00:49:55 +0000

3.1.5 - 2025-10-13

TAG: v3.1.5
COVERAGE: 93.58% -- 437/467 lines in 14 files
BRANCH COVERAGE: 81.00% -- 81/100 branches in 14 files
92.39% documented

Added

Adapter support for Hanami and ROM
Complete YARD documentation
kettle-dev for easier maintenance & dev tooling

The one where omniauth-identity gains a rom adapter. Since rom is the default DB adapter for Hanami, this also makes it hanami-ready.

class Identity
  include OmniAuth::Identity::Models::Rom

  # Configure the ROM container and relation using the DSL (no `self.`):
  rom_container -> { MyDatabase.rom } # accepts a proc or a container object
  rom_relation_name :identities # optional, defaults to :identities
  owner_relation_name :owners  # optional, for loading associated owner
  # Uses OmniAuth::Identity::Model.auth_key to set the auth key (defaults to :email)
  auth_key :email
  # Optional: override the password digest field name (defaults to :password_digest)
  password_field :password_digest
end

Find a complete example after the funding info.

Support & Funding Info

I am a full-time FLOSS maintainer. If you find my work valuable I ask that you become a sponsor. Every dollar helps!

🥰 Support FLOSS work 🥰	Get access to "Sponsors" channel	on Galtzo FLOSS	Discord 👇️

As an example I'll use the code straight from the specs.

Test Harness

ROM_DB = if RUBY_ENGINE == "jruby"
  require "jdbc/sqlite3"
  require "sequel"
  Sequel.connect("jdbc:sqlite::memory:rom")
else
  require "sqlite3"
  require "sequel"
  Sequel.connect("sqlite::memory:rom")
end

require "rom"
require "rom-sql"

# Define the ROM relations
class RomTestIdentities < ROM::Relation[:sql]
  schema(:rom_test_identities) do
    attribute :id, ROM::SQL::Types::Serial
    attribute :email, ROM::SQL::Types::String
    attribute :login, ROM::SQL::Types::String
    attribute :password_digest, ROM::SQL::Types::String
    attribute :pwd_hash, ROM::SQL::Types::String
    attribute :owner_id, ROM::SQL::Types::Integer
  end
end

class RomTestOwners < ROM::Relation[:sql]
  schema(:rom_test_owners) do
    attribute :id, ROM::SQL::Types::Serial
    attribute :name, ROM::SQL::Types::String
  end
end

# Set up ROM container
ROM_CONFIG = ROM::Configuration.new(:sql, ROM_DB)
ROM_CONFIG.register_relation(RomTestIdentities)
ROM_CONFIG.register_relation(RomTestOwners)
ROM_CONTAINER = ROM.container(ROM_CONFIG)

class RomTestIdentity
  include OmniAuth::Identity::Models::Rom

  # Configure via the new DSL (no `self.`): accepts a value or a proc
  rom_container -> { ROM_CONTAINER }
  rom_relation_name :rom_test_identities
  # Use the standard Model.auth_key API to configure the auth key
  auth_key :email
  password_field :password_digest

  # Provide a simple reader for the :login attribute for specs that use a
  # non-standard auth key (e.g. `auth_key :login`). The ROM adapter stores the
  # underlying tuple in @identity_data, so delegate to it here.
  def login
    @identity_data && @identity_data[:login]
  end
end

Test

RSpec.describe(OmniAuth::Identity::Models::Rom, :sqlite3) do
  before(:all) do
    # Create the tables
    ROM_DB.create_table(:rom_test_identities) do
      primary_key :id
      String :email, null: false
      String :password_digest, null: false
      # Add the login column to support tests that use a non-standard auth_key
      String :login
      Integer :owner_id
    end

    ROM_DB.create_table(:rom_test_owners) do
      primary_key :id
      String :name, null: false
    end
  end

  before do
    # Clear the tables before each test
    ROM_DB[:rom_test_identities].delete
    ROM_DB[:rom_test_owners].delete
  end

  describe "model", type: :model do
    subject(:model_klass) { RomTestIdentity }

    describe "::authenticate" do
      it "authenticates with correct password" do
        # Insert test data
        password_digest = BCrypt::Password.create("password")
        identity_data = {email: "test@example.com", password_digest: password_digest}
        ROM_CONTAINER.relations[:rom_test_identities].insert(identity_data)

        authenticated = model_klass.authenticate({email: "test@example.com"}, "password")
        expect(authenticated).to(be_a(RomTestIdentity))
        expect(authenticated.email).to(eq("test@example.com"))
      end

      it "authenticates with custom auth_key (login) when auth_key is set to :login" do
        original = model_klass.auth_key
        model_klass.auth_key(:login)

        begin
          # Insert test data using login field
          password_digest = BCrypt::Password.create("password")
          identity_data = {login: "bob", email: "bob@example.com", password_digest: password_digest}
          ROM_CONTAINER.relations[:rom_test_identities].insert(identity_data)

          authenticated = model_klass.authenticate({login: "bob"}, "password")
          expect(authenticated).to(be_a(RomTestIdentity))
          expect(authenticated.login).to(eq("bob"))
        ensure
          model_klass.auth_key(original)
        end
      end

      it "returns false with incorrect password" do
        # Insert test data
        password_digest = BCrypt::Password.create("password")
        identity_data = {email: "test@example.com", password_digest: password_digest}
        ROM_CONTAINER.relations[:rom_test_identities].insert(identity_data)

        authenticated = model_klass.authenticate({email: "test@example.com"}, "wrong")
        expect(authenticated).to(be(false))
      end

      it "returns false for non-existent user" do
        authenticated = model_klass.authenticate({email: "nonexistent@example.com"}, "password")
        expect(authenticated).to(be(false))
      end
    end
  end
end

Photo by Ryunosuke Kikuno on Unsplash

💎 ANN: oauth2 v2.0.17

Peter H. Boling — Thu, 18 Sep 2025 06:30:38 +0000

Announcing oauth2 v2.0.17 — Static Hash for verb‑dependent token mode (Instagram‑friendly)

The oauth2 v2.0.17 is a small but useful release: it adds support for configuring verb‑dependent token transmission with a static Hash in addition to the previously available Proc. This makes integrations like Instagram’s Graph API a little simpler and slightly more performant.

TL;DR

v2.0.15 introduced verb‑dependent token mode, so you could decide per HTTP verb whether the access token should be sent in the query string or the Authorization header.
v2.0.17 lets you provide that mapping as a static Hash instead of a Proc.
Example mapping: {get: :query, post: :header, delete: :header}.

Why this matters

Some APIs (notably Instagram’s Graph API) require you to send the access token in the query for GET requests (e.g., ?access_token=...), but in the Authorization header for POST/DELETE (e.g., Authorization: Bearer ...).

In v2.0.15 we added support for a verb‑dependent mode via a Proc, like:

{mode: ->(verb) { verb == :get ? :query : :header }}

In v2.0.17 you can now configure the same behavior using a static Hash, which avoids calling a Proc for each request, keeps intent obvious at a glance, and can be trivially serialized or reused:

verb_dependent_token = {get: :query, post: :header, delete: :header}

Example: Instagram Graph API with a static Hash

Below is a concrete example that exchanges a short‑lived token for a long‑lived token, refreshes it, and then makes API calls — all while automatically placing the token in the right place per HTTP verb using the static Hash mode.

require "oauth2"

client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com")

# Start with a short‑lived token you already obtained via Facebook Login
verb_dependent_token = {get: :query, post: :header, delete: :header}

short_lived = OAuth2::AccessToken.new(
  client,
  ENV["IG_SHORT_LIVED_TOKEN"],
  mode: verb_dependent_token,
)

# 1) Exchange for a long‑lived token (GET with token in query)
#    Endpoint: GET https://graph.instagram.com/access_token
#    Params: grant_type=ig_exchange_token, client_secret=APP_SECRET
exchange = short_lived.get(
  "/access_token",
  params: {
    grant_type: "ig_exchange_token",
    client_secret: ENV["IG_APP_SECRET"],
    # access_token will be added automatically in the query
  },
)
long_lived_token_value = exchange.parsed["access_token"]

long_lived = OAuth2::AccessToken.new(
  client,
  long_lived_token_value,
  mode: verb_dependent_token,
)

# 2) Refresh the long‑lived token (GET with token in query)
#    Endpoint: GET https://graph.instagram.com/refresh_access_token
refresh_resp = long_lived.get(
  "/refresh_access_token",
  params: {grant_type: "ig_refresh_token"},
)
long_lived = OAuth2::AccessToken.new(
  client,
  refresh_resp.parsed["access_token"],
  mode: verb_dependent_token,
)

# 3) Typical API GET request (token automatically in query)
me = long_lived.get("/me", params: {fields: "id,username"}).parsed

# 4) Example POST (token automatically in Authorization header)
# long_lived.post("/me/media", body: {image_url: "https://...", caption: "hello"})

Notes

Instagram is a special case that explicitly requires query‑string tokens for GET endpoints. For most providers you should prefer header‑based tokens when possible.
If you need custom logic beyond a simple mapping, you can still use a Proc: mode: ->(verb) { ... }.

Migrating from Proc to Hash

If you already use the v2.0.15 Proc style:

{mode: ->(verb) { verb == :get ? :query : :header }}

You can switch to the Hash form in v2.0.17:

{mode: {get: :query, post: :header, delete: :header}}

Both are supported; choose whichever best fits your app. The Hash form is generally a bit faster and more explicit, while the Proc form is endlessly versatile!

Release links

Changelog entry: https://github.com/ruby-oauth/oauth2/blob/main/CHANGELOG.md#2017---2025-09-15
Tag: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.17
PR: Add Hash‑based verb‑dependent mode https://github.com/ruby-oauth/oauth2/pull/682

Thanks

Thanks to everyone using oauth2 and filing issues. Keep the feedback coming!

Support & Funding Info

I am a full-time FLOSS maintainer. If you find my work valuable I ask that you become a sponsor. Every dollar helps!

🥰 Support FLOSS work 🥰	Get access	"Sponsors" channel	on Galtzo FLOSS	Discord 👇️

Photo (cropped) by Wonder KIM on Unsplash

💎 ANN: kettle-dev v1.1.20 w/ improved CHANGELOG handling

Peter H. Boling — Mon, 15 Sep 2025 11:53:14 +0000

1.1.20 - 2025-09-15

TAG: v1.1.20
COVERAGE: 96.80% -- 3660/3781 lines in 25 files
BRANCH COVERAGE: 81.65% -- 1504/1842 branches in 25 files
77.01% documented

Added

Allow reformating of CHANGELOG.md without version bump
--include=GLOB includes files not otherwise included in default template
more test coverage

Fixed

Add .licenserc.yaml to gem package
Handling of GFM fenced code blocks in CHANGELOG.md
Handling of nested list items in CHANGELOG.md
Handling of blank lines around all headings in CHANGELOG.md

Support & Funding Info

I am a full-time FLOSS maintainer. If you find my work valuable I ask that you become a sponsor. Every dollar helps!

🥰 Support FLOSS work 🥰	Get access	"Sponsors" channel	on Galtzo FLOSS	Discord 👇️

DEV Community: Peter H. Boling

Why flag_shih_tzu is changing its default SQL for bit flags

The deploy that breaks old queries

Bit operators match the model

This is a breaking change

Performance tradeoff

Why this matters

Support & Funding Info

yard-yaml 0.1.1: safer UTF-8 handling for YAML documentation

What changed

Documentation and CI maintenance

Quick usage

Release links

yard-fence 0.9.0: cleaner YARD docs when Markdown braces get in the way

The problem

What yard-fence does

What changed in 0.9.0

Installation

Basic usage

Recommended .yardopts

Environment variables

Release links

yard-timekeeper: Stop YARD Timestamp Churn in Checked-In Docs

The Problem

What yard-timekeeper Does

Install

Configuration

Behavior

Why This Exists

Links

💎REL: oauth2 v2.0.18

Ruby #GitHub #Security

🐠 ANN: appraisal2 v3.0.6 - support frozen appraisal lockfiles

Hostile Takeover of RubyGems: My Thoughts

👣🔍️ First some background reading 🕵️

My thoughts

What I'm doing about it

⚡️ setup-ruby-flash

Features

Requirements

Key Differences with setup-ruby

Basic Usage

With Gem Installation

Using Version Files

Enough Talk, Where?

Inputs

Outputs

Examples

Matrix Build

Production Gems Only

Latest Ruby with Latest RubyGems and Bundler

Specific RubyGems Version

Skip Native Extensions

Custom Working Directory

Specific Tool Versions

Custom Retry Configuration

Enable Documentation Generation

Building rv or ore from Source

Migration from setup-ruby

With Latest RubyGems and Bundler

Acknowledgements

Support & Funding Info

About rv and ore

rv

ore

💲FLOSS Funding

Two things are true.

You may be saying:

What kinds of dependencies?

What if it was easy?

💎 ANN: omniauth-identity v3.1.5 (Hanami/ROM Support)

3.1.5 - 2025-10-13

Added

Support & Funding Info

Test Harness

Test

💎 ANN: oauth2 v2.0.17

Announcing oauth2 v2.0.17 — Static Hash for verb‑dependent token mode (Instagram‑friendly)

TL;DR

Why this matters

What `yard-timekeeper` Does