standard 0.1.0 → 1.51.1

data/README.md

@@ -1,246 +1,266 @@
-## Standard - Ruby style guide, linter, and formatter
+<img src="https://user-images.githubusercontent.com/79303/233717126-9fd13e6d-9a66-4f1c-b40c-fe875cb1d1b4.png" style="width: 100%"/>
 
-[![CircleCI](https://circleci.com/gh/testdouble/standard.svg?style=svg)](https://circleci.com/gh/testdouble/standard)
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Tests](https://github.com/standardrb/standard/actions/workflows/test.yml/badge.svg)](https://github.com/standardrb/standard/actions/workflows/test.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
 [![Gem Version](https://badge.fury.io/rb/standard.svg)](https://rubygems.org/gems/standard)
 
-This gem is a spiritual port of [StandardJS](https://standardjs.com) and aims
-to save you (and others!) time in the same three ways:
+The `standard` gem brings the ethos of [StandardJS](https://standardjs.com) to
+Ruby. It's a linter & formatter built on
+[RuboCop](https://github.com/rubocop/rubocop) and provides an **unconfigurable
+configuration** to all of RuboCop's built-in rules as well as those included in
+[rubocop-performance](https://github.com/rubocop/rubocop-performance). It also
+supports plugins built with
+[lint_roller](https://github.com/standardrb/lint_roller), like
+[standard-rails](https://github.com/standardrb/standard-rails) and
+[standard-sorbet](https://github.com/standardrb/standard-sorbet).
+
+Standard Ruby was created and is maintained by the team at [Test
+Double](https://testdouble.com), because we appreciate the importance of
+balancing predictable, consistent code with preserving developer autonomy. 💚
+
+Topics covered in this README:
+
+* [Wait, what?!](#wait-did-you-say-unconfigurable-configuration)
+* [Basic usage](#usage)
+* [Editor & CI integrations](#integrating-standard-into-your-workflow)
+* [Ignoring errors](#ignoring-errors)
+* [Configuration options](#configuring-standard)
+* [Plugins and extensions](#extending-standard)
+* [Community](#who-uses-standard-ruby)
+
+## Wait, did you say unconfigurable configuration?
+
+Yes, Standard is unconfigurable. See, pretty much every developer can agree that
+automatically identifying and fixing slow, insecure, and error-prone code is a
+good idea. People also agree it's easier to work in codebases that exhibit a
+consistent style and format. So, what's the problem? **No two developers will
+ever agree on what all the rules and format should be.**
+
+This has resulted in innumerable teams arguing about how to configure their linters
+and formatters over literal decades. Some teams routinely divert time and energy
+from whatever they're building to reach consensus on where commas should go.
+Other teams have an overzealous tech lead who sets up everything _his favorite
+way_ and then imposes his will on others. It's not uncommon to witness
+passive-aggressive programmers change a contentious rule back-and-forth,
+resulting in both acrimony and git churn (and acrimony _about_ git churn).
+Still, most developers give way to whoever cares more, often resulting in an
+inconsistent configuration that nobody understands and isn't kept up-to-date
+with changes to their linter and its target language. Whatever the approach,
+time spent
+[bikeshedding](https://blog.testdouble.com/posts/2019-09-17-bike-shed-history/)
+is time wasted.
+
+**But you can't configure Standard Ruby.** You can take it or leave it. If this
+seems presumptive, constraining, and brusque: you're right, it usually does feel
+that way at first. But [since
+2018](https://www.youtube.com/watch?v=uLyV5hOqGQ8), the Ruby community has
+debated Standard Ruby's ruleset, ultimately landing us on a
+[sensible](/config/base.yml)
+[set](https://github.com/standardrb/standard-performance/blob/main/config/base.yml)
+of
+[defaults](https://github.com/standardrb/standard-custom/blob/main/config/base.yml)
+that—_while no one person's favorite way to format Ruby_—seems to be good enough
+for most of the ways people use Ruby, most of the time.
+
+If you adopt Standard Ruby, what's in it for you? Time saved that would've been
+spent arguing over how to set things up. Also, seamless upgrades: we stay on top
+of each new RuboCop rule and update our configuration on a monthly release
+cadence. But the best part of adopting Standard as your linter and formatter?
+**You'll spend a whole lot less time thinking about linters and formatters.**
+
+So please, give Standard Ruby a try. If you're like [these
+folks](#who-uses-standard-ruby), you'll soon realize that the value of a linter
+is in using one at all and not in the particulars of how it's configured.
 
-* **No configuration.** The easiest way to enforce consistent style in your
-  project. Just drop it in.
-* **Automatically format code.** Just run `standardrb --fix` and say goodbye to
-  messy or inconsistent code.
-* **Catch style issues & programmer errors early.** Save precious code review
-  time by eliminating back-and-forth between reviewer & contributor.
+## Usage
 
-No decisions to make. It just works. Here's a [⚡ lightning talk ⚡](https://www.youtube.com/watch?v=uLyV5hOqGQ8) about it.
+### Install
 
-Install by adding it to your Gemfile:
+Getting started is as easy as `gem install standard` or throwing it in your
+project's Gemfile and running `bundle install`:
 
 ```ruby
-gem "standard", group: [:development, :test]
+gem "standard"
 ```
 
-And running `bundle install`.
-
-Run Standard from the command line with:
+### Running Standard Ruby
 
-```ruby
-$ bundle exec standardrb
-```
-
-And if you'd like, Standard can autocorrect your code by tacking on a `--fix`
-flag.
-
-## StandardRB — The Rules
-
-- **2 spaces** – for indentation
-- **Double quotes for string literals** - because pre-committing to whether
-  you'll need interpolation in a string slows people down
-- **1.9 hash syntax** - When all the keys in a hash literal are symbols,
-  Standard enforces Ruby 1.9's `{hash: syntax}`
-- **Semantic blocks** - `{`/`}` for functional blocks that return a value, and
-  `do`/`end` for procedural blocks that have side effects. More
-  [here](http://www.virtuouscode.com/2011/07/26/the-procedurefunction-block-convention-in-ruby/)
-  and [here](https://github.com/rubocop-hq/ruby-style-guide/issues/162)
-- **Leading dots on multi-line method chains** - chosen for
-  [these](https://github.com/testdouble/standard/issues/75) reasons.
-- **Spaces inside blocks, but not hash literals** - In Ruby, the `{` and `}`
-  characters do a lot of heavy lifting. To visually distinguish array literals
-  from blocks, Standard enforces that (like arrays), no leading or trailing
-  spaces be added to pad hashes
-- **And a good deal more**
-
-If you're familiar with [RuboCop](https://github.com/rubocop-hq/rubocop), you
-can look at Standard's current base configuration in
-[config/base.yml](/config/base.yml).
-
-**[NOTE: until StandardRB hits 1.0.0, we consider this configuration to be a
-non-final work in progress and we encourage you to submit your opinions (and
-reasoned arguments) for the addition, removal, or change to a rule by [opening
-an issue](https://github.com/testdouble/standard/issues/new). If you start using
-Standard, don't be shocked if things change a bit!]**
+Once installed, you can run Standard from the command line via its built-in
+executable or as a Rake task.
 
-## Usage
+Standard Ruby's binary is named `standardrb` to distinguish it from
+[StandardJS](https://github.com/standard/standard):
 
-Once you've installed Standard, you should be able to use the `standardrb`
-program. The simplest use case would be checking the style of all Ruby
-files in the current working directory:
-
-```bash
-$ bundle exec standardrb
-standard: Use Ruby Standard Style (https://github.com/testdouble/standard)
-standard: Run `standardrb --fix` to automatically fix some problems.
-  /Users/code/cli.rb:31:23: Style/Semicolon: Do not use semicolons to terminate expressions.
+```
+$ standardrb
 ```
 
-You can optionally pass in a directory (or directories) using the glob pattern. Be
-sure to quote paths containing glob patterns so that they are expanded by
-`standardrb` instead of your shell:
+And the Rake task can be run if your Rakefile includes `require
+"standard/rake"`.  This will load the `standard` task, allowing you to run:
 
-```bash
-$ bundle exec standardrb "lib/**/*.rb" test
+```
+$ rake standard
 ```
 
-**Note:** by default, StandardRB will look for all `*.rb` files (and some other
-files typically associated with Ruby like `*.gemspec` and `Gemfile`)
+Either way, Standard will inspect any Ruby files found in the current directory
+tree. If any errors are found, it'll report them. If your code is
+standard-compliant, it will get out of your way by quietly exiting code 0.
 
-### Using with Rake
+### Fixing errors
 
-Standard also ships with Rake tasks. If you're using Rails, these should
-autoload and be available after installing Standard. Otherwise, just require the
-tasks in your `Rakefile`:
+A majority of Standard's rules can be safely fixed automatically.
 
-```ruby
-require "standard/rake"
 ```
+# CLI
+$ standardrb --fix
 
-Here are the tasks bundled with Standard:
-
-```
-$ rake standard     # equivalent to running `standardrb`
-$ rake standard:fix # equivalent to running `standardrb --fix`
+# Rake
+$ rake standard:fix
 ```
 
-You may also pass command line options to Standard's Rake tasks by embedding
-them in a `STANDARDOPTS` environment variable (similar to how the Minitest Rake
-task accepts CLI options in `TESTOPTS`).
+Because we're confident Standard's fixes won't change the behavior of our code,
+we typically run with fix enabled _all the time_ because it saves us from having
+to look at and think about problems the computer can solve for us.
+
+### Applying unsafe fixes
+
+There are a number of other rules that can be automatically remedied, but not
+without the risk of changing your code's behavior. While we wouldn't recommend
+running it all the time, if the CLI suggests that additional errors can be fixed
+_unsafely_, here's how to do that:
 
 ```
-# equivalent to `standardrb --format progress`:
-$ rake standard STANDARDOPTS="--format progress"
+# CLI
+$ standardrb --fix-unsafely
 
-# equivalent to `standardrb lib "app/**/*"`, to lint just certain paths:
-$ rake standard STANDARDOPTS="lib \"app/**/*\""
+# Rake
+$ rake standard:fix_unsafely
 ```
 
-## What you might do if you're clever
+So long as your code is checked into source control, there's no mortal harm in
+running with unsafe fixes enabled. If the changes look good to you and your
+tests pass, then it's probably no more error prone than manually editing
+every change by hand.
 
-If you want or need to configure Standard, there are a _handful_ of options
-are available creating a `.standard.yml` file in the root of your project.
+## Integrating Standard into your workflow
 
-Here's an example yaml file with every option set:
+Because code formatting is so integral to programming productivity and linter
+violations risk becoming bugs if released into production, tools like
+Standard Ruby are only as useful as their integration into code editors and
+continuous integration systems.
 
-```yaml
-fix: true               # default: false
-parallel: true          # default: false
-format: progress        # default: Standard::Formatter
-ruby_version: 2.3.3     # default: RUBY_VERSION
-default_ignores: false  # default: true
+### Editor support
 
-ignore:                 # default: []
-  - 'db/schema.rb'
-  - 'vendor/**/*'
-  - 'test/**/*':
-    - Layout/AlignHash
-```
+We've added a number of editing guides for getting started:
 
-Note: If you're running Standard in a context where your `.standard.yml` file
-cannot be found by ascending the current working directory (i.e. against a
-temporary file buffer in your editor), you can specify the config location with
-`--config path/to/.standard.yml`.
+- [Atom](https://github.com/standardrb/standard/wiki/IDE:-Atom)
+- [emacs](https://www.flycheck.org/en/latest/languages.html#syntax-checker-ruby-standard)
+- [Helix](https://github.com/helix-editor/helix/wiki/Formatter-configurations#standardrb)
+- [neovim](https://github.com/standardrb/standard/wiki/IDE:-neovim)
+- [Nova](https://codeberg.org/edwardloveall/nova-standard)
+- [RubyMine](https://www.jetbrains.com/help/ruby/rubocop.html#disable_rubocop)
+- [vim](https://github.com/standardrb/standard/wiki/IDE:-vim)
+- [VS Code](https://github.com/standardrb/standard/wiki/IDE:-vscode)
+- [Zed](https://zed.dev/docs/languages/ruby#setting-up-ruby-lsp)
+- [Sublime Text](https://github.com/standardrb/standard/wiki/IDE:-Sublime-Text)
 
-## What you might do if you're REALLY clever
+If you'd like to help by creating a guide, please draft one [in an
+issue](https://github.com/standardrb/standard/issues/new) and we'll get it
+added!
 
-Because StandardRB is essentially a wrapper on top of
-[RuboCop](https://github.com/rubocop-hq/rubocop), it will actually forward the
-vast majority of CLI and ENV arguments forward to RuboCop.
+#### Language Server Protocol support
 
-You can see a list of
-[RuboCop](https://docs.rubocop.org/en/latest/basic_usage/#other-useful-command-line-flags)'s
-CLI flags here.
+If you don't see your preferred editor above, Standard Ruby also offers robust
+[language server](https://microsoft.github.io/language-server-protocol/) support,
+in two ways, both included with the `standard` gem:
 
-## Why should I use Ruby Standard Style?
+1. A [Ruby LSP](https://github.com/Shopify/ruby-lsp) add-on, which (if
+the `standard` gem is in your `Gemfile`) will be loaded automatically
+2. A language server executable, which can be run from the command line
+   with `standardrb --lsp`
 
-(This section will [look
-familiar](https://github.com/standard/standard#why-should-i-use-javascript-standard-style)
-if you've used StandardJS.)
+| Capability  | Ruby LSP Add-on | Internal Server |
+| ------------- | ------------- | ------------- |
+| Diagnostics (Linting) | ✅ ([Pull](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_pullDiagnostics)) | ✅ ([Push](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_publishDiagnostics)) |
+| [Formatting](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_formatting)  | ✅ | ✅ |
+| [Code Actions](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_codeAction) | ✅ | ❌ |
+| Everything else  | ❌  | ❌ |
 
-The beauty of Ruby Standard Style is that it's simple. No one wants to
-maintain multiple hundred-line style configuration files for every module/project
-they work on. Enough of this madness!
+Due to the advantages of Pull diagnostics and its inclusion of Code Actions
+("Quick Fixes" in VS Code parlance), we recommend using Standard's [Ruby LSP
+add-on](https://github.com/standardrb/standard/wiki/IDE:-vscode#using-ruby-lsp)
+where possible.
 
-This gem saves you (and others!) time in three ways:
+Regardless of which language server you use, many editors have added LSP
+support, with each bringing their own approach to configuration. Many LSP
+features should "just work", but when in doubt, please consult our [editor
+guides above](#editor-support) as well as your editor's own documentation on how
+to configure LSP formatters and linters.
 
-- **No configuration.** The easiest way to enforce consistent style in your
-  project. Just drop it in.
-- **Automatically format code.** Just run `standardrb --fix` and say goodbye to
-  messy or inconsistent code.
-- **Catch style issues & programmer errors early.** Save precious code review
-  time by eliminating back-and-forth between reviewer & contributor.
+### CI support
 
-Adopting Standard style means ranking the importance of code clarity and
-community conventions higher than personal style. This might not make sense for
-100% of projects and development cultures, however open source can be a hostile
-place for newbies. Setting up clear, automated contributor expectations makes a
-project healthier.
+Various continuous integration and quality-checking tools have been made to
+support Standard Ruby, as well.
 
-## Who uses Ruby Standard Style?
+* [GitHub Actions](https://github.com/standardrb/standard-ruby-action)
+* [Code Climate](https://github.com/standardrb/standard/wiki/CI:-Code-Climate)
+* [Pronto](https://github.com/julianrubisch/pronto-standardrb)
+* [Danger](https://github.com/ashfurrow/danger-rubocop/)
 
-(This section will not [look very
-familiar](https://github.com/standard/standard#who-uses-javascript-standard-style)
-if you've used StandardJS.)
+Of course, no special plugin is necessary to run Standard Ruby in a CI
+environment, as `standardrb` and `rake standard` work just fine on their own!
 
-* [Test Double](https://testdouble.com/agency)
-* [Collective Idea](https://collectiveidea.com/)
-* [Culture Foundry](https://www.culturefoundry.com/)
-* [Evil Martians](https://evilmartians.com)
-* [Rebase Interactive](https://www.rebaseinteractive.com/)
-* [Hashrocket](https://hashrocket.com)
-* And that's about it so far!
+### Other tools
 
-If your team starts using Standard, [send a pull
-request](https://github.com/testdouble/standard/edit/master/README.md) to let us
-know!
+These tool integrations are also available:
 
-## Is there a readme badge?
+* [Guard](https://github.com/JodyVanden/guard-standardrb)
+* [Spring](https://github.com/lakim/spring-commands-standard)
 
-Yes! If you use Standard in your project, you can include one of these
-badges in your readme to let people know that your code is using the StandardRB
-style.
+## Ignoring errors
 
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+While Standard is very strict in how each formatting and linting rule is configured,
+it's mercifully flexible when you need to ignore a violation to focus on a higher
+priority (like, say, keeping the build running). There are a number of ways to
+ignore any errors, with the right answer depending on the situation.
 
-```md
-[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
-```
+### Ignoring a line with a comment
 
-## I disagree with rule X, can you change it?
+Individual lines can be ignored with a comment directive at the end of the line.
+As an example, the line `text = 'hi'` violates two rules,
+[Lint/UselessAssignment](https://docs.rubocop.org/rubocop/cops_lint.html#lintuselessassignment)
+and
+[Style/StringLiterals](https://docs.rubocop.org/rubocop/cops_style.html#stylestringliterals).
 
-**[NOTE: until StandardRB hits 1.0.0, the answer is yes! It just requires
-[opening an issue](https://github.com/testdouble/standard/issues/new) and
-convincing [@searls](https://twitter.com/searls) (the BDFNow) to make the
-change.]**
+You could ignore one, both, or all errors with the following comments:
 
-No. The whole point of Standard is to save you time by avoiding
-[bikeshedding](https://www.freebsd.org/doc/en/books/faq/misc.html#bikeshed-painting)
-about code style. There are lots of debates online about tabs vs. spaces, etc.
-that will never be resolved. These debates just distract from getting stuff
-done. At the end of the day you have to 'just pick something', and that's the
-whole philosophy of Standard -- its a bunch of sensible 'just pick something'
-opinions. Hopefully, users see the value in that over defending their own
-opinions.
-
-Pro tip: Just use Standard and move on. There are actual real problems that
-you could spend your time solving! :P
+```ruby
+# Disable one error but keep Lint/UselessAssignment
+text = 'hi' # standard:disable Style/StringLiterals
 
-## Is there an automatic formatter?
+# Disable both errors explicitly
+text = 'hi' # standard:disable Style/StringLiterals, Lint/UselessAssignment
 
-Yes! You can use `standardrb --fix` to fix most issues automatically.
+# Disable all errors on the line with "all"
+text = "hi" # standard:disable all
+```
 
-`standardrb --fix` is built into `standardrb` for maximum convenience. Most
-problems are fixable, but some errors must be fixed manually.
+### Ignoring multiple lines with comments
 
-## Can I override the `fix: true` config setting?
+Similarly to individual lines, you can also disable multiple lines by wrapping
+them in comments that disable and re-enable them:
 
-Also yes! You can use `standardrb --no-fix`. Not `fix`ing is the default behavior, but this flag will override the `fix: true` setting in your [`.standard.yml` config](#what-you-might-do-if-youre-clever). This is especially useful for checking your projects compliance with `standardrb` in CI environments while keeping the `fix: true` option enabled locally.
+```ruby
+# standard:disable Style/StringLiterals, Lint/UselessAssignment
+text = "hi"
+puts 'bye'
+# standard:enable Style/StringLiterals, Lint/UselessAssignment
+```
 
-## How do I ignore files?
+### Ignoring entire files and globs
 
-Sometimes you need to ignore additional folders or specific minified files. To
-do that, add a `.standard.yml` file to the root of your project and specify a
-list of files and globs that should be excluded:
+You can ignore entire files and file patterns by adding them to `ignore:` in
+your project's `.standard.yml` file:
 
 ```yaml
 ignore:
@@ -248,135 +268,310 @@ ignore:
   - 'a/whole/directory/**/*'
 ```
 
-You can see the files Standard ignores by default
-[here](https://github.com/testdouble/standard/blob/master/lib/standard/creates_config_store/configures_ignored_paths.rb#L3-L13)
+### Ignoring specific rules in files and globs
+
+For a given file or glob, you can even ignore only specific rules by nesting an
+array of the rules you'd like to ignore:
+
+```yaml
+ignore:
+  - 'test/**/*':
+    - Layout/AlignHash
+```
+
+### Ignoring every violation and converting them into a todo list
 
-## How do I hide a certain warning?
+If you're adopting Standard in a large codebase and you don't want to convert
+everything all at once, you can work incrementally by generating a "todo" file
+which will cause Standard to ignore every violation present in each file of the
+codebase.
 
-In rare cases, you'll need to break a rule and hide the warning generated by
-Standard.
+This way, you can gradually work through the todo list, removing ignore
+directives and fixing any associated errors, while also being alerted to any
+regressions if they're introduced into the project.
 
-Ruby Standard Style uses [RuboCop](https://github.com/rubocop-hq/rubocop)
-under-the-hood and you can hide warnings as you normally would if you used
-RuboCop directly.
+Here are the commands you might run to get started:
 
-To ignore only certain rules from certain globs (not recommended, but maybe your
-test suite uses a non-standardable DSL, you can specify an array of RuboCop
-rules to ignore for a particular glob:
+```
+# Start by clearing any auto-fixable errors:
+$ standardrb --fix
+
+# Generate a `.standard_todo.yml' to work from
+$ standardrb --generate-todo
+```
+
+## Configuring Standard
+
+While the rules aren't configurable, Standard offers a number of options that
+can be configured as CLI flags and YAML properties.
+
+### CLI flags
+
+The easiest way to summarize the available CLI flags is to invoke `standardrb -h`:
+
+```
+Usage: standardrb [--fix] [--lsp] [-vh] [--format <name>] [--] [FILE]...
+
+Options:
+
+  --fix             Apply automatic fixes that we're confident won't break your code
+  --fix-unsafely    Apply even more fixes, including some that may change code behavior
+  --no-fix          Do not automatically fix failures
+  --format <name>   Format output with any RuboCop formatter (e.g. "json")
+  --generate-todo   Create a .standard_todo.yml that lists all the files that contain errors
+  --lsp             Start a LSP server listening on STDIN
+  -v, --version     Print the version of Standard
+  -V, --verbose-version   Print the version of Standard and its dependencies.
+  -h, --help        Print this message
+  FILE              Files to lint [default: ./]
+
+Standard also forwards most CLI arguments to RuboCop. To see them, run:
+
+  $ rubocop --help
+```
+
+If you run Standard via Rake, you can specify your CLI flags in an environment
+variable named `STANDARDOPTS` like so:
+
+```
+$ rake standard STANDARDOPTS="--format progress"
+```
+
+### YAML options
+
+In addition to CLI flags, Standard will search for a `.standard.yml` file
+(ascending to parent directories if the current working directory doesn't
+contain one). If you find yourself repeatedly running Standard with the same
+CLI options, it probably makes more sense to set it once in a YAML file:
 
 ```yaml
-ignore:
-  - 'test/**/*':
-    - Style/BlockDelimiters
+fix: true               # default: false
+parallel: true          # default: false
+format: progress        # default: Standard::Formatter
+ruby_version: 3.0       # default: RUBY_VERSION
+default_ignores: false  # default: true
+
+ignore:                 # default: []
+  - 'vendor/**/*'
+
+plugins:                # default: []
+  - standard-rails
+
+extend_config:                # default: []
+  - .standard_ext.yml
+```
+
+#### Configuring ruby_version
+
+One notable YAML setting is `ruby_version`, which allows you to set the **oldest
+version of Ruby the project needs to support** [RuboCop's `TargetRubyVersion`
+setting](https://docs.rubocop.org/rubocop/configuration.html#setting-the-target-ruby-version)
+explicitly. Because this value is inferred from any `.ruby-version`,
+`.tool-versions`, `Gemfile.lock`, and `*.gemspec` files that might be present,
+most applications won't need to set this.
+
+However, gems and libraries that support older versions of Ruby will want
+to lock the `ruby-version:` explicitly in their `.standard.yml` file to ensure
+new rules don't break old rubies:
+
+```yaml
+ruby_version: 2.7
 ```
 
-You can also use special comments to disable all or certain rules within your
-source code. See [RuboCop's
-docs](https://docs.rubocop.org/en/latest/configuration/#disabling-cops-within-source-code)
-for details.
+## Extending Standard
+
+Standard includes two extension mechanisms: plugins and configuration
+extensions. While neither can _change_ the rules configured out-of-the-box by
+Standard, they can define, require, and configure _additional_ RuboCop rules.
 
-## How do I specify a Ruby version? What is supported?
+Both are "first-in-wins", meaning once a rule is configured by a plugin or
+extension, it can't be changed or reconfigured by a later plugin or extension.
+This way, each Standard plugin you add becomes a de facto "standard" of its
+own. Plugins have precedence over extensions as they are loaded first.
 
-Because Standard wraps RuboCop, they share the same [runtime
-requirements](https://github.com/rubocop-hq/rubocop#compatibility)—currently,
-that's MRI 2.3 and newer. While Standard can't avoid this runtime requirement,
-it does allow you to lint codebases that target Ruby versions older than 2.3 by
-narrowing the ruleset somewhat.
+### Plugins
 
-Standard will default to telling RuboCop to target the currently running version
-of Ruby (by inspecting `RUBY_VERSION` at runtime. But if you want to lock it
-down, you can specify `ruby_version` in `.standard.yml`.
+Adding a plugin to your project is as easy as adding it to your Gemfile and
+specifying it in `.standard.yml` in the root of your project. For example, after
+installing [standard-rails](https://github.com/standardrb/standard-rails), you
+can configure it by adding it to `plugins`:
 
+```yaml
+plugins:
+  - standard-rails
 ```
-ruby_version: 1.8.7
+
+Each plugin can be passed configuration options by specifying them in a nested
+hash. For example, `standard-rails` allows you to configure its rules for
+a particular version of Rails (though this will usually be detected for you
+automatically):
+
+```yaml
+plugins:
+  - standard-rails:
+      target_rails_version: 7.0
 ```
 
-See
-[testdouble/suture](https://github.com/testdouble/suture/blob/master/.standard.yml)
-for an example.
+You can develop your own plugins, too! Check out the
+[lint_roller](https://github.com/standardrb/lint_roller) gem to learn how. For a
+simple example, you can look at
+[standard-custom](https://github.com/standardrb/standard-custom), which is one
+of the default plugins included by Standard.
 
-It's a little confusing to consider, but the targeted Ruby version for linting
-may or may not match the version of the runtime (suppose you're on Ruby 2.5.1,
-but your library supports Ruby 2.3.0). In this case, specify `ruby_version` and
-you should be okay. However, note that if you target a _newer_ Ruby version than
-the runtime, RuboCop may behave in surprising or inconsistent ways.
+### Extended config files
 
-If you are targeting a Ruby older than 2.3 and run into an issue, check out
-Standard's [version-specific RuboCop
-configurations](https://github.com/testdouble/standard/tree/master/config) and
-consider helping out by submitting a pull request if you find a rule that won't
-work for older Rubies.
+Of course, you may want to add more rules without going to the trouble
+of packaging them in a plugin gem. For cases like this, you can define one or
+more [RuboCop configuration
+files](https://docs.rubocop.org/rubocop/configuration.html) and then list them
+in your `.standard.yml` file under `extend_config`.
 
-## How do I change the output?
+For example, after installing the
+[betterlint](https://github.com/Betterment/betterlint) gem from our friends at
+[Betterment](https://www.betterment.com), we could create a RuboCop config
+file named `.betterlint.yml`:
 
-Standard's built-in formatter is intentionally minimal, printing only unfixed
-failures or (when successful) printing nothing at all. If you'd like to use a
-different formatter, you can specify any of RuboCop's built-in formatters or
-write your own.
+```yaml
+require:
+  - rubocop/cop/betterment.rb
 
-For example, if you'd like to see colorful progress dots, you can either run
-Standard with:
+Betterment/UnscopedFind:
+  Enabled: true
 
+  unauthenticated_models:
+    - SystemConfiguration
 ```
-$ bundle exec standardrb --format progress
-Inspecting 15 files
-...............
 
-15 files inspected, no offenses detected
+And then reference it in our `.standard.yml`:
+
+```yml
+extend_config:
+  - .betterlint.yml
 ```
 
-Or, in your project's `.standard.yml` file, specify:
+### Running Standard's rules via RuboCop
+
+**Please note that the following usage is not supported and may break at any
+time. Use at your own risk and please refrain from opening GitHub issues with
+respect to loading Standard or its plugins' YAML configurations for use by
+the `rubocop` CLI.**
+
+If you find that neither plugins or configuration extensions meet your needs or
+if you have some other reason to run Standard's rules with RuboCop's CLI (e.g.,
+to continue using your favorite IDE/tooling/workflow with RuboCop support) Evil
+Martians also maintains [a regularly updated
+guide](https://evilmartians.com/chronicles/rubocoping-with-legacy-bring-your-ruby-code-up-to-standard)
+on how to configure RuboCop to load and execute Standard's ruleset.
+
+In short, you can configure this in your `.rubocop.yml` to load Standard's three
+default rulesets, just as you would any other gem:
 
 ```yaml
-format: progress
+require:
+  - standard
+  - standard-custom
+  - standard-performance
+  - rubocop-performance
+
+inherit_gem:
+  standard: config/base.yml
+  standard-custom: config/base.yml
+  standard-performance: config/base.yml
 ```
 
-Refer to RuboCop's [documentation on
-formatters](https://rubocop.readthedocs.io/en/latest/formatters/) for more
-information.
+## Who uses Standard Ruby?
 
-## How do I run standard in my editor?
+Here are a few examples of Ruby Standard-compliant teams & projects:
 
-It can be very handy to know about failures while editing to shorten the
-feedback loop. Some editors support asynchronously running linters.
+* [Test Double](https://testdouble.com/agency)
+* [AdBarker](https://adbarker.com)
+* [AlchemyCMS](https://alchemy-cms.com)
+* [Amazon Web Services](https://aws.amazon.com/)
+* [Arrows](https://arrows.to/)
+* [Avo Admin](https://avohq.io/)
+* [Babylist](https://www.babylist.com/)
+* [BLISH](https://blish.cloud)
+* [Brand New Box](https://brandnewbox.com)
+* [Brave Software](https://github.com/brave-intl/publishers)
+* [Collective Idea](https://collectiveidea.com/)
+* [Culture Foundry](https://www.culturefoundry.com/)
+* [Datadog](https://www.datadoghq.com/)
+* [Donut](https://www.donut.com/)
+* [Elevate Labs](https://elevatelabs.com)
+* [Envoy](https://www.envoy.com)
+* [Evil Martians](https://evilmartians.com)
+* [Firstline](https://firstline.org/)
+* [Hashrocket](https://hashrocket.com)
+* [Honeybadger](https://www.honeybadger.io)
+* [JetThoughts](https://www.jetthoughts.com/)
+* [Level UP Solutions](https://levups.com)
+* [Lobsters](https://github.com/lobsters/lobsters)
+* [Monterail](https://www.monterail.com)
+* [myRent](https://www.myrent.co.nz)
+* [OBLSK](https://oblsk.com/)
+* [Oyster](https://www.oysterhr.com/)
+* [Planet Argon](https://www.planetargon.com/)
+* [PLT4M](https://plt4m.com/)
+* [Podia](https://www.podia.com/)
+* [Privy](https://www.privy.com/)
+* [Rebase Interactive](https://www.rebaseinteractive.com/)
+* [Renuo](https://www.renuo.ch/)
+* [RubyCI](https://ruby.ci)
+* [SearchApi](https://www.searchapi.io/)
+* [Spinal](https://spinalcms.com/)
+* [Teamtailor](https://www.teamtailor.com/)
+* [thoughtbot](https://thoughtbot.com/)
+* [Topkey](https://topkey.io)
+* [University of Wisconsin-Eau Claire](https://www.uwec.edu/)
+* [Cartwheel](https://www.cartwheel.org)
 
-### Atom
+Does your team use Standard? [Add your name to the list](https://github.com/standardrb/standard/edit/main/README.md)!
 
-1. Install [linter-rubocop](https://github.com/AtomLinter/linter-rubocop) package.
+If you really want to show off, you can also add a badge to your project's README, like this one:
 
-2. Configure `linter-rubocop` to use either `standardrb` [binstub](https://bundler.io/man/bundle-binstubs.1.html) (`./bin/standardrb`) or a globally installed `standardrb` (with absolute path).
+[![Ruby Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
 
-![alt "linter-rubocop configuration"](https://user-images.githubusercontent.com/631534/54869518-e5aa7780-4d99-11e9-81e7-777654a4f91b.png)
+```md
+[![Ruby Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
+```
 
-### Vim
+## Help, I'm seeing an install error!
 
-Install [ale](https://github.com/w0rp/ale). And add these lines to your `.vimrc`
-file.
+This section is really only here to feed Google, but if you see an error like
+any of the following:
 
-```vimscript
-let g:ale_linters = {'ruby': ['standardrb']}
-let g:ale_fixers = {'ruby': ['standardrb']}
+```
+ERROR:  Could not find a valid gem 'standard' (= 0.0.36) in any repository
 ```
 
-This sets Standard as your only linter and fixer for Ruby files and so
-prevents conflicts with RuboCop. For automatic fixing on save, add
-this to your `.vimrc`:
+```
+Could not find gem 'standard (= 0.0.36)' in rubygems repository https://rubygems.org/ or installed locally.
+```
 
 ```
-let g:ale_fix_on_save = 1
+Your bundle is locked to standard (0.0.36) from rubygems repository https://rubygems.org/ or installed locally, but that version can no longer be found in that source. That means the author of standard (0.0.36) has removed it. You'll need to update your bundle to a version other than standard (0.0.36) that hasn't been removed in order to install.
 ```
 
-## Contributing
+This is because on August 18th, 2023, we yanked versions 0.0.1~0.0.36.1 from
+[RubyGems.org](https://rubygems.org) for the reasons discussed in [this
+issue](https://github.com/standardrb/standard/issues/340). Because these
+versions are now over four years old and no longer track supported versions of
+Ruby or RuboCop, the correct fix for any of the above errors is probably to
+**upgrade to the latest version of Standard Ruby**.
 
-Follow the steps below to setup standard locally:
+If for whatever reason you need to install one of these versions, you can
+change your Gemfile to point to the corresponding git tag from the source
+repository:
 
-```bash
-$ git clone https://github.com/testdouble/standard
-$ cd standard
-$ gem install bundler # if working with ruby version below 2.6.0
-$ bundle install
-$ bundle exec rake # to run test suite
+```ruby
+gem "standard", git: "https://github.com/testdouble/standard.git", tag: "v0.0.36"
 ```
 
 ## Code of Conduct
-This project follows Test Double's [code of conduct](https://testdouble.com/code-of-conduct) for all community interactions, including (but not limited to) one-on-one communications, public posts/comments, code reviews, pull requests, and GitHub issues. If violations occur, Test Double will take any action they deem appropriate for the infraction, up to and including blocking a user from the organization's repositories.
+
+This project follows Test Double's [code of
+conduct](https://testdouble.com/code-of-conduct) for all community interactions,
+including (but not limited to) one-on-one communications, public posts/comments,
+code reviews, pull requests, and GitHub issues. If violations occur, Test Double
+will take any action they deem appropriate for the infraction, up to and
+including blocking a user from the organization's repositories.