RuboCop: tweak common config

document why each cop is disabled, disable a few more globally, and document
the intentions for each currently disabled cops in the optional config

Change-Id: I7abaabd76142a61e1922f55da0c8abb6a665ec05
Reviewed-on: https://gerrit.instructure.com/c/canvas-lms/+/274265
Tested-by: Service Cloud Jenkins <svc.cloudjenkins@instructure.com>
Reviewed-by: Simon Williams <simon@instructure.com>
QA-Review: Cody Cutrer <cody@instructure.com>
Product-Review: Cody Cutrer <cody@instructure.com>

.rubocop.common.yml

@@ -28,7 +28,7 @@ Layout/IndentationConsistency:
   Exclude:
     - "**/Gemfile.d/*" # we purposely indent dependent gems
 Layout/LineLength:
-  Enabled: false
+  Enabled: false # TODO. Maybe.
 
 Lint/Debugger:
   Severity: error
@@ -51,17 +51,23 @@ Naming/FileName:
 Rails:
   Exclude:
     - "**/Gemfile.d/*" # Rails isn't loaded yet, so can't use their helpers in the Gemfile
+Rails/ApplicationRecord:
+  Enabled: false # we never bothered creating an ApplicationRecord
+Rails/SkipsModelValidations:
+  Enabled: false # Canvas skips validations in many places for optimization reasons
 
 RSpec/EmptyExampleGroup:
   Severity: error
 RSpec/ExampleLength:
-  Enabled: false
+  Enabled: false # this is a Metrics-style cop
 RSpec/InstanceVariable:
-  Enabled: false
+  Enabled: false # legacy code
+RSpec/MessageSpies:
+  Enabled: false # we don't use spies
 RSpec/MultipleExpectations:
-  Enabled: false
+  Enabled: false # we don't write specs in this style
 RSpec/NestedGroups:
-  Enabled: false
+  Enabled: false # legacy code
 RSpec/RepeatedDescription:
   Severity: error
 
@@ -69,12 +75,16 @@ Specs/EnsureSpecExtension:
   Exclude:
     - spec/shared_examples/**/*
 Style/AsciiComments:
-  Enabled: false
+  Enabled: false # we have comments in other languages
 Style/Documentation:
-  Enabled: false
+  Enabled: false # most things don't need to be documented
 Style/FrozenStringLiteralComment:
   Severity: error
+Style/HashSyntax:
+  Enabled: false # TODO. Maybe.
+Style/PerlBackrefs:
+  Enabled: false # Regexp.last_match(1) is far worse than $1
 Style/SpecialGlobalVars:
-  Enabled: false
+  Enabled: false # $! and $? are fine
 Style/StringLiterals:
-  Enabled: false
+  Enabled: false # TODO. Maybe.

.rubocop.yml

@@ -1,117 +1,100 @@
 inherit_from: .rubocop.common.yml
 
 AllCops:
-  NewCops: enable
+  NewCops: enable # TODO
 
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Lint/AmbiguousBlockAssociation:
+Lint/AmbiguousBlockAssociation: # TODO
   Exclude:
     - spec/**/*
 
-Naming/VariableNumber:
+Naming/VariableNumber: # TODO
   Enabled: false
 
-Rails/ApplicationRecord:
-  Enabled: false # we never bothered creating an ApplicationRecord
-Rails/HasManyOrHasOneDependent:
-  # It whines about update_all too much, which we use a lot specifically to
-  # bypass validations and any other AR-ness
+Rails/HasManyOrHasOneDependent: # TODO
   Enabled: false
-Rails/ReadWriteAttribute:
+Rails/ReadWriteAttribute: # TODO: autocorrect (unsafe)
   Enabled: false # accessors are often defined in terms of read_attribute
-Rails/SkipsModelValidations:
-  Enabled: false
-Rails/TimeZone:
+Rails/TimeZone: # TODO: autocorrect (unsafe)
   Enabled: false
 
-RSpec/ContextWording:
+RSpec/ContextWording: # TODO
   Enabled: false
-RSpec/DescribeClass:
+RSpec/DescribeClass: # TODO
   Enabled: false
-RSpec/DescribedClass:
+RSpec/DescribedClass: # TODO: autocorrect (unsafe)
   Enabled: false
-RSpec/ExpectChange:
+RSpec/ExpectChange: # TODO: autocorrect (unsafe)
   Enabled: false
-RSpec/HookArgument:
+RSpec/HookArgument: # TODO: autocorrect
   Enabled: false
-RSpec/MessageSpies:
+RSpec/NamedSubject: # TODO
   Enabled: false
-RSpec/NamedSubject:
+RSpec/NotToNot: # TODO: autocorrect
   Enabled: false
-RSpec/NotToNot:
+RSpec/ScatteredSetup: # TODO: investigate if these are required
   Enabled: false
-RSpec/ScatteredSetup:
-  Enabled: false
-RSpec/VerifiedDoubles:
+RSpec/VerifiedDoubles: # TODO
   Enabled: false
 
-Style/BlockDelimiters:
+Style/BlockDelimiters: # TODO: autocorrect
   Enabled: true
   Exclude:
     - spec/**/*_spec.rb
     - spec/shared_examples/**/*.rb
-Style/ClassAndModuleChildren:
+Style/ClassAndModuleChildren: # TODO: autocorrect (unsafe)
   Enabled: false
-Style/DateTime:
+Style/DoubleNegation: # TODO: autocorrect (unsafe)
   Enabled: false
-Style/DoubleNegation:
+Style/Dir: # TODO: autocorrect
   Enabled: false
-Style/Dir:
+Style/FormatStringToken: # TODO: investigate if this complains about our i18n library
   Enabled: false
-Style/FormatStringToken:
+Style/GuardClause: # TODO
   Enabled: false
-Style/IfUnlessModifier:
+Style/IfUnlessModifier: # TODO: autocorrect
   Enabled: false
-Style/GuardClause:
+Style/Lambda: # TODO: autocorrect
   Enabled: false
-Style/HashSyntax:
+Style/MethodCallWithArgsParentheses: # TODO: autocorrect
   Enabled: false
-Style/Lambda:
+Style/MethodCallWithoutArgsParentheses: # TODO: autocorrect
   Enabled: false
-Style/MethodCallWithArgsParentheses:
+Style/NumericLiterals: # TODO: autocorrect
   Enabled: false
-Style/MethodCallWithoutArgsParentheses:
+Style/NumericPredicate: # TODO: autocorrect (unsafe)
   Enabled: false
-Style/NumericLiterals:
+Style/ParallelAssignment: # TODO: autocorrect (with probable exceptions)
   Enabled: false
-Style/NumericPredicate:
+Style/PercentLiteralDelimiters: # TODO: autocorrect
   Enabled: false
-Style/ParallelAssignment:
+Style/PercentQLiterals: # TODO: autocorrect
   Enabled: false
-Style/PercentLiteralDelimiters:
+Style/RedundantSelf: # TODO: autocorrect
   Enabled: false
-Style/PercentQLiterals:
+Style/RegexpLiteral: # TODO: autocorrect
   Enabled: false
-Style/RedundantSelf:
-  Enabled: false
-Style/RegexpLiteral:
-  Enabled: false
-Style/RescueModifier:
+Style/RescueModifier: # TODO
   Severity: warning
-Style/RescueStandardError:
+Style/RescueStandardError: # TODO: autocorrect
   EnforcedStyle: implicit
   Enabled: false
-Style/ReturnNil:
+Style/ReturnNil: # TODO: autocorrect (investigate violations)
   Enabled: false
-Style/SignalException:
+Style/SignalException: # TODO: autocorrect
   Enabled: false
-Style/StderrPuts:
+Style/StderrPuts: # TODO: autocorrect
   Enabled: false
-Style/StringLiterals:
+Style/SymbolArray: # TODO: autocorrect
   Enabled: false
-Style/SymbolArray:
+Style/TrailingCommaInArguments: # TODO: autocorrect
   Enabled: false
-Style/TrailingCommaInArguments:
+Style/TrailingCommaInArrayLiteral: # TODO: autocorrect
   Enabled: false
-Style/TrailingCommaInArrayLiteral:
+Style/TrailingCommaInHashLiteral: # TODO: autocorrect
   Enabled: false
-Style/TrailingCommaInHashLiteral:
+Style/WhileUntilModifier: # TODO: autocorrect
   Enabled: false
-Style/WhileUntilModifier:
+Style/WordArray: # TODO: autocorrect
   Enabled: false
-Style/WordArray:
-  Enabled: false
-Style/ZeroLengthPredicate:
+Style/ZeroLengthPredicate: # TODO: autocorrect (unsafe)
   Enabled: false