RuboCop rule development guidelines
Our codebase style is defined and enforced by RuboCop.
You can check for any offenses locally with bundle exec rubocop --parallel
.
On the CI, this is automatically checked by the static-analysis
jobs.
In addition, you can integrate RuboCop into supported IDEs using the Solargraph gem.
For RuboCop rules that we have not taken a decision on, follow the Ruby style guide to write idiomatic Ruby.
Reviewers/maintainers should be tolerant and not too pedantic about style.
Some RuboCop rules are disabled, and for those, reviewers/maintainers must not ask authors to use one style or the other, as both are accepted. This isn’t an ideal situation because this leaves space for bike-shedding. Ideally we should enable all RuboCop rules to avoid style-related discussions, nitpicking, or back-and-forth in reviews. The GitLab Ruby style guide includes a non-exhaustive list of styles that commonly come up in reviews and are not enforced.
Additionally, we have dedicated test-specific style guides and best practices.
Creating new RuboCop cops
Typically it is better for the linting rules to be enforced programmatically as it reduces the aforementioned bike-shedding.
To that end, we encourage creation of new RuboCop rules in the codebase.
Before adding a new cop to enforce a given style, make sure to discuss it with your team.
We maintain cops across several Ruby code bases, and not all of them are
specific to the GitLab application.
When creating a new cop that could be applied to multiple applications, we encourage you
to add it to our gitlab-styles
gem.
If the cop targets rules that only apply to the main GitLab application,
it should be added to GitLab instead.
Cop grace period
A cop is in a grace period if it is enabled and has Details: grace period
defined in its TODO YAML configuration.
On the default branch, offenses from cops in the grace period do not fail the RuboCop CI job. Instead, the job notifies the #f_rubocop
Slack channel. However, on other branches, the RuboCop job fails.
A grace period can safely be lifted as soon as there are no warnings for 2 weeks in the #f_rubocop
channel on Slack.
Enabling a new cop
- Enable the new cop in
.rubocop.yml
(if not already done viagitlab-styles
). - Generate TODOs for the new cop.
-
Set the new cop to
grace period
. - Create an issue to fix TODOs and encourage community contributions (via ~"quick win" and/or ~"Seeking community contributions"). See some examples.
- Create an issue to remove
grace period
after 2 weeks of silence in the#f_rubocop
Slack channel. See an example.
Silenced offenses
When offenses are silenced for cops in the grace period,
the #f_rubocop
Slack channel receives a notification message every 2 hours.
To fix this issue:
- Find cops with silenced offenses in the linked CI job.
- Generate TODOs for these cops.
RuboCop node pattern
When creating node patterns to match
Ruby’s AST, you can use scripts/rubocop-parse
.
This displays the AST of a Ruby expression to help you create the matcher.
See also !97024.
Resolving RuboCop exceptions
When the number of RuboCop exceptions exceeds the default exclude-limit
of 15,
we may want to resolve exceptions over multiple commits. To minimize confusion,
we should track our progress through the exception list.
The preferred way to generate the initial list or a list for specific RuboCop rules
is to run the Rake task rubocop:todo:generate
:
# Initial list
bundle exec rake rubocop:todo:generate
# List for specific RuboCop rules
bundle exec rake 'rubocop:todo:generate[Gitlab/NamespacedClass,Lint/Syntax]'
This Rake task creates or updates the exception list in .rubocop_todo/
. For
example, the configuration for the RuboCop rule Gitlab/NamespacedClass
is
located in .rubocop_todo/gitlab/namespaced_class.yml
.
Make sure to commit any changes in .rubocop_todo/
after running the Rake task.
Reveal existing RuboCop exceptions
To reveal existing RuboCop exceptions in the code that have been excluded via .rubocop_todo.yml
and
.rubocop_todo/**/*.yml
, set the environment variable REVEAL_RUBOCOP_TODO
to 1
.
This allows you to reveal existing RuboCop exceptions during your daily work cycle and fix them along the way.
Exclude
s in .rubocop.yml
instead of .rubocop_todo/**/*.yml
.