rubocop/ruby-style-guide: the community Ruby style guide and how it maps to RuboCop

What rubocop/ruby-style-guide actually is, and who reads it

This repository is a document, not a program. The top-level entries are .circleci/, .gitattributes, .github/, .gitignore, README.adoc and codespell.txt. The guide itself lives in README.adoc, written in AsciiDoc, and the README points readers to a rendered version at https://rubystyle.guide for what it calls a beautiful version with much improved navigation. There is no gem, no CLI and no configuration file to install in this repository, and the README does not describe one.

The audience is narrower than the name suggests. The introduction says the guide recommends best practices so that real-world Ruby programmers can write code maintainable by other real-world Ruby programmers, and it argues that a guide reflecting real-world usage gets used while one holding to an ideal rejected by its supposed beneficiaries risks not being used at all. That sentence is the project's whole editorial stance. If you want a rulebook that settles arguments by principle, this is the wrong document. If you want the conventions that a broad slice of the Ruby community already follows, this is the reference the rest of the ecosystem points at.

The README also names two companion documents for readers working in specific frameworks: a Ruby on Rails Style Guide and an RSpec Style Guide, both under the rubocop organization. Teams on Rails will find that the Rails guide covers ground this one deliberately leaves out.

How the guide is structured and how RuboCop relates to it

The guide is organized into sections of related guidelines. Source Code Layout is the first, opening with a rule that source files use UTF-8, and the README notes that UTF-8 has been the default source file encoding, which is why that rule needs little justification. Later sections cover naming, classes, exceptions, collections and the rest of the usual surface area.

The mechanism that matters for adoption is the relationship to RuboCop. The README states it in one line: RuboCop is a static code analyzer (linter) and formatter, based on this style guide. That is the data flow. Prose rules in README.adoc become cops in RuboCop, and RuboCop is what a team actually runs in CI or in an editor. This repository does not enforce anything. Nothing here will fail a build.

That split has a consequence the README does not spell out. Where the guide lists several acceptable styles, RuboCop has to pick one default, so a passing RuboCop run and a reading of the guide can disagree without either being wrong. The guide's own list of contested areas includes string literal quoting, spacing inside hash literals and dot position in multi-line method chaining. For those, the README says all popular styles are acknowledged and it is up to you to pick one and apply it consistently. Treat the guide as the rationale layer and RuboCop as the enforcement layer, and read both when a rule surprises you.

Building the guide locally with asciidoctor

The README gives build commands only inside a GitHub-specific conditional block, so they appear when the file is read on GitHub rather than in every rendering. They use AsciiDoctor, which the README links to for installation, and AsciiDoctor PDF for the PDF output. Run them from the repository root, where README.adoc sits.

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

# Generates README.html
asciidoctor README.adoc

The first command writes README.pdf and the second writes README.html next to the source. The -a allow-uri-read flag on the PDF command lets AsciiDoctor PDF read remote content referenced from the document; the README does not explain what remote content that is, so expect the flag to matter only if the build fails without it.

The README adds a tip for syntax highlighting in the generated document: install the rouge gem, with the command gem install rouge. Without it the build still runs, but code samples lose highlighting. The README does not document any other build dependency, and it does not describe a way to run a subset of the guide.

The escape clauses are the most useful part of the document

Most style guides bury their exceptions. This one puts them near the front. A section titled A Note about Consistency sets out a hierarchy: consistency with the guide is important, consistency within a project is more important, and consistency within one class or method is the most important. It then tells the reader to know when to be inconsistent.

The README lists four reasons to ignore a guideline. Applying it would make the code less readable even for someone used to the guide's style. Consistency with surrounding code that also breaks the rule, possibly for historic reasons. The code predates the guideline and there is no other reason to touch it. The code must stay compatible with older Ruby versions that lack the feature the guideline recommends. It also states, in its own words, do not break backwards compatibility just to comply with this guide.

For a team lead, this is the section to quote when someone cites the guide as an absolute. For a contributor, it is the section that makes the rest tolerable. The trade-off is real, though: a guide this permissive is hard to use as a gate. You cannot point at a rule and say the code violates the project's standard, because the standard itself says readability and local consistency can override it. Enforcement has to come from somewhere else, which in practice means RuboCop configuration that your team owns.

Where the guide is silent, and where it is the wrong tool

The README is candid about contested territory. It says there are areas where the Ruby community has no clear consensus, naming string literal quoting, spacing inside hash literals and dot position in multi-line method chaining, and that in those cases all popular styles are acknowledged and the choice is yours. If your goal is to end a formatting debate with an authoritative answer, the guide will not do it. It will tell you both sides are popular.

The translations are a second limitation, and the README states it directly: translations are not maintained by the editor team, so quality and completeness may vary, and translated versions often lag behind the upstream English version. If you work in a language that has a listed translation, do not assume it matches the current English text. The README lists translations for Chinese Simplified, Chinese Traditional, Egyptian Arabic, French, Japanese, Korean, Portuguese (pt-BR), Russian, Spanish and Vietnamese, each hosted in a separate repository rather than here.

The third limitation is scope. This is a Ruby guide. The README points Rails and RSpec users to separate guides, which means a Rails application following only this document will have no guidance on framework-specific conventions. And because the repository ships no executable, anyone who wants automated checks has to go to RuboCop, which the README describes as based on this guide rather than identical to it.

Alternatives: house guides and the framework guides

The most direct alternative is a company's own style guide. The related searches around this project include Shopify/Ruby-style guide and airbnb ruby style guide, which reflects how common that pattern is: large engineering organizations publish their own rules rather than deferring to the community document. The difference in approach is ownership. A house guide can be opinionated where the community guide refuses to be, because it only has to satisfy one codebase and one hiring pipeline. It can also mandate a single answer on string quoting and dot position, which this guide explicitly declines to do. The cost is that a house guide has to be maintained by the company that wrote it, and it will diverge from the wider ecosystem over time.

The second alternative is the pair of guides the README itself recommends. The Ruby on Rails Style Guide and the RSpec Style Guide are separate repositories in the same organization, and they cover conventions this document does not. If your work is mostly Rails application code, starting with the community Ruby guide alone will leave gaps that the Rails guide fills. The three are meant to be read together, not as competing standards.

A third option, for teams that want enforcement without prose, is to skip the document and configure RuboCop directly. That works, but you lose the rationale. The README's stated goal is to include the reasoning behind guidelines, and when a cop's default surprises a new contributor, the explanation usually lives in this repository rather than in RuboCop's own documentation.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-07-20, which is recent enough that the guide is being touched. The README describes the guide as evolving over time as additional conventions are identified and past conventions are rendered obsolete by changes in Ruby itself, so updates are expected rather than exceptional. There are no releases to track, which fits a document: you consume the current state of README.adoc rather than a version number. The practical upgrade cost is reading a diff on a long AsciiDoc file when you want to know what changed.

On licensing, the repository metadata available here does not state a licence, and the README does not discuss one. That matters more than it would for a library, because style guides get copied into internal wikis, onboarding documents and code review checklists. Before you reproduce the text inside your company, check the repository for a licence file or terms, since nothing in the README grants or restricts reuse. This is a factual gap, not a legal opinion, and it is the kind of thing to resolve before the guide ends up pasted into a handbook.

There is also a maintenance cost the README implies but does not quantify. Because RuboCop is based on this guide, a change here can eventually surface as a changed cop default in a RuboCop upgrade, and a rule your team disabled may become a rule you have to re-disable. Nothing in the README documents that migration path.

Editorial conclusion

Adopt it if you want one written reference for Ruby layout, naming and consistency that RuboCop's cops are based on, and if you are willing to treat the README's own escape clauses as part of the guide. Do not adopt it expecting an installable tool; the repository is AsciiDoc source, and the analyzer is RuboCop. Before you cite a rule to your team, open the section in README.adoc and read the rationale next to it, because the README states that where the Ruby community has no consensus it lists the popular styles and leaves the choice to you.

Frequently asked questions

Official sources

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