rubocop/rails-style-guide: Community Ruby on Rails Coding Standards

What the Rails Style Guide Covers and Who It Is For

Ruby on Rails ships with its own conventions, but those conventions do not address every coding decision a team faces: how to organise initializers, whether to use namespaced routes, how to write controller actions, or how to handle callbacks in models. The rails-style-guide fills that gap by collecting the accumulated preferences of the Rails community into a single document.

The guide was created by Bozhidar Batsov, who is also the creator of RuboCop. The README describes it as a complementary guide to the ruby-style-guide, covering Rails-specific patterns rather than general Ruby style. The intended audience is real-world Rails programmers who want to write code maintainable by other real-world Rails programmers.

The README's introduction includes an explicit statement of philosophy: a style guide that reflects real-world usage gets adopted, while one that holds to ideals rejected by its intended users does not. Rules are not invented from theory; they come from practice and community feedback.

The guide is available as a formatted HTML document at https://rails.rubystyle.guide with navigation that the raw AsciiDoc file in the repository does not provide.

How the Guide Is Organised: Rule Anchors and Sections

The guide is a single AsciiDoc file, README.adoc, divided into thematic sections. Each rule has a named anchor that allows direct linking. For example, the rule about placing custom initialization code in config/initializers is anchored as [[config-initializers]].

The major sections cover Configuration, Routing, Controllers, Models, Migrations, Views, Mailers, Active Record Queries, and Time. Within each section, rules are grouped by related concern. Rules show bad and good code examples side by side using [source,ruby] blocks.

The routing section alone covers member and collection routes, nested routes, shallow routes, namespaced routes, and the prohibition on wild controller routes. The configuration section covers where to put gem initializers, how to separate dev/test/production configs, and how to use Rails.application.config_for for YAML configuration.

Translations exist in Japanese and Russian, maintained in separate repositories and linked from the main README.

Reading, Generating, and Browsing the Guide

The canonical online version is at https://rails.rubystyle.guide, rendered from the AsciiDoc source with improved navigation. For offline use or internal distribution, the README documents how to generate PDF and HTML versions locally.

To generate a PDF:

asciidoctor-pdf -a allow-uri-read README.adoc

To generate HTML:

asciidoctor README.adoc

For syntax highlighting in the generated documents, the README recommends installing the rouge gem:

gem install rouge

The source-highlighter directive in the AsciiDoc header references rouge. Without it, the code examples in the generated document appear without colour differentiation. The asciidoctor and asciidoctor-pdf tools are separate gems not bundled with the repository; they must be installed before running the generation commands.

Configuration and Routing Rules: Reading the Code Examples

The rules use annotated code examples to make intent unambiguous. The configuration section shows how load_defaults should match the Rails version to take advantage of the latest recommended practices:

config.load_defaults 6.1

The YAML configuration section shows the Rails 4.2 config_for method:

Rails::Application.config_for(:yaml_file)

The routing section shows the correct way to add non-RESTful actions using member routes instead of ad-hoc path definitions:

resources :subscriptions do
  get 'unsubscribe', on: :member
end

It contrasts this with the incorrect alternative of defining a bare path outside the resources block, and explains why: the member route produces a named helper and keeps the URL structure predictable. The bad/good examples make the rule actionable without requiring interpretation.

The README also prohibits the legacy wild controller route pattern (match ':controller(/:action(/:id(.:format)))'), which makes all controller actions accessible via GET requests and creates a security surface that RESTful routing avoids.

The Relationship Between This Guide and rubocop-rails

The README documents a direct relationship: RuboCop, the static code analyzer and formatter, has a rubocop-rails extension based on this style guide. This means many of the rules in the guide have corresponding cops in the rubocop-rails gem.

For teams that want automated enforcement rather than a manual reference, rubocop-rails is the practical tool. It integrates into the development workflow through the standard RuboCop configuration file (.rubocop.yml), runs on pull requests in CI, and reports violations with file name, line number, and the cop name. The cop name can be traced back to the specific rule in this guide.

The style guide predates and informs rubocop-rails: it documents the intent behind each rule in prose, while rubocop-rails provides the automated check. Some rules in the guide may not yet have a corresponding rubocop-rails cop; the guide is the canonical specification, and the linter follows it.

Limitations and What the Guide Does Not Address

The README includes an explicit caveat: some advice is applicable only to recent versions of Rails. The guide does not specify which rules apply to which versions. A team running an older Rails version must read each rule with that uncertainty in mind.

The guide is a text document. It cannot be applied to existing code automatically without rubocop-rails. For a codebase that has not followed these conventions historically, adopting the guide means either a manual code review pass, a rubocop-rails run with auto-correct, or both.

No license is listed in the repository. The primary language of the repository is listed as unknown in the metadata, consistent with the content being AsciiDoc prose rather than executable code. The absence of a license means contributors and users do not have explicit permission to reproduce or modify the content, which is an unusual gap for a document intended for wide adoption.

The repository has no GitHub releases and no package on any package manager. Updates arrive as commits to master, so tracking changes requires following the git log rather than release notes.

The Official Rails Guides as a Different Kind of Reference

The official Ruby on Rails Guides at guides.rubyonrails.org are a different kind of document. They explain how Rails works: what Active Record associations do, how the router maps URLs to controllers, how the asset pipeline processes files. They are descriptive, not prescriptive.

The rails-style-guide is prescriptive: given that you know how Rails routing works, here is the preferred way to write your routes. The two documents address different questions. A new Rails developer reaches for guides.rubyonrails.org to understand the framework. A developer writing code for a team reaches for the style guide to make decisions consistent with community conventions.

There is no overlap in content. The official guides are maintained by the Rails core team and updated with each major version. The rails-style-guide is community-maintained and evolves based on contributor consensus, with Batsov as the original author and primary maintainer. The last push to the style guide repository was on 2026-07-21.

Editorial conclusion

The rails-style-guide is useful as a reference when establishing Rails coding conventions in a team and as the source document behind rubocop-rails automated enforcement. Its limitation as a standalone resource is that it does not enforce anything on its own. Teams that want automated checking should pair it with the rubocop-rails gem. The README notes that some advice applies only to recent Rails versions without specifying which, so verify the relevant sections against your Rails version before adopting a rule. No license is documented in the repository, which is an unusual gap for a widely referenced style guide.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. rubocop/rails-style-guide on GitHub