From a859ce5668f1802dc9711c3a99daf5b43046ec5f Mon Sep 17 00:00:00 2001 From: Brian Austin Date: Tue, 2 Apr 2024 17:59:06 -0400 Subject: [PATCH 1/4] AO3-6691 Add Readme for custom RuboCop cops --- rubocop/cop/README.md | 122 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 rubocop/cop/README.md diff --git a/rubocop/cop/README.md b/rubocop/cop/README.md new file mode 100644 index 00000000000..1e034a7d9ff --- /dev/null +++ b/rubocop/cop/README.md @@ -0,0 +1,122 @@ +# Custom Cops + +This folder contains custom RuboCop rules (cops) we've writen +to enforce in-house conventions. To add a new rule, create +a Ruby file within the directory that matches the departmen +(category in RuboCop speak). Custom cops also need tests in `spec/rubocop`. + +## cucumber + +### regex_step_name +Checks that Cucumber step definitions use Cucumber expressions +instead of Regex. _Note:_ this may not always be possible, and this +cop is not smart enough to detect those cases. + +Avoid +```ruby +Given /foobar/ do + ... +end +When /baz/ do + ... +end +Then /oops(\w+)/ do |it| + ... +end +``` + +Prefer +```ruby +Given "foobar(s)" do + ... +end +When "baz" do + ... +end +Then "oops{str}" do |it| + ... +end + +# Exception: sometimes we still need regex +When /^I do the (\d+)(?:st|nd|rd|th) thing$/ do |ordinal| # rubocop:disable Cucumber/RegexStepName + ... +end +``` + +## i18n + +### default_translation +Checks for uses of the `default` keyword argument within Rails translation helpers. + +Avoid +```ruby +t(".translation_key", default: "English text") +``` + +Prefer +```ruby +# assuming the translation is in a view, the key must be defined in config/locales/views/en.yml +t(".translation_key") +``` + +### deprecated_helper +Checks for uses of the deprecated helper function, `ts`. +Strings passed to it cannot be translated, and all calls +will need to be replaced with `t` to enable UI translations +in the future. + +Avoid +```ruby +ts("This will only be in English :(") +ts("Hello %{name}", name: "world") +``` + +Prefer +```ruby +t(".relative.path.to.translation") +t(".greeting", name: "world") +``` + +### deprecated_translation_key +Checks for uses of translation keys that have been superseded +by others or different methods of translation. + +Avoid +```ruby +Category.human_attribute_name("name_with_colon", count: 1) +t(".relative.path.name_with_colon", count: 2) +``` + +Prefer +```ruby +Category.human_attribute_name("name", count: 1) + t("mailer.general.metadata_label_indicator") +metadata_property(t(".relative.path.name", count: 2)) # views only +``` + +Deprecated keys are listed in https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L23. + +## migration + +### large_table_schema_update +Checks that migrations updating the schema of large tables, +as defined in the configuration, do so safely. As of writing, +this involves utilizing the `uses_departure!` helper. + +Avoid +```ruby +class ExampleMigration < ActiveRecord::Migration[6.1] + add_column :users, :new_field, :integer, nullable: true +end +``` + +Prefer +```ruby +class ExampleMigration < ActiveRecord::Migration[6.1] + uses_departure! if Rails.env.staging? || Rails.env.production? + + add_column :users, :new_field, :integer, nullable: true +end +``` + +Tables that require Departure: +https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L81. From 90a7d57dda5e3266e49799c0d52df638e0601df2 Mon Sep 17 00:00:00 2001 From: Brian Austin Date: Tue, 2 Apr 2024 18:17:44 -0400 Subject: [PATCH 2/4] Fix typo --- rubocop/cop/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rubocop/cop/README.md b/rubocop/cop/README.md index 1e034a7d9ff..58f43f12c04 100644 --- a/rubocop/cop/README.md +++ b/rubocop/cop/README.md @@ -2,7 +2,7 @@ This folder contains custom RuboCop rules (cops) we've writen to enforce in-house conventions. To add a new rule, create -a Ruby file within the directory that matches the departmen +a Ruby file within the directory that matches the department (category in RuboCop speak). Custom cops also need tests in `spec/rubocop`. ## cucumber From a63467808afbf41bca76418190c99681b8e0381d Mon Sep 17 00:00:00 2001 From: Brian Austin Date: Tue, 2 Apr 2024 19:42:16 -0400 Subject: [PATCH 3/4] Embed links in text --- rubocop/cop/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/rubocop/cop/README.md b/rubocop/cop/README.md index 58f43f12c04..1940d3fda3e 100644 --- a/rubocop/cop/README.md +++ b/rubocop/cop/README.md @@ -93,7 +93,7 @@ Category.human_attribute_name("name", count: 1) + t("mailer.general.metadata_lab metadata_property(t(".relative.path.name", count: 2)) # views only ``` -Deprecated keys are listed in https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L23. +[Deprecated keys translation keys](https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L23) ## migration @@ -118,5 +118,4 @@ class ExampleMigration < ActiveRecord::Migration[6.1] end ``` -Tables that require Departure: -https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L81. +[Tables that require Departure](https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L81) From 9ce9db1d640e812dc2aa6955297cfa9e0d161dd2 Mon Sep 17 00:00:00 2001 From: Brian Austin Date: Tue, 2 Apr 2024 20:15:36 -0400 Subject: [PATCH 4/4] Remove duplicate word --- rubocop/cop/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rubocop/cop/README.md b/rubocop/cop/README.md index 1940d3fda3e..d68018b55a5 100644 --- a/rubocop/cop/README.md +++ b/rubocop/cop/README.md @@ -93,7 +93,7 @@ Category.human_attribute_name("name", count: 1) + t("mailer.general.metadata_lab metadata_property(t(".relative.path.name", count: 2)) # views only ``` -[Deprecated keys translation keys](https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L23) +[Deprecated translation keys](https://github.com/otwcode/otwarchive/blob/master/.rubocop.yml#L23) ## migration