How we work / Sample Rails App Audit
What a Rails App Audit looks like
The Rails App Audit ends with a written report in this format: where your versions stand, what blocks an upgrade, what is risky to change, and a staged plan with honest effort estimates. You keep it whether or not we do the follow-on work.
Sample format — this is the document format you receive on a real engagement. Everything below is illustrative: the business, numbers, and findings are examples, not client data.
Prepared for: Example Subscriptions Ltd. (illustrative)
Scope: Versions, dependencies, tests, performance, security
Format: 10–20 pages, written
1. Executive summary
Three sentences a non-technical owner can act on: the app runs on Rails and Ruby versions that no longer receive security fixes, the billing flow has no automated tests, and two abandoned gems block the next step. The recommended path is four staged upgrades on the main branch, each one shipped to production before the next begins.
2. Version and support status
Each component is checked against its official maintenance policy on the audit date. Illustrative rows:
| Component | Current | Support status | Target |
|---|---|---|---|
| Rails | 6.1 | No security fixes | 8.1 |
| Ruby | 3.0 | End of life | 3.4 |
| PostgreSQL | 13 | End of life | 17 |
| Sidekiq | 6.x | Upgrade with Ruby/Rails | Current major |
3. Findings, by severity
Each finding names the evidence (the file, the query, the gem), the business impact, and the effort to fix. Illustrative rows:
| Severity | Finding | Impact | Est. fix |
|---|---|---|---|
| Critical | Rails and Ruby versions no longer receive security fixes | Publicly disclosed vulnerabilities stay unpatched in production | staged plan |
| High | Billing and signup flows have no request or system tests | No safe way to tell whether any upgrade step broke revenue | 3–4 days |
| High | Two gems are abandoned with no release supporting Rails 7 | Blocks the next version step until replaced | 1–2 days each |
| Medium | Admin invoice index loads each customer separately (N+1 queries) | Slowest page in the app; grows with every customer | half day |
4. The upgrade plan
- Step 0 — tests first: request and system tests around signup, billing, and admin, recorded against current behaviour. No versions change.
- Step 1 — Ruby 3.0 → 3.2, then 3.4, each its own deploy, so a failure has one cause.
- Step 2 — replace the two abandoned gems behind the new tests.
- Step 3 — Rails 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1, one minor version at a time with dual-boot CI.
- Each step has a written rollback (revert the lockfile, redeploy) and leaves a working app.
5. Estimate and options
Effort per step as a range, with the assumptions that would move it. Where it applies, the report also prices the alternative — staying on the current version with compensating controls — so the decision is yours with the numbers in front of you. The audit fee is credited in full against follow-on work.
Our approach to staged upgrades is written out in full in the Rails upgrade reference design, and current support dates are in Rails and Ruby support dates.
Want documents like this about your systems?
Describe the problem in plain language — broken, slow, manual, or missing. We'll tell you honestly whether and how we can help.
- 01We reply within one business day
- 02A short call to understand the problem
- 03A written scope and fixed quote — no obligation