Merge branch 'doc-add-documentation-about-use-of-manual-rubocop-todo-file' into 'master'

Docs: Document use of manual rubocop todo file

See merge request gitlab-org/gitlab!49416

doc/development/contributing/index.md

@@ -147,7 +147,7 @@ Keep the following in mind when submitting merge requests:
 - If the code quality is found to not meet GitLab’s standards, the merge request reviewer will
   provide guidance and refer the author to our:
   - [Documentation](../documentation/styleguide/index.md) style guide.
-  - Code style guides.
+  - [Code style guides](style_guides.md).
 - Sometimes style guides will be followed but the code will lack structural integrity, or the
   reviewer will have reservations about the code’s overall quality. When there is a reservation,
   the reviewer will inform the author and provide some guidance.

doc/development/contributing/style_guides.md

@@ -97,6 +97,32 @@ To that end, we encourage creation of new RuboCop rules in the codebase.
 When creating a new cop that could be applied to multiple applications, we encourage you
 to add it to our [GitLab Styles](https://gitlab.com/gitlab-org/gitlab-styles) gem.
 
+### Resolving RuboCop exceptions
+
+When the number of RuboCop exceptions exceed the default [`exclude-limit` of 15](https://docs.rubocop.org/rubocop/1.2/usage/basic_usage.html#command-line-flags),
+we may want to resolve exceptions over multiple commits. To minimize confusion,
+we should track our progress through the exception list.
+
+When auto-generating the `.rubocop_todo.yml` exception list for a particular Cop,
+and more than 15 files are affected, we should add the exception list to
+a different file, `.rubocop_manual_todo.yml`.
+
+This ensures that our list isn't mistakenly removed by another auto generation of
+the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions
+which are currently being resolved.
+
+One way to generate the initial list is to run the todo auto generation,
+with `exclude limit` set to a high number. 
+
+```shell
+bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=10000
+```
+
+You can then move the list from the freshly generated `.rubocop_todo.yml` for the Cop being actively 
+resolved and place it in the `.rubocop_manual_todo.yml`. In this scenario, do not commit auto generated 
+changes to the `.rubocop_todo.yml` as an `exclude limit` that is higher than 15 will make the
+`.rubocop_todo.yml` hard to parse.
+
 ## Database migrations
 
 See the dedicated [Database Migrations Style Guide](../migration_style_guide.md).