RSpec syntax extensions in third-party gems

Some gems, e.g. cancancan, action_policy and pundit provide their own extensions and aliases to RSpec syntax. Also, RSpec extensions like test-prof, rspec-its and saharspec do.

By default, RuboCop RSpec is not aware of those syntax extensions, and does not intend to gather all of them in the default configuration file. It is possible for the gems to provide configuration for RuboCop RSpec to allow proper detection of RSpec elements. RuboCop provides third-party gems with an ability to configure RuboCop.

Packaging configuration for RuboCop RSpec

Due to a [bug](https://github.com/rubocop/rubocop-rspec/issues/1126), this feature doesn’t work properly for rubocop-rspec 2.5.0 and earlier versions.

For a third-party gem, it’s sufficient to follow three steps:

  1. Provide a configuration file (e.g. .rubocop_rspec_alias_config.yml or config/rubocop-rspec.yml). Please check with the RSpec DSL configuration how different elements of RSpec syntax can be configured.

  2. Add a section to their documentation how users can benefit from using RuboCop RSpec with full detection of their syntax extensions. Example:

    ## Usage with RuboCop RSpec
Please add the following to your `.rubocop.yml` to make RuboCop RSpec aware of our cool syntax extensions:
  inherit_gem:
    third-party-gem: .rubocop_rspec_alias_config.yml

  3. Include the configuration file to their package by updating their gemspec’s spec.files to include the aforementioned configuration file.

See pull requests: test-prof, and action_policy for a less trivial example.