Add a guideline about nested departments

Author: pirj

docs/modules/ROOT/pages/upgrade_to_version_2.adoc

@@ -7,6 +7,7 @@ In version 2.x:
 
  - `RSpec/InvalidPredicateMatcher` cop is removed
  - `CustomIncludeMethods` configuration option for `RSpec/EmptyExampleGroup` is removed
+ - cop departments are nested for cops with a department that doesn't match the extension name (`Capybara`, `FactoryBot`, `Rails`)
 
 [discrete]
 === Adjust the configuration of `RSpec/EmptyExampleGroup`
@@ -29,6 +30,42 @@ AllCops:
         - include_tests
 ----
 
+=== Add a top-level `RSpec` department
+
+RuboCop extensions had cops with clashing names and departments, e.g. both `rspec-rails` and `rubocop-rspec` had `Rails::HttpStatus` cops.
+To avoid issues, e.g. inability to disable just one of the cops, each extension now has its own uber-department.
+Expectedly, RuboCop RSpec's uber-department name is `RSpec`.
+Changes are only applied to cops that don't already have the department set to `RSpec`, i.e. `Capybara`, `FactoryBot` and `Rails`.
+
+[source,yaml]
+----
+# .rubocop.yml
+
+# Before
+Capybara/CurrentPathExpectation:
+  Enabled: false
+
+FactoryBot/AttributeDefinedStatically:
+  Enabled: false
+
+# remains the same
+RSpec/EmptyExampleGroup:
+  Enabled: false
+
+# After
+RSpec/Capybara/CurrentPathExpectation:
+  Enabled: false
+
+RSpec/FactoryBot/AttributeDefinedStatically:
+  Enabled: false
+
+# remains the same
+RSpec/EmptyExampleGroup:
+  Enabled: false
+----
+
+https://github.com/rubocop-hq/rubocop/pull/8490[Learn more about this change].
+
 == Custom Cop Update Guide
 
 Due to significant API changes custom cops will break.