simplycop 2.20.0 → 2.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb3cb0dcc9beaf4e82889d902ed721ad050981e5d8b8cdc7a86787cf4783003f
-  data.tar.gz: a4ba938727a4e34a991d8a1c3a5bb28339f3397e7b8be666e373fed6665a6716
+  metadata.gz: 6157c3eef86dfe12f513756c99d70f0dfa29771d33ab4e8cb3e2750df0743180
+  data.tar.gz: bae1f7c522cde06878c7766b47fd43806018d9a9fcc4680f819776c62bcaa010
 SHA512:
-  metadata.gz: 47cbdbf53db81556df7a17b3d3b7bdb481a7f0b37cf6f5643c3e57acf06a0d5f1cd2806ce3f26b2b072444ab537104bb1a6265d84e0935b336e9fa7b0bb502e6
-  data.tar.gz: 9fd2e6e084150671cf3cc25208304b4936bdcbacefddfd7ea5f0a2d86b6a44cdc95dd54de6b44ddec4ab48ece11c470b6458cd128fa090a7b310df356e18732a
+  metadata.gz: 6d44d159da2e4fd39e405cd29df55071e051f13e86a7ac38bf643206f9257ef533616ce58bdd47f18daf849ddabd27e77284e0f61f240b0dfe4910a1ec6a5699
+  data.tar.gz: 5360a0a6bcd97ef3a524392472ed5048eb9d22fea7938fe5e8a49eae7dccbc96f0312615d2867cd8e0d4c85f5977bbf7f4bcf8a089ca6fe6834bab3c65f9ca79

data/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby-version: ['3.1', '3.2', '3.3', '3.4', jruby]
+        ruby-version: ['3.2', '3.3', '3.4', jruby]
 
     steps:
     - uses: actions/checkout@v4

data/catalog-info.yaml

@@ -10,7 +10,7 @@ metadata:
     simplybusiness.com/bnw-app-name: simplycop
     simplybusiness.com/sast-scanning: enabled
     rubygems.org/name: simplycop
-    rubygems.org/current-version: 2.18.1
+    rubygems.org/current-version: 2.20.1
 spec:
   type: library
   lifecycle: production

data/docs/index.md

@@ -2,20 +2,47 @@
 
 Provides standard shared rubocop configuration for Simply Business applications. No more copying `.rubocop.yml`, no more out-of-sync configuration files. Yay!
 
+## Table of Contents
+
+- [Installation](#installation)
+  - [Prerequisites](#prerequisites)
+  - [Basic Setup](#basic-setup)
+  - [Configuration Examples](#configuration-examples)
+- [Usage](#usage)
+  - [Running RuboCop](#running-rubocop)
+  - [CI/CD Integration](#cicd-integration)
+- [Configuration Guidelines](#configuration-guidelines)
+  - [Non-Rails Projects](#non-rails-projects)
+  - [Legacy Projects](#legacy-projects)
+- [Security Cops](#security-cops)
+- [Development](#development)
+  - [Contributing Guidelines](#contributing-guidelines)
+  - [Testing Configuration Changes](#testing-configuration-changes)
+- [Versioning](#versioning)
+- [FAQ](#faq)
+- [Migration Guide](#migration-guide)
+
 ## Installation
 
-Add this line to your application's Gemfile:
+### Prerequisites
+
+- Ruby 3.2 or higher
+- Bundler
+- RuboCop gem (automatically installed as a dependency)
+
+### Basic Setup
 
-```ruby
-gem 'simplycop'
+Add this line to your application's Gemfile via bundle add:
 
+```
+bundle add 'simplycop'
 ```
 
 Then install gems by executing:
 
     $ bundle install
 
-Put following lines at the beginning of your `.rubocop.yml` file:
+Create or update your `.rubocop.yml` file with the following basic configuration:
 
 ```yaml
 inherit_gem:
@@ -24,9 +51,87 @@ inherit_gem:
 AllCops:
   Exclude:
     - 'vendor/**/*'
+    - 'db/schema.rb'
+    - 'node_modules/**/*'
+```
+
+### Configuration Examples
+
+#### Basic Rails Application with RSpec
+
+```yaml
+inherit_gem:
+  simplycop:
+    - .simplycop.yml
+    - .simplycop_performance.yml
+    - .simplycop_rails.yml
+    - .simplycop_rspec.yml
+
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+    - 'db/schema.rb'
+    - 'bin/**/*'
 ```
 
-The base `.simplycop.yml` contains cops for all the standard rubocop departments, i.e.
+#### Rails Application with Full Test Suite
+
+```yaml
+inherit_gem:
+  simplycop:
+    - .simplycop.yml
+    - .simplycop_performance.yml
+    - .simplycop_rails.yml
+    - .simplycop_rspec.yml
+    - .simplycop_capybara.yml
+    - .simplycop_factory_bot.yml
+    - .simplycop_rspec_rails.yml
+
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+    - 'db/schema.rb'
+    - 'bin/**/*'
+```
+
+#### Non-Rails Ruby Gem
+
+```yaml
+inherit_gem:
+  simplycop: .simplycop.yml
+
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+
+Rails:
+  Enabled: false
+```
+
+#### Legacy Project (Gradual Migration)
+
+```yaml
+inherit_gem:
+  simplycop: .simplycop.yml
+
+AllCops:
+  Exclude:
+    - 'vendor/**/*'
+    - 'legacy/**/*'  # Exclude legacy code initially
+  NewCops: disable   # Don't enable new cops automatically
+
+# Start with just a few departments
+Style:
+  Enabled: true
+Layout:
+  Enabled: true
+Lint:
+  Enabled: true
+```
+
+### Available Configurations
+
+The base `.simplycop.yml` contains cops for all the standard rubocop departments:
 
 * Bundler
 * Gemspec
@@ -39,101 +144,279 @@ The base `.simplycop.yml` contains cops for all the standard rubocop departments
 * Style
 
 These can also be enabled individually as follows:
+
 ```yaml
 inherit_gem:
   simplycop:
     - .simplycop_<DEPARTMENT_NAME>.yml
 ```
 
-If you are implementing this in a rails project and have rspec, you probably want the standard rails, rspec, and performance cops. you can include this by adding:
+**Note:** Replace `<DEPARTMENT_NAME>` with the lowercase department name (e.g., `style`, `layout`, `lint`).
 
-```yaml
-inherit_gem:
-  simplycop:
-    - .simplycop.yml
-    - .simplycop_performance.yml
-    - .simplycop_rails.yml
-    - .simplycop_rspec.yml
-```
+### Additional Packages
 
-You may also want the following packages:
+For Rails projects with testing frameworks, you may want to include:
 ```yaml
-
-    - .simplycop_capybara.yml
-    - .simplycop_factory_bot.yml
-    - .simplycop_rspec_rails.yml
+- .simplycop_capybara.yml      # For Capybara feature tests
+- .simplycop_factory_bot.yml   # For FactoryBot test factories
+- .simplycop_rspec_rails.yml   # For RSpec Rails-specific cops
 ```
 
-NB: Capybara, FactoryBot and RSpecRails cops were previously available either via departments within `rubocop_rspec` or as packages in their own right. As of `rubocop_rspec` v3, they no longer exist as departments within `rubocop_rspec` and the packages need installing independently. If you use simplycop v1, you will still have access to some of these cops by inheriting `.simplycop_rspec`. As of simplycop v2 (which uses `rubocop_rspec` v3) you would need to inherit the packages individually.
+> **Important:** Capybara, FactoryBot and RSpecRails cops were previously available either via departments within `rubocop_rspec` or as packages in their own right. As of `rubocop_rspec` v3, they no longer exist as departments within `rubocop_rspec` and the packages need installing independently. If you use simplycop v1, you will still have access to some of these cops by inheriting `.simplycop_rspec`. As of simplycop v2 (which uses `rubocop_rspec` v3) you would need to inherit the packages individually.
 
 ## Usage
 
-Run Rubocop as you would usually do, i.e.
+### Running RuboCop
+
+Run RuboCop as you would usually do:
 
-    $ bundle exec rubocop
+```bash
+# Run on entire codebase
+$ bundle exec rubocop
 
-or from your continuous integration tool.
+# Run with auto-correction
+$ bundle exec rubocop --auto-correct
 
-## Guidances
+# Run only safe auto-corrections
+$ bundle exec rubocop --safe-auto-correct
+
+# Run on specific files or directories
+$ bundle exec rubocop app/ spec/
+
+# Generate TODO configuration for existing violations
+$ bundle exec rubocop --auto-gen-config
+```
+
+### CI/CD Integration
+
+#### GitHub Actions
 
-* If you are implementing this in a non-rails project, you probably don't want or need the rails cops. In case they cause problems, you can exclude them using:
 ```yaml
-Rails:
-  Enabled: false
+name: RuboCop
+on: [push, pull_request]
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: bundle exec rubocop
+```
+
+#### Semaphore CI
+
+```yaml
+version: v1.0
+name: RuboCop
+agent:
+  machine:
+    type: f1-standard-2
+    os_image: ubuntu2204
+
+blocks:
+  - name: "RuboCop"
+    task:
+      jobs:
+        - name: Run RuboCop
+          commands:
+            - checkout
+            - cache restore
+            - bundle install --deployment --path vendor/bundle
+            - cache store
+            - bundle exec rubocop
+      prologue:
+        commands:
+          - sem-version ruby 3.2
 ```
-* When adding rubocop and simplycop to a legacy project, you might want to initially disable some of the rules.
 
-## Security Cops
-- CheckForVulnerableCode
+## Configuration Guidelines
+
+### Legacy Projects
 
-This cop was built to identify possible Rails vulnerable code.
-Its purpose is to raise an awareness of the finding.
-When an offence was raised, please seek for help and guidance from application security team.
+When adding RuboCop and simplycop to a legacy project, you might want to initially disable some of the rules. Consider this approach:
 
-IMPORTANT:
-This cop must be enabled at all times, if you need to disable it please check with AppSec team first.
+1. **Start with basic cops**: Enable only `Style`, `Layout`, and `Lint` departments initially
+2. **Generate TODO configuration**: Use `--auto-gen-config` to create a `.rubocop_todo.yml` for existing violations
+3. **Gradual migration**: Enable more departments over time as you clean up the codebase
+4. **Team agreement**: Ensure the team agrees on the migration timeline
 
-Example of vulnerable code:
+Example for legacy projects:
 
-```ruby
-class BooksController < ApplicationController
-  caches_page :show
-end
+```yaml
+inherit_gem:
+  simplycop: .simplycop.yml
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  NewCops: disable  # Don't enable new cops automatically
+  Exclude:
+    - 'vendor/**/*'
+    - 'legacy_code/**/*'  # Exclude problematic areas initially
 ```
-Vulnerability Details: https://nvd.nist.gov/vuln/detail/CVE-2020-8159
 
 ## Development
 
-To change a setting for simplycop, simply edit the relevant .yml file with the configuration changes you wish to make. The aim is to choose a sensible configuration for all new cops as they are added in package updates. 
+### Contributing Guidelines
 
-Rubocop is well established enough that most new cops are for niche cases. The default assumption is therefore that they will provide a small code quality benefit without major disruption to the codebase and can safely be enabled.
+To change a setting for simplycop, simply edit the relevant `.yml` file with the configuration changes you wish to make. The aim is to choose a sensible configuration for all new cops as they are added in package updates.
+
+RuboCop is well established enough that most new cops are for niche cases. The default assumption is therefore that they will provide a small code quality benefit without major disruption to the codebase and can safely be enabled.
 
 However, this is not always the case. Always check the notes on the cop to understand the reasoning behind it, paying particular attention to any warnings and exceptions listed.
 
-- [Base Rubocop](https://docs.rubocop.org/rubocop/cops.html)
-- [Rubocop Capybara](https://docs.rubocop.org/rubocop-capybara/cops.html)
-- [Rubocop Factory Bot](https://docs.rubocop.org/rubocop-factory_bot/cops.html)
-- [Rubocop Performance](https://docs.rubocop.org/rubocop-performance/cops.html)
-- [Rubocop Rails](https://docs.rubocop.org/rubocop-rails/cops.html)
-- [Rubocop Rspec](https://docs.rubocop.org/rubocop-rspec/cops.html)
-- [Rubocop RSpec Rails](https://docs.rubocop.org/rubocop-rspec_rails/cops.html)
+#### Useful References
+
+- [Base RuboCop](https://docs.rubocop.org/rubocop/cops.html)
+- [RuboCop Capybara](https://docs.rubocop.org/rubocop-capybara/cops.html)
+- [RuboCop Factory Bot](https://docs.rubocop.org/rubocop-factory_bot/cops.html)
+- [RuboCop Performance](https://docs.rubocop.org/rubocop-performance/cops.html)
+- [RuboCop Rails](https://docs.rubocop.org/rubocop-rails/cops.html)
+- [RuboCop RSpec](https://docs.rubocop.org/rubocop-rspec/cops.html)
+- [RuboCop RSpec Rails](https://docs.rubocop.org/rubocop-rspec_rails/cops.html)
+
+#### When to Keep a Cop Disabled
 
 Consider keeping the cop disabled (or selecting a sensible config option) if any of the following apply:
-- The cop is disabled by default in rubocop (NB: All new cops are set to pending until the next major rubocop version)
-- The cop is listed as not safe in rubocop. Read the notes to find out why.
-- It is known that a large part of the SB codebase will systematically break a rule. Use smaller, newer repos as your benchmark for this. Chopin and Rater will have violations for most new rules, so do not disable a rule on that basis alone if it will bring benefit across the wider codebase.
 
-Other things to bear in mind:
-- Lean towards enabling rules if there are clear performance and/or clarity benefits.
-- Avoid setting config or enablement based on personal stylistic preference. If a team has a particularly strong stylistic preference on, say [explicit return of nil](https://docs.rubocop.org/rubocop/cops_style.html#stylereturnnil) this can be overridden at a repo level.
-- Default maximums for metrics cops are hard to meet and regularly violated. For that reason, they are mostly overridden or set as 'to-dos' within individual repos. There will be value in reducing violation of these over time, but centralised maximums have not yet been discussed or set.
+- The cop is disabled by default in RuboCop (Note: All new cops are set to pending until the next major RuboCop version)
+- The cop is listed as not safe in RuboCop. Read the notes to find out why
+- It is known that a large part of the SB codebase will systematically break a rule. Use smaller, newer repos as your benchmark for this. Chopin and Rater will have violations for most new rules, so do not disable a rule on that basis alone if it will bring benefit across the wider codebase
+
+#### Decision-Making Guidelines
+
+- Lean towards enabling rules if there are clear performance and/or clarity benefits
+- Avoid setting config or enablement based on personal stylistic preference. If a team has a particularly strong stylistic preference on, say [explicit return of nil](https://docs.rubocop.org/rubocop/cops_style.html#stylereturnnil), this can be overridden at a repo level
+- Default maximums for metrics cops are hard to meet and regularly violated. For that reason, they are mostly overridden or set as 'to-dos' within individual repos. There will be value in reducing violation of these over time, but centralized maximums have not yet been discussed or set
+
+If in doubt, discuss in `#technical-excellence-community` or `#tech` for guidance and a wider range of opinion.
+
+### Testing Configuration Changes
+
+Before submitting changes to simplycop configurations:
 
-If in doubt, discuss in #technical-excellence-community or #tech for guidance and a wider range of opinion.
+1. **Test locally**: Apply your changes to a sample project and run RuboCop
+2. **Check multiple projects**: Test on both new and legacy codebases if possible
+3. **Review impact**: Consider how many violations the change might introduce
+4. **Document rationale**: Include reasoning for the change in your PR description
+
+Example testing workflow:
+
+```bash
+# In a test project
+echo "inherit_gem:\n  simplycop: .simplycop.yml" > .rubocop.yml
+bundle add simplycop --path="/path/to/your/local/simplycop"
+bundle exec rubocop --dry-run
+```
 
 ### Versioning
 
-When updating simplycop, you can use [dobby](https://github.com/simplybusiness/dobby) in your PR comments to increment the version number. Try to stick to the following versioning principles
+#### Automatic Versioning
+
+When updating simplycop, you can use [Dobby](https://github.com/simplybusiness/dobby) in your PR comments to increment the version number. Try to stick to the following versioning principles
 
 - MAJOR: For breaking changes (e.g in [v2.0](https://github.com/simplybusiness/simplycop/releases/tag/2.0.0) several rubocop departments were split out into separate packages)
 - MINOR: For rule enablements, disablements and config changes (i.e. changes that may cause previously passing rubocop runs to fail)
 - PATCH: For updates that do not touch config (e.g. individual rubocop package bumps which typically fix false positives/negatives or other bugs, doc changes)
+
+#### Manual Versioning
+
+If you prefer to manually version, you can do so by editing the `lib/simplycop/version.rb` file and updating the `VERSION` line and updating the `catalog-info.yaml` file with the new version number for the annotation `rubygems.org/current-version`.
+
+## FAQ
+
+### Common Questions
+
+**Q: Can I override specific cops in my project?**
+A: Yes, you can override any cop configuration in your local `.rubocop.yml` file. Your local configuration takes precedence over inherited configurations.
+
+**Q: How do I handle RuboCop violations in legacy code?**
+A: Use `bundle exec rubocop --auto-gen-config` to generate a `.rubocop_todo.yml` file that disables existing violations. Then gradually address violations over time.
+
+**Q: What's the difference between simplycop v1 and v2?**
+A: v2 uses RuboCop RSpec v3, which splits Capybara, FactoryBot, and RSpecRails cops into separate packages. You'll need to explicitly include these configurations if you use them.
+
+**Q: Can I use simplycop with other RuboCop configurations?**
+A: Yes, you can inherit from multiple sources. List simplycop first to establish the base, then add other configurations.
+
+**Q: How often is simplycop updated?**
+A: Simplycop is updated regularly to include new RuboCop cops and configuration improvements. Check the [releases page](https://github.com/simplybusiness/simplycop/releases) for updates.
+
+**Q: What if a new cop causes too many violations?**
+A: New cops are carefully evaluated before being enabled. If you encounter issues, discuss with the team in `#technical-excellence-community` or create an issue on the simplycop repository.
+
+### Troubleshooting
+
+**RuboCop exits with "undefined method" errors:**
+- Ensure you're using compatible versions of RuboCop and simplycop
+- Try running `bundle update` to update dependencies
+
+**Unexpected violations after updating simplycop:**
+- Check the changelog for new enabled cops
+- Use `--auto-gen-config` to temporarily disable new violations while you address them
+
+**Performance issues with large codebases:**
+- Use `.rubocop.yml` exclude patterns to skip large generated files
+- Consider running RuboCop on specific directories during development
+
+## Migration Guide
+
+### From Standard RuboCop Configuration
+
+If you're currently using a custom `.rubocop.yml` file:
+
+1. **Back up your current configuration**:
+   ```bash
+   cp .rubocop.yml .rubocop.yml.backup
+   ```
+
+2. **Create a new minimal configuration**:
+   ```yaml
+   inherit_gem:
+     simplycop: .simplycop.yml
+
+   AllCops:
+     Exclude:
+       - 'vendor/**/*'
+   ```
+
+3. **Add your project-specific overrides**:
+   - Review your backup configuration
+   - Add any project-specific cop configurations to your new `.rubocop.yml`
+   - Test thoroughly before committing
+
+### From Other Shared Configurations
+
+If you're migrating from another shared RuboCop configuration:
+
+1. **Identify differences**: Compare your current configuration with simplycop's defaults
+2. **Plan the migration**: Decide whether to adopt simplycop's settings or override them
+3. **Test incrementally**: Apply changes in small batches to understand the impact
+4. **Update CI/CD**: Ensure your continuous integration tools use the new configuration
+
+### From Simplycop v1 to v2
+
+Key changes in v2:
+- Uses RuboCop RSpec v3
+- Capybara, FactoryBot, and RSpecRails cops are now separate packages
+- Some cop names and configurations may have changed
+
+Migration steps:
+1. **Update your Gemfile**: Ensure you're using simplycop v2
+2. **Update your configuration**: If you use RSpec testing cops, explicitly include the new packages:
+   ```yaml
+   inherit_gem:
+     simplycop:
+       - .simplycop.yml
+       - .simplycop_rspec.yml
+       - .simplycop_capybara.yml      # Add if you use Capybara
+       - .simplycop_factory_bot.yml   # Add if you use FactoryBot
+       - .simplycop_rspec_rails.yml   # Add if you use RSpec Rails
+   ```
+3. **Test thoroughly**: Run RuboCop and address any new or changed violations
+4. **Update documentation**: Ensure your team is aware of the changes
+
+---
+
+For more information, visit the [simplycop repository](https://github.com/simplybusiness/simplycop) or reach out to the team in `#technical-excellence-community`.

data/lib/simplycop/version.rb

@@ -7,5 +7,5 @@
 #
 
 module Simplycop
-  VERSION = '2.20.0'
+  VERSION = '2.20.1'
 end

data/simplycop.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.version       = Simplycop::VERSION
   spec.authors       = ['Simply Business']
   spec.email         = ['tech@simplybusiness.co.uk']
-  spec.required_ruby_version = ['>= 3.1 ', '< 3.5']
+  spec.required_ruby_version = ['>= 3.2 ', '< 3.5']
   spec.license       = 'MIT'
   spec.summary       = 'Provides a single point of reference for common rubocop rules.'
   spec.description   = 'Require this gem in your application to use Simply Business common rubocop rules.'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: simplycop
 version: !ruby/object:Gem::Version
-  version: 2.20.0
+  version: 2.20.1
 platform: ruby
 authors:
 - Simply Business
 bindir: bin
 cert_chain: []
-date: 2025-06-23 00:00:00.000000000 Z
+date: 2025-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -239,7 +239,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.5'