# 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

```ruby
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`:

```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

```ruby
# 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](https://pacmon.dev/agents/).