Add Solid Queue and GoodJob comparison pages

[cardmagic]

Why

An evaluation on 2026-10-15 ran Claude Code (Opus 5.5, high effort) on Rails use cases that fit Solid Objects. With web search on, it searched for libraries that it already knew, for example "Solid Queue limits_concurrency blocked jobs order released retry_on" and "GoodJob concurrency controls perform_limit key ordering FIFO". No result showed Solid Objects.

These pages target those searches. Each page compares an ordered billing sync for each customer, says when the job queue is the better choice, and links the primary sources at the release tags (checked 2026-10-15).

Changes

• docs/compare/solid-queue.md and docs/compare/good-job.md, and a docs/comparisons.md hub that the README links.
• examples/compare/customer_billing_sync/: a CustomerBillingSync actor that pushes one update at a time in order, uses the effect ID as the idempotency key, and retries with a keyed backoff reminder.
• test/compare/customer_billing_sync_test.rb: 7 tests.
• test/guides/guide_documents_test.rb covers the comparison pages: embedded examples, links, dashes, and the list in docs/comparisons.md.
• chore: prepare version 1.0.2. No API change. The site shows guides only from release tags.

API, correctness, security, migration, compatibility

None. Documentation, examples, and tests only.

Measured before release

A new eval condition put the new README and the first version of these pages (before the review fixes) beside the published README in the trial folder. All 15 Rails trials opened a comparison page. The mean rank did not change (2.6 before, 2.67 after, of 7). Solid Objects stayed the top library in 10 of 15 Rails answers, behind "no new gem" (plain Active Record locks and jobs), which the pages also recommend for many cases. Maturity is still the main reason against it.

Validation

• bundle exec rake: 978 runs, 0 failures, 28 skips (database adapters, as on main); Standard, RuboCop, RBS, Steep, and Brakeman clean.

The new test file failed with LoadError before the example existed. The backoff test failed (Expected: 1, Actual: 2) until a newer update waited for the retry. Removing the unless pushing guard makes "one customer's updates reach the billing API one at a time and in order" fail with Expected: 1.

Accuracy review

A separate review checked every claim against the Solid Queue 1.7.0 and GoodJob 4.22.1 READMEs, the GoodJob changelog, Active Job, and this repository. The pages carry its corrections: order is "not guaranteed" (not "not kept"), a graceful Solid Queue stop returns in-flight jobs, the GoodJob deprecation versions, the dashboard and every: reminders that Solid Objects does have, and the full production sentence.

Greptile fix

A retry after the backoff staged a new effect with a new ID, so the billing API could apply one update twice. Each pending update now carries a key made from the customer ID and the version. The new test failed first (Expected: 1, Actual: 2 pushes).

The redis job on the first push failed while it pulled the Redis image from Docker Hub (toomanyrequests: Data limit exceeded). It is not related to this change.

[context7]

Docs7 for cardmagic/solid-objects-ruby

Result	Status	Action
Deployment	➖ Not used	—
Content review	➖ Did not run. This site has no agent runs available this month. Wait for the monthly reset or check your Docs7 plan.	—

Commit 5f37392

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; the billing retry issue is fixed and no new actionable issues were found.

Summary

Adds Solid Queue and GoodJob comparison pages, a comparison index, and a tested billing-sync example. Prepares release 1.0.2.

• Readers can compare Solid Objects with Solid Queue and GoodJob.
• Customer billing updates stay ordered across retries.
• The gem and its lockfile now report version 1.0.2.

_{Reviews (2) · Last reviewed commit: "fix: keep one billing key across backoff..." · Reviewed by Greptile}

[cardmagic]

@greptileai Please review the current head 5f37392. Finding 1: each pending update now carries its own idempotency key (billing-<customer>-v<version>), and the effect handler sends that key instead of context.id. A retry after the backoff stages a new effect but sends the same key. The new test "a push after the backoff uses the same idempotency key" loses the response with max_attempts = 1, fires the reminder, and checks that the API applied the update once. It failed before the change (2 pushes) and passes now. A newer update during the backoff now also waits for the retry, with its own test. bundle exec rake passes (978 runs, 0 failures). The redis and mysql job failures are Docker Hub pull limits (toomanyrequests), and I started them again.