1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
# RuboCop Usage Guide
## Overview
A tale of two RuboCop plugin gems.
### RuboCop Gradual
This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
### RuboCop LTS
This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
## Checking RuboCop Violations
To check for RuboCop violations in this project, always use:
```bash
bundle exec rake rubocop_gradual:check
```
**Do not use** the standard RuboCop commands like:
- `bundle exec rubocop`
- `rubocop`
## Understanding the Lock File
The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
1. Prevent new violations while gradually fixing existing ones
2. Track progress on code style improvements
3. Ensure CI builds don't fail due to pre-existing violations
## Common Commands
- **Check violations**
- `bundle exec rake rubocop_gradual`
- `bundle exec rake rubocop_gradual:check`
- **(Safe) Autocorrect violations, and update lockfile if no new violations**
- `bundle exec rake rubocop_gradual:autocorrect`
- **Force update the lock file (w/o autocorrect) to match violations present in code**
- `bundle exec rake rubocop_gradual:force_update`
## Workflow
1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
2. If there are new violations, either:
- Fix them in your code
- Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
3. Commit the updated `.rubocop_gradual.lock` file along with your changes
## Never add inline RuboCop disables
Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
- `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
- If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
## Benefits of rubocop_gradual
- Allows incremental adoption of code style rules
- Prevents CI failures due to pre-existing violations
- Provides a clear record of code style debt
- Enables focused efforts on improving code quality over time
|
