mobility 0.8.11 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af3d3290a6ff7b079c7762980e5b26127c22e2a047e24d1d732daae129c51d3e
-  data.tar.gz: 4318510dcbc21495323317f02fed44b8d44218bd572a1ff9a32ee401ea97ad43
+  metadata.gz: 8658079d8c9fad02763385921421140d2410cde1d505c286627de5a8c1819612
+  data.tar.gz: 9bb012a9f564971e0c24fd3015e20e17384d7cbd77f2f0a5f1f1505e5262277a
 SHA512:
-  metadata.gz: ac1ac24bec3eb971644aa9cf63a5515c102649cc534f8cce7455bc90dd2dbfbe3002fab8e8dfd79adb0b7784bf87269b7e074723caec1598b163595defa79da9
-  data.tar.gz: fb6cdeb01e91a6373486a5156742ef068184742d53419ea6b1595a878ddd03fbc82345333519917a242bbc61798fc4e71e5f21494c0939272576f2af912e5b15
+  metadata.gz: 0a4a8a38a27d6f727091062010087466c85bfe48ce369395adb5501bd9875cfba21a56bce6a13b92b5cf83746883934f4161835f1336adedd9539bbf1138c51b
+  data.tar.gz: ca65fdaf7af558d235fdb5ba45347b9ca2319d9e6d69ddf7611afa2a50a477a30998316ce8661ca640ced1d09cd05f6ff282b1edfebd79abf4830c142bdf95df

data/CHANGELOG.md

@@ -1,9 +1,77 @@
 # Mobility Changelog
 
+## 1.0
+
+1.0 is a rewrite of many internals of the gem. Please see the [wiki page on v1.0](https://github.com/shioyama/mobility/wiki/Introduction-to-Mobility-v1.0) for more details on how to upgrade.
+
+## 1.0.0.rc1 (pre-release)
+
+- Remove `Mobility::ActiveRecord`, `Mobility::Sequel` and `Mobility::Arel`, and
+  general cleanup ([#464](https://github.com/shioyama/mobility/pull/464))
+
+## 1.0.0.beta2 (pre-release)
+
+- Refactor attributes & backend plugins and make `mobility_attributes` public
+  ([#462](https://github.com/shioyama/mobility/pull/462))
+- Make attribute_methods plugin depend on attributes
+  ([#461](https://github.com/shioyama/mobility/pull/461))
+
+## 1.0.0.beta1 (pre-release)
+
+- Remove `Mobility::Backend#apply_plugin`
+  ([#454](https://github.com/shioyama/mobility/pull/454))
+- Instance exec configure block if it takes no arguments
+  ([#456](https://github.com/shioyama/mobility/pull/456))
+- Raise an exception if invalid options are passed to Translations initializer
+  ([#457](https://github.com/shioyama/mobility/pull/457/files))
+- Fix Ruby 2.7 deprecation warnings
+  ([#460](https://github.com/shioyama/mobility/pull/460))
+
+## 1.0.0.alpha (pre-release)
+
+- Default fallbacks plugin to `true` when enabled
+  ([#447](https://github.com/shioyama/mobility/pull/447))
+- Remove `Mobility::Backend.method_name`
+  ([#400](https://github.com/shioyama/mobility/pull/400))
+- Remove `translated_attribute_names` as alias for `mobility_attributes`
+  ([#402](https://github.com/shioyama/mobility/pull/402))
+- Move `_backend` methods into `backend_reader` plugin
+  ([#403](https://github.com/shioyama/mobility/pull/403))
+- Replace `Configuration#query_method` configuration with Query plugin option
+  ([#414](https://github.com/shioyama/mobility/pull/414))
+- Remove `Mobility::Configuration#default_accessor_locales`. Use plugin option
+  to configure global default instead.
+  ([#424](https://github.com/shioyama/mobility/pull/424))
+- Pass `model_class` to `Mobility::Backend#configure` via class method rather
+  than on options hash ([#429](https://github.com/shioyama/mobility/pull/429))
+- Remove `Mobility.new_fallbacks` and `Configuration#fallbacks_generator`
+  ([#433](https://github.com/shioyama/mobility/pull/433))
+- Rename `backend_name` to `backend`
+  ([#443](https://github.com/shioyama/mobility/pull/443))
+- Remove `Configuration#accessor_method`
+  ([#450](https://github.com/shioyama/mobility/pull/450))
+- Rename `Mobility::Attributes` to `Mobility::Translations`
+- Remove `Mobility::Configuration` altogether
+  ([#452](https://github.com/shioyama/mobility/pull/452))
+
 ## 0.8
 
+### 0.8.13 (May 27, 2020)
+
+* Fix fallthrough accessor method_missing not passing all options to super
+  ([#364](https://github.com/shioyama/mobility/pull/364),
+  [#384](https://github.com/shioyama/mobility/pull/384),
+  [#377](https://github.com/shioyama/mobility/pull/377), thanks
+  [doits](https://github.com/doits)!)
+
+### 0.8.12 (May 15, 2020)
+
+(yanked)
+
 ### 0.8.11 (May 14, 2020)
-* Handle select with block ([#359](https://github.com/shioyama/mobility/pull/359))
+* Handle select with block
+  ([#359](https://github.com/shioyama/mobility/pull/359), thanks
+  [dlcmh](https://github.com/dlcmh)!)
 
 ### 0.8.10 (February 11, 2020)
 * Enforce case_sensitive comparison for Rails 6.1

data/Gemfile

@@ -3,41 +3,73 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mobility.gemspec
 gemspec
 
+orm, orm_version = ENV['ORM'], ENV['ORM_VERSION']
+
 group :development, :test do
-  if ENV['ORM'] == 'active_record'
-    if ENV['RAILS_VERSION'] == '5.0'
-      gem 'activerecord', '>= 5.0', '< 5.1'
-    elsif ENV['RAILS_VERSION'] == '4.2'
+  case orm
+  when 'active_record'
+    orm_version ||= '6.0'
+    case orm_version
+    when '4.2'
       gem 'activerecord', '>= 4.2.6', '< 5.0'
-    elsif ENV['RAILS_VERSION'] == '5.1'
+    when '5.0'
+      gem 'activerecord', '>= 5.0', '< 5.1'
+    when '5.1'
       gem 'activerecord', '>= 5.1', '< 5.2'
-    elsif ENV['RAILS_VERSION'] == '5.2'
+    when '5.2'
       gem 'activerecord', '>= 5.2.0', '< 5.3'
       gem 'railties', '>= 5.2.0.rc2', '< 5.3'
-    else # Default is Rails 6.0
+    when '6.0'
       gem 'activerecord', '>= 6.0.0', '< 6.1'
+    when '6.1'
+      git 'https://github.com/rails/rails.git' do
+        gem 'activerecord'
+        gem 'activesupport'
+      end
+    else
+      raise ArgumentError, 'Invalid ActiveRecord version'
     end
-    gem "generator_spec", '~> 0.9.4'
-  elsif ENV['ORM'] == 'sequel'
-    if ENV['SEQUEL_VERSION'] == '4'
+  when 'sequel'
+    orm_version ||= '5'
+    case orm_version
+    when '4'
       gem 'sequel', '>= 4.46.0', '< 5.0'
-    else
+    when '5'
       gem 'sequel', '>= 5.0.0', '< 6.0.0'
+    else
+      raise ArgumentError, 'Invalid Sequel version'
     end
+  when nil, ''
+  else
+    raise ArgumentError, "Invalid ORM: #{orm}"
   end
 
-  gem 'allocation_stats' if ENV['TEST_PERFORMANCE']
+  gem 'allocation_stats' if ENV['FEATURE'] == 'performance'
+
+  if ENV['FEATURE'] == 'rails'
+    gem 'rails'
+    gem 'generator_spec', '~> 0.9.4'
+  end
 
   platforms :ruby do
     gem 'guard-rspec'
     gem 'pry-byebug'
-    if ENV['ORM'] == 'active_record' && ENV['RAILS_VERSION'] < '5.2'
-      gem 'sqlite3', '~> 1.3.13'
-    else
-      gem 'sqlite3', '~> 1.4.1'
+    case ENV['DB']
+    when 'sqlite3'
+      if orm == 'active_record' && orm_version < '5.2'
+        gem 'sqlite3', '~> 1.3.13'
+      else
+        gem 'sqlite3', '~> 1.4.1'
+      end
+    when 'mysql'
+      gem 'mysql2'
+    when 'postgres'
+      if orm == 'active_record' && orm_version < '5.0'
+        gem 'pg', '< 1.0'
+      else
+        gem 'pg'
+      end
     end
-    gem 'mysql2', '~> 0.4.9'
-    gem 'pg', '< 1.0'
   end
 end
 

data/Gemfile.lock

@@ -1,51 +1,32 @@
 PATH
   remote: .
   specs:
-    mobility (0.8.10)
+    mobility (1.0.0.beta2)
       i18n (>= 0.6.10, < 2)
       request_store (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (6.0.3)
-      actionview (= 6.0.3)
-      activesupport (= 6.0.3)
-      rack (~> 2.0, >= 2.0.8)
-      rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actionview (6.0.3)
-      activesupport (= 6.0.3)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activemodel (6.0.3)
-      activesupport (= 6.0.3)
-    activerecord (6.0.3)
-      activemodel (= 6.0.3)
-      activesupport (= 6.0.3)
-    activesupport (6.0.3)
+    activemodel (6.0.3.4)
+      activesupport (= 6.0.3.4)
+    activerecord (6.0.3.4)
+      activemodel (= 6.0.3.4)
+      activesupport (= 6.0.3.4)
+    activesupport (6.0.3.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
       zeitwerk (~> 2.2, >= 2.2.2)
-    benchmark-ips (2.8.2)
-    builder (3.2.4)
+    benchmark-ips (2.8.3)
     byebug (11.1.3)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.6)
-    crass (1.0.6)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
     database_cleaner (1.8.5)
-    diff-lcs (1.3)
-    erubi (1.9.0)
-    ffi (1.12.2)
+    diff-lcs (1.4.4)
+    ffi (1.13.1)
     formatador (0.2.5)
-    generator_spec (0.9.4)
-      activesupport (>= 3.0.0)
-      railties (>= 3.0.0)
     guard (2.16.2)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
@@ -60,73 +41,52 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.8.2)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
     listen (3.2.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    loofah (2.5.0)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    lumberjack (1.2.4)
+    lumberjack (1.2.8)
     method_source (1.0.0)
-    mini_portile2 (2.4.0)
-    minitest (5.14.0)
-    mysql2 (0.4.10)
+    minitest (5.14.2)
     nenv (0.3.0)
-    nokogiri (1.10.9)
-      mini_portile2 (~> 2.4.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    pg (0.21.0)
+    pg (1.2.3)
     pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    rack (2.2.2)
-    rack-test (1.1.0)
-      rack (>= 1.0, < 3)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
-      loofah (~> 2.3)
-    railties (6.0.3)
-      actionpack (= 6.0.3)
-      activesupport (= 6.0.3)
-      method_source
-      rake (>= 0.8.7)
-      thor (>= 0.20.3, < 2.0)
+    rack (2.2.3)
     rake (12.3.3)
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     request_store (1.5.0)
       rack (>= 1.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
     shellany (0.0.1)
-    sqlite3 (1.4.2)
     thor (1.0.1)
     thread_safe (0.3.6)
-    tzinfo (1.2.7)
+    tzinfo (1.2.8)
       thread_safe (~> 0.1)
     yard (0.9.25)
-    zeitwerk (2.3.0)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby
@@ -135,16 +95,13 @@ DEPENDENCIES
   activerecord (>= 6.0.0, < 6.1)
   benchmark-ips
   database_cleaner (~> 1.5, >= 1.5.3)
-  generator_spec (~> 0.9.4)
   guard-rspec
   mobility!
-  mysql2 (~> 0.4.9)
-  pg (< 1.0)
+  pg
   pry-byebug
   rake (~> 12, >= 12.2.1)
   rspec (~> 3.0)
-  sqlite3 (~> 1.4.1)
   yard (~> 0.9.0)
 
 BUNDLED WITH
-   1.17.3
+   2.1.4

data/README.md

@@ -2,16 +2,22 @@ Mobility
 ========
 
 [![Gem Version](https://badge.fury.io/rb/mobility.svg)][gem]
-[![Build Status](https://travis-ci.org/shioyama/mobility.svg?branch=master)][travis]
+[![Build Status](https://github.com/shioyama/mobility/workflows/CI/badge.svg)][actions]
 [![Code Climate](https://api.codeclimate.com/v1/badges/72200f2b00c339ec4537/maintainability.svg)][codeclimate]
 [![Gitter Chat](https://badges.gitter.im/mobility-ruby/mobility.svg)](https://gitter.im/mobility-ruby/mobility)
 
 [gem]: https://rubygems.org/gems/mobility
-[travis]: https://travis-ci.org/shioyama/mobility
+[actions]: https://github.com/shioyama/mobility/actions
 [codeclimate]: https://codeclimate.com/github/shioyama/mobility
 [docs]: http://www.rubydoc.info/gems/mobility
 [wiki]: https://github.com/shioyama/mobility/wiki
 
+**This is the readme for the [`master`](https://github.com/shioyama/mobility)
+branch, which corresponds to v1.0.0.rc1, a pre-release version of Mobility.
+If you are using an earlier version (0.8.x or earlier), you probably want the
+readme on the [0-8-stable
+branch](https://github.com/shioyama/mobility/tree/0-8-stable).**
+
 Mobility is a gem for storing and retrieving translations as attributes on a
 class. These translations could be the content of blog posts, captions on
 images, tags on bookmarks, or anything else you might want to store in
@@ -36,10 +42,10 @@ and [Sequel](http://sequel.jeremyevans.net/) ORM, with support for other
 platforms planned.
 
 For a detailed introduction to Mobility, see [Translating with
-Mobility](http://dejimata.com/2017/3/3/translating-with-mobility). See also the
-[Roadmap](https://github.com/shioyama/mobility/wiki/Roadmap) for what's in the
-works for future releases, and other pages of the [wiki][wiki] for more detail
-on usage.
+Mobility](http://dejimata.com/2017/3/3/translating-with-mobility). See also my
+talk at RubyConf 2018, [Building Generic
+Software](https://www.youtube.com/watch?v=RZkemV_-__A), where I explain the
+thinking behind Mobility's design.
 
 If you're coming from Globalize, be sure to also read the [Migrating from
 Globalize](https://github.com/shioyama/mobility/wiki/Migrating-from-Globalize)
@@ -48,22 +54,15 @@ section of the wiki.
 Installation
 ------------
 
-Add this line to your application's Gemfile:
+To use the latest pre-version of Mobility 1.0, add this line to your
+application's Gemfile:
 
 ```ruby
-gem 'mobility', '~> 0.8.11'
-```
-
-Mobility is cryptographically signed. To be sure the gem you install hasn't
-been tampered with, add my public key as a trusted certificate and install:
-
-```
-gem cert --add <(curl -Ls https://raw.github.com/shioyama/mobility/master/certs/shioyama.pem)
-gem install mobility -P MediumSecurity
+gem 'mobility', '~> 1.0.0.rc1'
 ```
 
-The MediumSecurity trust profile will verify signed gems, but allow the
-installation of unsigned dependencies.
+For the latest stable version of Mobility, see the readme on the
+[0-8-stable](https://github.com/shioyama/mobility/tree/0-8-stable) branch.
 
 ### ActiveRecord (Rails)
 
@@ -72,7 +71,7 @@ Requirements:
 
 (Support for most backends and features is also supported with
 ActiveRecord/Rails 4.2, but there are some tests still failing. To see exactly
-what might not work, check pending specs in Rails 4.2 Travis builds.)
+what might not work, check pending specs in Rails 4.2 builds.)
 
 To translate attributes on a model, extend `Mobility`, then call `translates`
 passing in one or more attributes as well as a hash of options (see below).
@@ -89,36 +88,52 @@ rails generate mobility:install
 the `--without_tables` option here to skip the migration generation.)
 
 The generator will create an initializer file `config/initializers/mobility.rb`
-with the lines:
+which looks something like this:
 
 ```ruby
-Mobility.configure do |config|
-  config.default_backend = :key_value
-  config.accessor_method = :translates
-  config.query_method    = :i18n
+Mobility.configure do
+  # PLUGINS
+
+  plugins do
+    backend :key_value
+
+    active_record
+
+    reader
+    writer
+
+    # ...
+  end
 end
 ```
 
-To use a different default backend, set `default_backend` to another value (see
-possibilities [below](#backends)).
+Each method call inside the block passed to `config.plugins` declares a plugin,
+along with an optional default. To use a different default backend, you can
+change the default passed to the `backend` plugin, like this:
+
+```diff
+ Mobility.configure do |config|
+   # PLUGINS
+
+   config.plugins do
+-    backend :key_value
++    backend :table
+```
 
-You will likely also want to set default values for the various translation
-options described below. You can set these defaults by assigning values to keys
-on the `config.default_options` hash. Below, we turn on the Dirty plugin by
-default, so it will be enabled for all models.
+See other possible backends in the [backends section](#backends).
 
 You can also set defaults for backend-specific options. Below, we set the
-default `type` option for the KeyValue backend to `:string` (this is
-unnecessary and will be ignored if you are using a different backend).
+default `type` option for the KeyValue backend to `:string`.
 
 ```diff
  Mobility.configure do |config|
-   config.default_backend = :key_value
-   config.accessor_method = :translates
-   config.query_method    = :i18n
-+  config.default_options[:dirty] = true
-+  config.default_options[:type]  = :string
-end
+   # PLUGINS
+
+   config.plugins do
+-    backend :key_value
++    backend :key_value, type: :string
+   end
+ end
 ```
 
 We will assume the configuration above in the examples that follow. Other
@@ -132,6 +147,16 @@ See [Getting Started](#quickstart) to get started translating your models.
 Requirements:
 - Sequel >= 4.0
 
+When configuring Mobility, ensure that you include the `sequel` plugin:
+
+```diff
+ config.plugins do
+   backend :key_value
+
+-    active_record
++    sequel
+```
+
 You can extend `Mobility` just like in ActiveRecord, or you can use the
 `mobility` plugin, which does the same thing:
 
@@ -143,8 +168,8 @@ end
 ```
 
 Otherwise everything is (almost) identical to AR, with the exception that there
-is no equivalent to a Rails generator (so you will need to create the migration
-for any translation table(s) yourself, using Rails generators as a reference).
+is no equivalent to a Rails generator, so you will need to create the migration
+for any translation table(s) yourself, using Rails generators as a reference.
 
 The models in examples below all inherit from `ApplicationRecord`, but
 everything works exactly the same if the parent class is `Sequel::Model`.
@@ -259,15 +284,25 @@ changed and/or customized (see the [Backends](#backends) section below).
 ### <a name="getset"></a> Getting and Setting Translations
 
 The easiest way to get or set a translation is to use the getter and setter
-methods described above (`word.name` and `word.name=`), but you may want to
-access the value of an attribute in a specific locale, independent of the
-current value of `I18n.locale` (or `Mobility.locale`). There are a few ways to
-do this.
+methods described above (`word.name` and `word.name=`), enabled by including
+the `reader` and `writer` plugins.
+
+You may also want to access the value of an attribute in a specific locale,
+independent of the current value of `I18n.locale` (or `Mobility.locale`). There
+are a few ways to do this.
 
 The first way is to define locale-specific methods, one for each locale you
 want to access directly on a given attribute. These are called "locale
-accessors" in Mobility, and they can be defined by passing a `locale_accessors`
-option when defining translated attributes on the model class:
+accessors" in Mobility, and can be enabled by including the `locale_accessors`
+plugin, with a default set of accessors:
+
+```diff
+ config.plugins do
+   # ...
++  locale_accessors [:en, :ja]
+```
+
+You can also override this default from `translates` in any model:
 
 ```ruby
 class Word < ApplicationRecord
@@ -296,24 +331,23 @@ word.name_ru
 #=> NoMethodError: undefined method `name_ru' for #<Word id: ... >
 ```
 
-To generate methods for all locales in `I18n.available_locales` (at the time
-the model is first loaded), use `locale_accessors: true`.
+With no plugin option (or a default of `true`), Mobility generates methods for
+all locales in `I18n.available_locales` at the time the model is first loaded.
 
-An alternative to using the `locale_accessors` option is to use the
-`fallthrough_accessors` option, with `fallthrough_accessors: true`. This uses
-Ruby's [`method_missing`](http://apidock.com/ruby/BasicObject/method_missing)
-method to implicitly define the same methods as above, but supporting any
-locale without any method definitions. (Locale accessors and fallthrough
-locales can be used together without conflict, with locale accessors taking
-precedence if defined for a given locale.)
+An alternative to using the `locale_accessors` plugin is to use the
+`fallthrough_accessors` plugin. This uses Ruby's
+[`method_missing`](http://apidock.com/ruby/BasicObject/method_missing) method
+to implicitly define the same methods as above, but supporting any locale
+without any method definitions. (Locale accessors and fallthrough locales can
+be used together without conflict, with locale accessors taking precedence if
+defined for a given locale.)
 
-For example, if we define `Word` this way:
+Ensure the plugin is enabled:
 
-```ruby
-class Word < ApplicationRecord
-  extend Mobility
-  translates :name, fallthrough_accessors: true
-end
+```diff
+ config.plugins do
+   # ...
++  fallthrough_accessors
 ```
 
 ... then we can access any locale we want, without specifying them upfront:
@@ -374,11 +408,24 @@ word.name_backend.read(:en)
 ```
 
 Internally, all methods for accessing translated attributes ultimately end up
-reading and writing from the backend instance this way.
+reading and writing from the backend instance this way.  (The `write` methods
+do not call underlying backend's methods to persist the change. This is up to
+the user, so e.g. with ActiveRecord you should call `save` write the changes to
+the database).
 
-The `write` methods do not call underlying backend's methods to persist the change.
-This is up to the user (e.g. with ActiveRecord you should call `save` write
-the changes to the database).
+Note that accessor methods are defined in an included module, so you can wrap
+reads or writes in custom logic:
+
+```ruby
+class Post < ApplicationRecord
+  extend Mobility
+  translates :title
+
+  def title(*)
+    super.reverse
+  end
+end
+```
 
 ### Setting the Locale
 
@@ -419,15 +466,28 @@ details on how to configure it for your use case.
 
 ### <a name="fallbacks"></a>Fallbacks
 
-Mobility offers basic support for translation fallbacks. To enable fallbacks,
-pass a hash with fallbacks for each locale as an option when defining
+Mobility offers basic support for translation fallbacks. First, enable the
+`fallbacks` plugin:
+
+```diff
+ config.plugins do
+   # ...
++  fallbacks
++  locale_accessors
+```
+
+Fallbacks will require `fallthrough_accessors` to handle methods like
+`title_en`, which are used to track changes. For performance reasons it's
+generally best to also enable the `locale_accessors` plugin as shown above.
+
+Now pass a hash with fallbacks for each locale as an option when defining
 translated attributes on a class:
 
 ```ruby
 class Word < ApplicationRecord
   extend Mobility
-  translates :name,    fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
-  translates :meaning, fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
+  translates :name,    fallbacks: { de: :ja, fr: :ja }
+  translates :meaning, fallbacks: { de: :ja, fr: :ja }
 end
 ```
 
@@ -516,7 +576,16 @@ fallbacks](https://github.com/svenfuchs/i18n/wiki/Fallbacks).
 
 ### <a name="default"></a>Default values
 
-Another option is to assign a default value, which will be used if the result of a fetch would otherwise be `nil`:
+Another option is to assign a default value, using the `default` plugin:
+
+```diff
+ config.plugins do
+   # ...
++  default 'foo'
+```
+
+Here we've set a "default default" of `'foo'`, which will be returned if a fetch would
+otherwise return `nil`. This can be overridden from model classes:
 
 ```ruby
 class Word < ApplicationRecord
@@ -558,24 +627,29 @@ support it. Currently this is models which include
 [dirty](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/Dirty.html)
 plugin).
 
-Enabling dirty tracking is as simple as sending the `dirty: true` option when
-defining a translated attribute. The way dirty tracking works is somewhat
-dependent on the model class (ActiveModel or Sequel); we will describe the
-ActiveModel implementation here.
+First, ensure the `dirty` plugin is enabled in your configuration, and that you
+have enabled an ORM plugin (either `active_record` or `sequel`), since the
+dirty plugin will depend on one of these being enabled.
+
+```diff
+ config.plugins do
+   # ...
+   active_record
++  dirty
+```
+
+(Once enabled globally, the dirty plugin can be selectively disabled on classes
+by passing `dirty: false` to `translates`.)
 
-First, enable dirty tracking (note that this is a persisted AR model, although
-dirty tracking is not specific to AR and works for non-persisted models as well):
+Take this ActiveRecord class:
 
 ```ruby
 class Post < ApplicationRecord
   extend Mobility
-  translates :title, dirty: true
+  translates :title
 end
 ```
 
-(If you want to enable dirty tracking on all models, set the
-`config.default_options[:dirty]` option in your Mobility configuration.)
-
 Let's assume we start with a post with a title in English and Japanese:
 
 ```ruby
@@ -637,9 +711,6 @@ For performance reasons, it is highly recommended that when using the Dirty
 plugin, you also enable [locale accessors](#getset) for all locales which will
 be used, so that methods like `title_en` above are defined; otherwise they will
 be caught by `method_missing` (using fallthrough accessors), which is much slower.
-The easiest way to do this is to set `config.default_options[:locale_accessors]
-= true` in your Mobility config, and make sure that `I18n.available_locales`
-includes all locales you use in production.
 
 For more details on dirty tracking, see the [API
 documentation](http://www.rubydoc.info/gems/mobility/Mobility/Plugins/Dirty).
@@ -647,9 +718,17 @@ documentation](http://www.rubydoc.info/gems/mobility/Mobility/Plugins/Dirty).
 ### Cache
 
 The Mobility cache caches localized values that have been fetched once so they
-can be quickly retrieved again. The cache is enabled by default and should
-generally only be disabled when debugging; this can be done by passing `cache:
-false` when defining an attribute, like this:
+can be quickly retrieved again. The cache plugin is included in the default
+configuration created by the install generator:
+
+```diff
+ config.plugins do
+   # ...
++  cache
+```
+
+It can be disabled selectively per model by passing `cache: false` when
+defining an attribute, like this:
 
 ```ruby
 class Word < ApplicationRecord
@@ -659,7 +738,8 @@ end
 ```
 
 You can also turn off the cache for a single fetch by passing `cache: false` to
-the getter method, i.e. `post.title(cache: false)`.
+the getter method, i.e. `post.title(cache: false)`. To remove the cache plugin
+entirely, remove the `cache` line from the global plugins configuration.
 
 The cache is normally just a hash with locale keys and string (translation)
 values, but some backends (e.g. KeyValue and Table backends) have slightly more
@@ -667,11 +747,23 @@ complex implementations.
 
 ### <a name="querying"></a>Querying
 
-Mobility backends also support querying on translated attributes, in two
-different ways. The first is via query methods like `where` (and `not` and
-`find_by` in ActiveRecord, and `except` in Sequel). To query this way, use the
-`i18n` class method, which will return a model relation or dataset extended
-with Mobility-specific query method overrides.
+Mobility backends also support querying on translated attributes. To enable
+this feature, include the `query` plugin, and ensure you also have an ORM
+plugin enabled (`active_record` or `sequel`):
+
+```diff
+ config.plugins do
+   # ...
+   active_record
++  query
+```
+
+Querying defines a scope or dataset class method, whose default name is `i18n`.
+You can override this by passing a default in the configuration, like
+`query :t` to use a name `t`.
+
+Querying is supported in two different ways. The first is via query methods
+like `where` (and `not` and `find_by` in ActiveRecord, and `except` in Sequel).
 
 So for ActiveRecord, assuming a model using KeyValue as its default backend: