From 494ee04c669f69071d6143e1dde0337c8f0ff10a Mon Sep 17 00:00:00 2001
From: Phil Pirozhkov <pirjsuka@gmail.com>
Date: Sat, 22 Aug 2020 17:03:12 +0300
Subject: [PATCH] Add a guideline about nested departments

---
 .../ROOT/pages/upgrade_to_version_2.adoc      | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/modules/ROOT/pages/upgrade_to_version_2.adoc b/docs/modules/ROOT/pages/upgrade_to_version_2.adoc
index 1ccb98446..93a3a640a 100644
--- a/docs/modules/ROOT/pages/upgrade_to_version_2.adoc
+++ b/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.