Add v2 update docs

Author: pirj

docs/modules/ROOT/nav.adoc

@@ -2,6 +2,7 @@
 * xref:installation.adoc[Installation]
 * xref:usage.adoc[Usage]
 * xref:cops.adoc[Cops]
+* xref:upgrade_to_version_2.adoc[Upgrade to 2.x]
 * Cops Documentation
 ** xref:cops_capybara.adoc[Capybara]
 ** xref:cops_factorybot.adoc[FactoryBot]

docs/modules/ROOT/pages/upgrade_to_version_2.adoc

@@ -0,0 +1,129 @@
+= Upgrade to Version 2.x
+:doctype: book
+
+== Configuration File Update
+
+In version 2.x:
+
+ - `RSpec/InvalidPredicateMatcher` cop is removed
+ - `CustomIncludeMethods` configuration option for `RSpec/EmptyExampleGroup` is removed
+
+[discrete]
+=== Adjust the configuration of `RSpec/EmptyExampleGroup`
+
+[source,yaml]
+----
+# .rubocop.yml
+
+# Before
+RSpec/EmptyExampleGroup:
+  CustomIncludeMethods:
+  - include_tests
+
+# After
+AllCops:
+  RSpec:
+    Language:
+      Includes:
+        Example:
+        - include_tests
+----
+
+== Custom Cop Update Guide
+
+Due to significant API changes custom cops will break.
+Here is the summary of the changes:
+
+1) The base class for cops is now `RuboCop::Cop::RSpec::Base` instead of `RuboCop::Cop::RSpec::Cop`.
+
+2) `TopLevelDescribe` is replaced with a more generic `TopLevelGroup`.
+
+3) `RuboCop::RSpec::Language` has been completely rewritten to support dynamic RSpec DSL aliases and negated matchers to fully support third-party libraries e.g. RSpec Rails, Pundit, Action Policy and many others.
+
+4) RuboCop RSpec updated the dependency of RuboCop to 1.0+.
+
+Below are the necessary steps to update custom cops to work with `rubocop-rspec` version 2.x.
+
+
+=== Change the Parent Class
+
+Change the parent class of the custom cops from `RuboCop::Cop::RSpec::Cop` to `RuboCop::Cop::RSpec::Base`.
+
+[source,ruby]
+----
+# Before
+module RuboCop
+  module Cop
+    module RSpec
+      class FightPowerty < Cop
+
+# After
+module RuboCop
+  module Cop
+    module RSpec
+      class FightPowerty < Base
+----
+
+https://github.com/rubocop-hq/rubocop-rspec/pull/962[Example pull request].
+
+
+=== Replace `TopLevelDescribe`
+
+`TopLevelDescribe` was incomplete, had poor performance and did not distinguish between example groups and shared example groups.
+
+`TopLevelGroup` provides a similar interface, but instead of a single `on_top_level_describe` hook there are two, `on_top_level_example_group` and `on_top_level_group`.
+There's no need yet for `on_top_level_shared_group` for RuboCop core cops, but if your custom cop needs such a hook, please feel free to send a pull request.
+
+Additionally, `single_top_level_describe?` is removed with no direct replacement.
+You may use `top_level_groups` query method instead, e.g. `top_level_groups.one?`.
+
+Example pull requests to replace `TopLevelDescribe` with `TopLevelGroup` [https://github.com/rubocop-hq/rubocop-rspec/pull/978[1], https://github.com/rubocop-hq/rubocop-rspec/pull/932[2], https://github.com/rubocop-hq/rubocop-rspec/pull/977[3]].
+
+
+=== Change the `Language` Module Usages
+
+The `RuboCop::RSpec::Language` is completely different now.
+`Hooks::ALL` and alike, and their accompanying helpers work differently.
+To allow for lazy initialization, and for loading of the language configuration after the class are loaded, a https://docs.rubocop.org/rubocop-ast/node_pattern.html#to-call-functions[function call feature of RuboCop AST] is used.
+
+[source,ruby]
+----
+# Before
+def_node_matcher :shared_context,
+                 SharedGroups::CONTEXT.block_pattern
+
+# After
+def_node_matcher :shared_context,
+                 block_pattern('#rspec(:SharedGroups, :Context)')
+----
+
+[source,ruby]
+----
+# Before
+def_node_search :examples?,
+                (Includes::EXAMPLES + Examples::ALL).send_pattern
+
+# After
+def_node_search :examples?,
+                send_pattern(
+                  '{#rspec(:Includes, :Example) #rspec(:Examples)}')
+----
+
+[source,ruby]
+----
+# Before
+def_node_search :find_rspec_blocks,
+                ExampleGroups::ALL.block_pattern
+
+# After
+def_node_search :find_rspec_blocks,
+                block_pattern('#rspec(:ExampleGroups)')
+----
+
+https://github.com/rubocop-hq/rubocop-rspec/pull/956[Pull request with more examples].
+
+=== Conform with RuboCop API Changes
+
+The parent project, RuboCop, have API changes.
+They won't result in cop breakages, however, it's recommended to update cops to use new APIs.
+Follow the https://docs.rubocop.org/rubocop/v1_upgrade_notes[RuboCop's core v1 update guide] to adjust custom cops' RuboCop Autocorrect API usage.