Dependency notes for Ruby

A Gemfile takes comments, but a # after a gem line has room for a few words. The parts that matter do not fit there: why this gem and not another, why it stays below the next major, and what to run before bundle update moves it.

Pacmon keeps a note for each gem in .pacmon/ruby/DEPENDENCY-NOTES.md, beside the Gemfile, and shows it on the gem's line. A gemspec is read too, and the gems it declares share the same notes file.

What Pacmon reads

• Manifest: Gemfile, gems.rb, *.gemspec
• Notes file: .pacmon/ruby/DEPENDENCY-NOTES.md
• Section heading: the literal gem name as written: ## rails, ## rspec

Pacmon reads literal gem calls in Gemfile or gems.rb, with literal group and platform scopes; plus literal add_dependency, add_runtime_dependency and add_development_dependency calls on the active specification receiver in *.gemspec. Ruby is never evaluated. Dynamic names, method/class/module bodies, eval_gemfile, Gemfile.lock and transitive gems are ignored. Gem names are matched exactly.

Pacmon never runs Ruby, Bundler or RubyGems, so it needs no Ruby SDK. In JetBrains IDEs, the Ruby editor support comes from RubyMine or the Ruby plugin.

Example

source "https://rubygems.org"

gem "rails", "~> 7.2.0"
gem "pg", "~> 1.5"
gem "sidekiq", "~> 7.3"

group :development, :test do
  gem "rspec-rails", "~> 7.1"
end

.pacmon/ruby/DEPENDENCY-NOTES.md:

## sidekiq

Background jobs. Queues and retry limits are in config/sidekiq.yml.

### Agent notes

- purpose: background jobs for the mailers, the webhooks and the nightly exports
- constraint: stay on 7.x until the Redis servers are upgraded (OPS-88)
- verify: `bundle exec rspec spec/jobs`
- verified: 7.3.9

The heading is the gem name exactly as it is written, case included: gem "RedCloth" is ## RedCloth, not ## redcloth. A gem that both the Gemfile and the gemspec beside it declare has one section.

Comments in the Gemfile

# sidekiq: stay on 7.x until the Redis servers are upgraded
gem "sidekiq", "~> 7.3"
gem "pg", "~> 1.5" # Postgres driver for ActiveRecord

A Gemfile is Ruby code: # starts a comment that runs to the end of the line. bundle add appends a gem at the end of the file. bundle remove deletes the gem's line, and a comment at the end of it, but leaves a comment on the line above behind, now describing nothing.

Pinning a version

A version on its own, gem "rails", "7.2.1", means that version only, the same as "= 7.2.1". "~> 7.2.0" accepts >= 7.2.0 and < 7.3.0, and "~> 7.2" accepts >= 7.2 and < 8.0.

Gemfile.lock records the exact version of every gem, direct or transitive, and bundle install installs exactly that. bundle update sidekiq moves sidekiq and the gems it depends on; with --conservative, those stay where they are. Why a gem is held goes in its note: the constraint: line above keeps sidekiq on 7.x.

For AI coding agents

An agent reads a gem's section before it adds, upgrades or removes the gem, runs what verify: says after the version moves, and records the version it checked in verified:. See the rules agents follow.