RuboCop's Rails Style Guide: config layout, routing verbs, and the rules nothing checks
A community-driven Ruby on Rails style guide
At a glance
- What is it?
- The community guide behind rubocop-rails is a single AsciiDoctor file of Rails prescriptions on configuration, routing and controllers, with no linter and no releases.
- Who is it for?
- Treat this repository as a review checklist rather than a tool. Its value is the rationale attached to each prescription, and its limits are just as concrete: it ships no linter and no releases.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 42 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rubocop/rails-style-guide6,501 ★ · -3
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| rubocop/rails-style-guide | 6.5k | 6.5k |
-3 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One AsciiDoctor file holds every rule
Everything the project ships sits in one document. The repository tracks .circleci/, .github/, .gitignore, README.adoc and codespell.txt on master, and it has no releases, no gem and no executable, so there is nothing to install and no code to call. Bozhidar Batsov opens with a quote from RoboCop about role models and states the goal plainly: code that real world Rails programmers can write should be maintainable by other real world Rails programmers. He also says the guide is complementary to the community driven Ruby coding style guide rather than a replacement for it. The file header carries AsciiDoctor attributes for the table of contents, a section anchor prefix, and rouge as the source highlighter, which is part of why the rendered edition at rails.rubystyle.guide navigates better than the raw text.
Rendering README.adoc yourself needs AsciiDoctor and rouge
Reading the guide needs a browser, and the introduction links a rendered edition with better navigation. Building your own copy needs AsciiDoctor and a checkout that holds README.adoc. Syntax highlighting in the output comes from one extra gem, and the PDF command is told to allow URI reads so remote images resolve.
# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc
# Generates README.html
asciidoctor README.adocgem install rougeNothing else in the repository takes part: there is no build script and no release artifact, so these commands are the whole local toolchain the file names, and both outputs land beside README.adoc.
Each rule arrives with its reason and an anchor id
The guide is organised as sections of related rules, and most entries pair a prescription with the reason for it. Its premise is editorial rather than technical: a style guide that reflects real world usage gets used, while one that holds to an ideal rejected by the people it is meant to help risks not getting used at all, no matter how good it is. Every entry also carries a bracketed anchor id, which is what makes a deep link into a single rule possible in the rendered edition and what lets the surrounding sections be cited one by one. Controllers get a section of their own, opening with the demand that they stay skinny, retrieve data for the view layer, and keep business logic out.
config.load_defaults falls behind when Rails moves on
When you move to a newer Rails version, your application's configuration setting stays on the previous version. The guide treats that as something to fix rather than skip: it says config.load_defaults should match your Rails version so you pick up the latest recommended practices, and the only example it gives is a single line marked good. The number in that line is 6.1, so the sample is pinned to one release family instead of tracking whatever is newest.
The wildcard route puts every controller action behind GET
The harshest route rule in the file concerns the legacy wildcard pattern, and the file marks it very bad for a concrete reason: it makes all actions in every controller accessible via GET requests. A narrower rule sits next to it and is stricter still, since match is not to be used at all unless one action has to answer several of [:get, :post, :patch, :put, :delete] through the :via option. The bad example is printed as a single line so the shape of the old routing table is unmistakable. No migration recipe appears for a routes.rb that already carries the wildcard, so removing one is a manual edit you own.
shallow: true trims both the path and the helper
Nesting depth gets a rule with a threshold and two named costs. Once routes go more than one level deep, the guide asks for shallow: true, and it names what goes away: URLs of the form posts/1/comments/5/versions/7/edit and helpers of the form edit_post_comment_version. The example nests posts, comments and versions under one shallow block. What the file leaves open is the boundary case, since it says nothing about exactly one level of nesting where shallow has nothing to remove, and it gives no guidance for deep paths that come from a URL scheme rather than from the resources tree.
Member and collection verbs replace hand written paths
Adding an extra action to a RESTful resource is where hand written routes come from, and the guide answers with two options instead of a new path. A verb on a single record uses on: :member, a verb across the whole set uses on: :collection, and once there is more than one of them the alternative block syntax groups them under member do or collection do. The rule also pushes back on the premise in parentheses, asking whether you really need those extra actions at all. The block form is printed for both example resources so the grouped and ungrouped shapes sit side by side.
Config files split by environment, with YAML for the rest
Configuration gets a file layout before it gets opinions. Initializer code belongs in config/initializers, with one file per gem named after that gem. Settings that differ per environment belong in the matching files under config/environments, and settings that apply everywhere belong in config/application.rb. Extra environments are discouraged: development, test and production are named as the defaults, and a production-like setup such as staging is supposed to run on environment variables instead. Anything further goes into YAML under config/, loadable through config_for since Rails 4.2, and assets needing precompilation are listed with a plus equals line inside the production environment file. The layout is settled; the values you put in it are your call.
Enforcement lives in rubocop-rails, not in this repository
The guide cannot check itself against an application, and it points at the tool that does. The introduction names RuboCop as a static code analyzer and formatter and names its rubocop-rails extension as being based on this document, so anything you automate arrives through a linter's configuration instead of from here. That leaves the prose rules exactly where they are, including the advice about environment files and the ban on the wildcard route, and no tool in this repository will flag either. Coverage is uneven in ways the file admits too, since a note says some of the advice applies only to recent versions of Rails, and translations exist only in Japanese and Russian.
Editorial conclusion
Treat this repository as a review checklist rather than a tool. Its value is the rationale attached to each prescription, and its limits are just as concrete: it ships no linter and no releases. Check config.load_defaults against the Rails version you actually run, and expect to verify routing and layout advice by hand.
Frequently asked questions
What does a Rails style guide usually include, and what does this one cover?
This one is arranged as sections of related rules, starting with configuration, then routing and controllers, and it attaches a rationale to most of them. Bozhidar Batsov frames it as complementary to the community driven Ruby coding style guide, and the last recorded push to the repository is 2026-10-04.
Is Rails still relevant, and is this guide still updated?
The repository is not archived and its last recorded push is 2026-10-04, so the file keeps receiving edits. The guide itself warns that some of the advice applies only to recent versions of Rails, and its config.load_defaults example is still pinned to 6.1, so an old prescription is worth checking against the version you run.
Which are the three most widely used style guides, and how does this one relate to them?
The file does not rank style guides or count adoption. It only positions itself as complementary to the community driven Ruby coding style guide from the RuboCop organization, and it points at the rubocop-rails extension as the automated counterpart built on these rules.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rubocop-rails-style-guide)Star history chart for your README
[](https://hysenlabs.com/projects/rubocop-rails-style-guide)Was this useful?