From 41e3bacf4304cae851fd68af12b8efb0fd5134bc Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Fri, 28 Jul 2023 18:27:59 +0200 Subject: [PATCH 01/12] Import doc generation commands from rubocop-sorbet Import docs generator rake task from Shopify/rubocop-sorbet@76e7634. This allow us to create docs based on the cop's description. --- .rubocop.yml | 7 + Gemfile | 1 + Gemfile.lock | 2 + Rakefile | 7 +- docs/cops.md | 19 ++ docs/cops_solidus.md | 228 ++++++++++++++++++++++++ tasks/cops_documentation.rake | 316 ++++++++++++++++++++++++++++++++++ 7 files changed, 579 insertions(+), 1 deletion(-) create mode 100644 docs/cops.md create mode 100644 docs/cops_solidus.md create mode 100644 tasks/cops_documentation.rake diff --git a/.rubocop.yml b/.rubocop.yml index cab8b98..e625cef 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -14,6 +14,13 @@ Metrics/BlockLength: - 'spec/**/*.rb' - '*.gemspec' +Metrics/MethodLength: + Exclude: + - 'Rakefile' + - '**/*.rake' + - 'spec/**/*.rb' + - '*.gemspec' + Metrics/ClassLength: Exclude: - 'tasks/**/*.rb' diff --git a/Gemfile b/Gemfile index fd2f12d..f85b62b 100644 --- a/Gemfile +++ b/Gemfile @@ -10,3 +10,4 @@ gem 'pry' gem 'rake' gem 'rspec' gem 'rubocop' +gem 'yard' diff --git a/Gemfile.lock b/Gemfile.lock index 98eb330..edb7076 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -54,6 +54,7 @@ GEM parser (>= 3.2.1.0) ruby-progressbar (1.13.0) unicode-display_width (2.4.2) + yard (0.9.34) PLATFORMS -darwin-22 @@ -69,6 +70,7 @@ DEPENDENCIES rspec rubocop rubocop-solidus! + yard BUNDLED WITH 2.3.26 diff --git a/Rakefile b/Rakefile index 2f1f2bb..3dfa414 100644 --- a/Rakefile +++ b/Rakefile @@ -6,7 +6,12 @@ require 'rspec/core/rake_task' Dir['tasks/**/*.rake'].each { |t| load t } -task default: %i[spec rubocop] +task default: %i[ + spec + rubocop + generate_cops_documentation + documentation_syntax_check +] RuboCop::RakeTask.new diff --git a/docs/cops.md b/docs/cops.md new file mode 100644 index 0000000..c7b14ed --- /dev/null +++ b/docs/cops.md @@ -0,0 +1,19 @@ +## Available cops + +In the following section you find all available cops: + + +#### Department [Solidus](cops_solidus.md) + +* [Solidus/ClassEvalDecorator](cops_solidus.md#solidusclassevaldecorator) +* [Solidus/ReimbursementHookDeprecated](cops_solidus.md#solidusreimbursementhookdeprecated) +* [Solidus/SpreeCalculatorFreeShippingDeprecated](cops_solidus.md#solidusspreecalculatorfreeshippingdeprecated) +* [Solidus/SpreeCalculatorPercentPerItemDeprecated](cops_solidus.md#solidusspreecalculatorpercentperitemdeprecated) +* [Solidus/SpreeCalculatorPriceSackDeprecated](cops_solidus.md#solidusspreecalculatorpricesackdeprecated) +* [Solidus/SpreeDefaultCreditCardDeprecated](cops_solidus.md#solidusspreedefaultcreditcarddeprecated) +* [Solidus/SpreeGatewayBogusDeprecated](cops_solidus.md#solidusspreegatewaybogusdeprecated) +* [Solidus/SpreeIconDeprecated](cops_solidus.md#solidusspreeicondeprecated) +* [Solidus/SpreeRefundCallPerform](cops_solidus.md#solidusspreerefundcallperform) +* [Solidus/SpreeTDeprecated](cops_solidus.md#solidusspreetdeprecated) + + \ No newline at end of file diff --git a/docs/cops_solidus.md b/docs/cops_solidus.md new file mode 100644 index 0000000..b10b8db --- /dev/null +++ b/docs/cops_solidus.md @@ -0,0 +1,228 @@ +# Solidus + +## Solidus/ClassEvalDecorator + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - + +TODO: Write cop description and example of bad / good code. For every +`SupportedStyle` and unique configuration, there needs to be examples. +Examples must have valid Ruby syntax. Do not use upticks. + +### Examples + +#### EnforcedStyle: SpreeClass + +```ruby +# Description of the `SpreeClass` style. + +# bad +SpreeClass.class_eval do +. +. +end + +# good +module SpreeClassDecorator +. +. +end +``` + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/21](https://github.com/solidusio/rubocop-solidus/issues/21) + +## Solidus/ReimbursementHookDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - + +This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and +asks to remove them and subscribe to reimbursement_reimbursed event instead. + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/27](https://github.com/solidusio/rubocop-solidus/issues/27) + +## Solidus/SpreeCalculatorFreeShippingDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - + +This cop finds Spree::Calculator::FreeShipping calls. +This cop is needed as they have been deprecated in future version. + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) + +## Solidus/SpreeCalculatorPercentPerItemDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - + +This cop finds Spree::Calculator::PercentPerItem calls. +This cop is needed as they have been deprecated in future version. + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) + +## Solidus/SpreeCalculatorPriceSackDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - + +This cop finds Spree::Calculator::PriceSack calls. +This cop is needed as they have been deprecated in future version. + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) + +## Solidus/SpreeDefaultCreditCardDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - + +This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source + +### Examples + +#### EnforcedStyle: + +```ruby +# bad +user.default_credit_card + +# good +user.wallet.default_wallet_payment_source +``` + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/33](https://github.com/solidusio/rubocop-solidus/issues/33) + +## Solidus/SpreeGatewayBogusDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - + +This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard call +This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version. + +### Examples + +#### EnforcedStyle: + +```ruby +# bad +Spree::Gateway::Bogus.new + +# good +Spree::PaymentMethod::BogusCreditCard.new + +# bad +Spree::Gateway::Bogus.create + +# good +Spree::PaymentMethod::BogusCreditCard.create + +# bad +Spree::Gateway::Bogus.create! + +# good +Spree::PaymentMethod::BogusCreditCard.create! +``` + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/26](https://github.com/solidusio/rubocop-solidus/issues/26) + +## Solidus/SpreeIconDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - + +This cop finds icon helper calls and suggest using solidus_icon + +### Examples + +#### EnforcedStyle: + +```ruby +# bad +helper.icon('example') + +# good +helper.solidus_icon('example') +``` + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/32](https://github.com/solidusio/rubocop-solidus/issues/32) + +## Solidus/SpreeRefundCallPerform + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - + +This cop finds Spree::Refund.create(your: attributes) calls and +replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/28](https://github.com/solidusio/rubocop-solidus/issues/28) + +## Solidus/SpreeTDeprecated + +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged +--- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - + +This cop finds Spree.t method calls and replaces them with the I18n,t method call +This cop is needed as the Spree.t version has been deprecated in future version. + +### Examples + +#### EnforcedStyle: bar (default) + +```ruby +# bad +Spree.t(:bar) + +# good +I18n.t(:bar, scope: :spree) + +# bad +Spree.t(:bar, scope: [:city]) + +# good +I18n.t(:bar, scope: [:spree, :city]) + +# bad +Spree.t(:bar, scope: [:city], email: email) + +# good +I18n.t(:bar, scope: [:spree, :city], email: email) + +# bad +Spree.t('bar', scope: 'admin.city') + +# good +I18n.t('bar', scope: 'spree.admin.city') +``` + +### References + +* [https://github.com/solidusio/rubocop-solidus/issues/22](https://github.com/solidusio/rubocop-solidus/issues/22) diff --git a/tasks/cops_documentation.rake b/tasks/cops_documentation.rake new file mode 100644 index 0000000..07fe596 --- /dev/null +++ b/tasks/cops_documentation.rake @@ -0,0 +1,316 @@ +# frozen_string_literal: true + +require 'yard' +require 'rubocop' +require 'rubocop-solidus' + +YARD::Rake::YardocTask.new(:yard_for_generate_documentation) do |task| + task.files = ['lib/rubocop/cop/**/*.rb'] + task.options = ['--no-output'] +end + +desc('Generate docs of all cops departments') +task generate_cops_documentation: :yard_for_generate_documentation do + def cops_of_department(cops, department) + cops.with_department(department).sort! + end + + def cops_body(config, cop, description, examples_objects, pars) + content = h2(cop.cop_name) + content << required_ruby_version(cop) + content << properties(config, cop) + content << "#{description}\n" + content << examples(examples_objects) if examples_objects.count.positive? + content << configurations(pars) + content << references(config, cop) + content + end + + def examples(examples_object) + examples_object.each_with_object(h3('Examples').dup) do |example, content| + content << h4(example.name) unless example.name == '' + content << code_example(example) + end + end + + def required_ruby_version(cop) + return '' unless cop.respond_to?(:required_minimum_ruby_version) + + <<~NOTE + !!! Note + + Required Ruby version: #{cop.required_minimum_ruby_version} + + NOTE + end + + def properties(config, cop) + header = [ + 'Enabled by default', 'Safe', 'Supports autocorrection', 'VersionAdded', + 'VersionChanged' + ] + config = config.for_cop(cop) + safe_auto_correct = config.fetch('SafeAutoCorrect', true) + autocorrect = if cop.support_autocorrect? + "Yes #{'(Unsafe)' unless safe_auto_correct}" + else + 'No' + end + content = [[ + config.fetch('Enabled') ? 'Enabled' : 'Disabled', + config.fetch('Safe', true) ? 'Yes' : 'No', + autocorrect, + config.fetch('VersionAdded', '-'), + config.fetch('VersionChanged', '-') + ]] + "#{to_table(header, content)}\n" + end + + def h2(title) + content = +"\n" + content << "## #{title}\n" + content << "\n" + content + end + + def h3(title) + content = +"\n" + content << "### #{title}\n" + content << "\n" + content + end + + def h4(title) + content = +"#### #{title}\n" + content << "\n" + content + end + + def code_example(ruby_code) + content = +"```ruby\n" + content << ruby_code.text + .gsub('@good', '# good').gsub('@bad', '# bad').strip + content << "\n```\n" + content + end + + def configurations(pars) + return '' if pars.empty? + + header = ['Name', 'Default value', 'Configurable values'] + configs = pars.each_key.reject { |key| key.start_with?('Supported') } + content = configs.map do |name| + configurable = configurable_values(pars, name) + default = format_table_value(pars[name]) + [name, default, configurable] + end + + h3('Configurable attributes') + to_table(header, content) + end + + # rubocop:disable Metrics/CyclomaticComplexity + def configurable_values(pars, name) + case name + when /^Enforced/ + supported_style_name = RuboCop::Cop::Util.to_supported_styles(name) + format_table_value(pars[supported_style_name]) + when 'IndentationWidth' + 'Integer' + when 'Database' + format_table_value(pars['SupportedDatabases']) + else + case pars[name] + when String + 'String' + when Integer + 'Integer' + when Float + 'Float' + when true, false + 'Boolean' + when Array + 'Array' + else + '' + end + end + end + # rubocop:enable Metrics/CyclomaticComplexity + + def to_table(header, content) + table = [ + header.join(' | '), + Array.new(header.size, '---').join(' | ') + ] + table.concat(content.map { |c| c.join(' | ') }) + "#{table.join("\n")}\n" + end + + def format_table_value(val) + value = + case val + when Array + if val.empty? + '`[]`' + else + val.map { |config| format_table_value(config) }.join(', ') + end + else + "`#{val.nil? ? '' : val}`" + end + value.gsub("#{Dir.pwd}/", '').rstrip + end + + def references(config, cop) + cop_config = config.for_cop(cop) + urls = RuboCop::Cop::MessageAnnotator.new( + config, cop.name, cop_config, {} + ).urls + return '' if urls.empty? + + content = h3('References') + content << urls.map { |url| "* [#{url}](#{url})" }.join("\n") + content << "\n" + content + end + + def print_cops_of_department(cops, department, config) + selected_cops = cops_of_department(cops, department).select do |cop| + cop.to_s.start_with?('RuboCop::Cop::Solidus') + end + return if selected_cops.empty? + + content = +"# #{department}\n" + selected_cops.each do |cop| + content << print_cop_with_doc(cop, config) + end + file_name = "#{Dir.pwd}/docs/cops_#{department.downcase}.md" + File.open(file_name, 'w') do |file| + puts "* generated #{file_name}" + file.write("#{content.strip}\n") + end + end + + def print_cop_with_doc(cop, config) + t = config.for_cop(cop) + non_display_keys = %w[Description Enabled StyleGuide Reference Safe SafeAutoCorrect VersionAdded + VersionChanged] + pars = t.reject { |k| non_display_keys.include?(k) } + description = 'No documentation' + examples_object = [] + YARD::Registry.all(:class).detect do |code_object| + next unless RuboCop::Cop::Badge.for(code_object.to_s) == cop.badge + + description = code_object.docstring unless code_object.docstring.blank? + examples_object = code_object.tags('example') + end + cops_body(config, cop, description, examples_object, pars) + end + + # rubocop:disable Metrics/AbcSize + def table_of_content_for_department(cops, department) + selected_cops = cops_of_department(cops, department.to_sym).select do |cop| + cop.to_s.start_with?('RuboCop::Cop::Solidus') + end + return if selected_cops.empty? + + type_title = department[0].upcase + department[1..] + filename = "cops_#{department.downcase}.md" + content = +"#### Department [#{type_title}](#{filename})\n\n" + selected_cops.each do |cop| + anchor = cop.cop_name.sub('/', '').downcase + content << "* [#{cop.cop_name}](#{filename}##{anchor})\n" + end + + content + end + # rubocop:enable Metrics/AbcSize + + def print_table_of_contents(cops) + path = "#{Dir.pwd}/docs/cops.md" + original = File.read(path) + content = +"\n" + + content << table_contents(cops) + + content << "\n" + + unless original.empty? + content = original.sub( + /.+/m, content + ) + end + File.write(path, content) + end + + def table_contents(cops) + cops + .departments + .map(&:to_s) + .sort + .map { |department| table_of_content_for_department(cops, department) } + .compact + .join("\n") + end + + def assert_docs_synchronized + # Do not print diff and yield whether exit code was zero + sh('git diff --quiet docs') do |outcome, _| + return if outcome + + # Output diff before raising error + sh('GIT_PAGER=cat git diff docs') + + warn('The docs directory is out of sync. ' \ + 'Run `rake generate_cops_documentation` and commit the results.') + exit! + end + end + + def main + cops = RuboCop::Cop::Cop.registry + config = RuboCop::ConfigLoader.load_file('config/default.yml') + + YARD::Registry.load! + cops.departments.sort!.each do |department| + print_cops_of_department(cops, department, config) + end + + print_table_of_contents(cops) + + assert_docs_synchronized if ENV['CI'] == 'true' + ensure + RuboCop::ConfigLoader.default_configuration = nil + end + + main +end + +desc('Syntax check for the documentation comments') +task documentation_syntax_check: :yard_for_generate_documentation do + require 'parser/ruby27' + + ok = true + YARD::Registry.load! + cops = RuboCop::Cop::Cop.registry + cops.each do |cop| + examples = YARD::Registry.all(:class).find do |code_object| + next unless RuboCop::Cop::Badge.for(code_object.to_s) == cop.badge + + break code_object.tags('example') + end + + examples.to_a.each do |example| + buffer = Parser::Source::Buffer.new('', 1) + buffer.source = example.text + parser = Parser::Ruby27.new(RuboCop::AST::Builder.new) + parser.diagnostics.all_errors_are_fatal = true + parser.parse(buffer) + rescue Parser::SyntaxError => e + path = example.object.file + puts "#{path}: Syntax Error in an example. #{e}" + ok = false + end + end + abort unless ok +end From 7b79e448969edc02628f22be47bcb15d42d3c950 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 10:59:05 +0200 Subject: [PATCH 02/12] Improve cop's descriptions and examples Some cop descriptions still need to be written, and others don't have relatively bad/good examples. So we updated all descriptions and regenerated the docs. --- docs/cops_solidus.md | 118 ++++++++++++------ .../cop/solidus/class_eval_decorator.rb | 28 ++--- .../solidus/reimbursement_hook_deprecated.rb | 17 +++ ...ree_calculator_free_shipping_deprecated.rb | 7 ++ ..._calculator_percent_per_item_deprecated.rb | 10 +- .../spree_calculator_price_sack_deprecated.rb | 7 ++ .../spree_default_credit_card_deprecated.rb | 7 +- .../solidus/spree_gateway_bogus_deprecated.rb | 18 +-- .../cop/solidus/spree_icon_deprecated.rb | 6 +- .../cop/solidus/spree_refund_call_perform.rb | 11 +- lib/rubocop/cop/solidus/spree_t_deprecated.rb | 16 ++- .../cop/solidus/class_eval_decorator_spec.rb | 2 +- ...ulator_percent_per_item_deprecated_spec.rb | 4 +- 13 files changed, 169 insertions(+), 82 deletions(-) diff --git a/docs/cops_solidus.md b/docs/cops_solidus.md index b10b8db..e48accd 100644 --- a/docs/cops_solidus.md +++ b/docs/cops_solidus.md @@ -6,27 +6,25 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan --- | --- | --- | --- | --- Enabled | Yes | No | 0.1.0 | - -TODO: Write cop description and example of bad / good code. For every -`SupportedStyle` and unique configuration, there needs to be examples. -Examples must have valid Ruby syntax. Do not use upticks. +Solidus suggests a decorator module instead of `class_eval` when overriding some features. +This cop finds any `class_eval` and asks to use a decorator module instead. +More info: https://guides.solidus.io/customization/customizing-the-core. ### Examples -#### EnforcedStyle: SpreeClass - ```ruby -# Description of the `SpreeClass` style. - # bad SpreeClass.class_eval do -. -. + # your code here end # good -module SpreeClassDecorator -. -. +module Spree + module SpreeClassDecorator + # your code here + end + + Spree::SpreeClass.prepend self end ``` @@ -43,6 +41,23 @@ Enabled | Yes | No | 0.1.0 | - This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and asks to remove them and subscribe to reimbursement_reimbursed event instead. +### Examples + +```ruby +# bad +reimbursement_success_hooks.each { |h| h.call self } +reimbursement_failed_hooks.each { |h| h.call self } + +# good +``` +```ruby +# bad +reimbursement_success_hooks.any? +reimbursement_failed_hooks.any? + +# good +``` + ### References * [https://github.com/solidusio/rubocop-solidus/issues/27](https://github.com/solidusio/rubocop-solidus/issues/27) @@ -56,6 +71,15 @@ Enabled | Yes | No | 0.1.0 | - This cop finds Spree::Calculator::FreeShipping calls. This cop is needed as they have been deprecated in future version. +### Examples + +```ruby +# bad +Spree::Calculator::FreeShipping + +# good +``` + ### References * [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) @@ -69,6 +93,16 @@ Enabled | Yes | Yes | 0.1.0 | - This cop finds Spree::Calculator::PercentPerItem calls. This cop is needed as they have been deprecated in future version. +### Examples + +```ruby +# bad +Spree::Calculator::PercentPerItem + +# good +Spree::Calculator::PercentOnLineItem +``` + ### References * [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) @@ -82,6 +116,15 @@ Enabled | Yes | No | 0.1.0 | - This cop finds Spree::Calculator::PriceSack calls. This cop is needed as they have been deprecated in future version. +### Examples + +```ruby +# bad +Spree::Calculator::PriceSack + +# good +``` + ### References * [https://github.com/solidusio/rubocop-solidus/issues/29](https://github.com/solidusio/rubocop-solidus/issues/29) @@ -92,12 +135,10 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan --- | --- | --- | --- | --- Enabled | Yes | Yes | 0.1.0 | - -This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source +This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source. ### Examples -#### EnforcedStyle: - ```ruby # bad user.default_credit_card @@ -116,30 +157,20 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan --- | --- | --- | --- | --- Enabled | Yes | Yes | 0.1.0 | - -This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard call +This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard. This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version. ### Examples -#### EnforcedStyle: - ```ruby # bad Spree::Gateway::Bogus.new - -# good -Spree::PaymentMethod::BogusCreditCard.new - -# bad Spree::Gateway::Bogus.create - -# good -Spree::PaymentMethod::BogusCreditCard.create - -# bad Spree::Gateway::Bogus.create! # good +Spree::PaymentMethod::BogusCreditCard.new +Spree::PaymentMethod::BogusCreditCard.create Spree::PaymentMethod::BogusCreditCard.create! ``` @@ -153,12 +184,10 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan --- | --- | --- | --- | --- Enabled | Yes | Yes | 0.1.0 | - -This cop finds icon helper calls and suggest using solidus_icon +This cop finds icon helper calls and suggest using solidus_icon. ### Examples -#### EnforcedStyle: - ```ruby # bad helper.icon('example') @@ -178,7 +207,17 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan Enabled | Yes | No | 0.1.0 | - This cop finds Spree::Refund.create(your: attributes) calls and -replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call +replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call. + +### Examples + +```ruby +# bad +Spree::Refund.create(your: attributes) + +# good +Spree::Refund.create(your: attributes, perform_after_create: false).perform! +``` ### References @@ -190,31 +229,40 @@ Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChan --- | --- | --- | --- | --- Enabled | Yes | Yes | 0.1.0 | - -This cop finds Spree.t method calls and replaces them with the I18n,t method call +This cop finds Spree.t method calls and replaces them with the I18n,t method call. This cop is needed as the Spree.t version has been deprecated in future version. ### Examples -#### EnforcedStyle: bar (default) - ```ruby +# Without any parameters + # bad Spree.t(:bar) # good I18n.t(:bar, scope: :spree) +``` +```ruby +# With the scope parameter # bad Spree.t(:bar, scope: [:city]) # good I18n.t(:bar, scope: [:spree, :city]) +``` +```ruby +# With the scope and other parameters # bad Spree.t(:bar, scope: [:city], email: email) # good I18n.t(:bar, scope: [:spree, :city], email: email) +``` +```ruby +# With the scope parameter as a string # bad Spree.t('bar', scope: 'admin.city') diff --git a/lib/rubocop/cop/solidus/class_eval_decorator.rb b/lib/rubocop/cop/solidus/class_eval_decorator.rb index a0c53a1..c2ca9c6 100644 --- a/lib/rubocop/cop/solidus/class_eval_decorator.rb +++ b/lib/rubocop/cop/solidus/class_eval_decorator.rb @@ -3,35 +3,31 @@ module RuboCop module Cop module Solidus - # TODO: Write cop description and example of bad / good code. For every - # `SupportedStyle` and unique configuration, there needs to be examples. - # Examples must have valid Ruby syntax. Do not use upticks. + # Solidus suggests a decorator module instead of `class_eval` when overriding some features. + # This cop finds any `class_eval` and asks to use a decorator module instead. + # More info: https://guides.solidus.io/customization/customizing-the-core. # - # - # @example EnforcedStyle: SpreeClass - # # Description of the `SpreeClass` style. + # @example # # # bad # SpreeClass.class_eval do - # . - # . + # # your code here # end # - # # # good - # module SpreeClassDecorator - # . - # . + # module Spree + # module SpreeClassDecorator + # # your code here + # end + # + # Spree::SpreeClass.prepend self # end # class ClassEvalDecorator < Base - MSG = 'Do not use `class_eval` flag. Use a decorator module instead. Check this link for an example https://guides.solidus.io/cookbook/redefining-checkout-steps' + MSG = 'Do not use `class_eval` flag. Use a decorator module instead. More info: https://guides.solidus.io/customization/customizing-the-core.' - # TODO: Don't call `on_send` unless the method name is in this list - # If you don't need `on_send` in the cop you created, remove it. RESTRICT_ON_SEND = %i[class_eval].freeze - # @!method on_class_eval?(node) def_node_matcher :on_class_eval?, <<~PATTERN (send ($...) :class_eval) PATTERN diff --git a/lib/rubocop/cop/solidus/reimbursement_hook_deprecated.rb b/lib/rubocop/cop/solidus/reimbursement_hook_deprecated.rb index 1dff36f..c64c753 100644 --- a/lib/rubocop/cop/solidus/reimbursement_hook_deprecated.rb +++ b/lib/rubocop/cop/solidus/reimbursement_hook_deprecated.rb @@ -5,6 +5,23 @@ module Cop module Solidus # This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and # asks to remove them and subscribe to reimbursement_reimbursed event instead. + # + # @example + # + # # bad + # reimbursement_success_hooks.each { |h| h.call self } + # reimbursement_failed_hooks.each { |h| h.call self } + # + # # good + # + # @example + # + # # bad + # reimbursement_success_hooks.any? + # reimbursement_failed_hooks.any? + # + # # good + # class ReimbursementHookDeprecated < Base include TargetSolidusVersion minimum_solidus_version 2.11 diff --git a/lib/rubocop/cop/solidus/spree_calculator_free_shipping_deprecated.rb b/lib/rubocop/cop/solidus/spree_calculator_free_shipping_deprecated.rb index d62f6cc..bacbc60 100644 --- a/lib/rubocop/cop/solidus/spree_calculator_free_shipping_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_calculator_free_shipping_deprecated.rb @@ -6,6 +6,13 @@ module Solidus # This cop finds Spree::Calculator::FreeShipping calls. # This cop is needed as they have been deprecated in future version. # + # @example + # + # # bad + # Spree::Calculator::FreeShipping + # + # # good + # class SpreeCalculatorFreeShippingDeprecated < Base MSG = 'Spree::Calculator::FreeShipping is deprecated.' diff --git a/lib/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated.rb b/lib/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated.rb index 13cca20..40663ca 100644 --- a/lib/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated.rb @@ -6,10 +6,18 @@ module Solidus # This cop finds Spree::Calculator::PercentPerItem calls. # This cop is needed as they have been deprecated in future version. # + # @example + # + # # bad + # Spree::Calculator::PercentPerItem + # + # # good + # Spree::Calculator::PercentOnLineItem + # class SpreeCalculatorPercentPerItemDeprecated < Base extend AutoCorrector - MSG = 'Spree::Calculator::PercentPerItem is deprecated.' + MSG = 'Spree::Calculator::PercentPerItem is deprecated. Use Spree::Calculator::PercentOnLineItem instead.' def_node_matcher :percent_per_item?, <<~PATTERN (send (... (... :Calculator) :PercentPerItem) $_) diff --git a/lib/rubocop/cop/solidus/spree_calculator_price_sack_deprecated.rb b/lib/rubocop/cop/solidus/spree_calculator_price_sack_deprecated.rb index 9200c7e..b67cc27 100644 --- a/lib/rubocop/cop/solidus/spree_calculator_price_sack_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_calculator_price_sack_deprecated.rb @@ -6,6 +6,13 @@ module Solidus # This cop finds Spree::Calculator::PriceSack calls. # This cop is needed as they have been deprecated in future version. # + # @example + # + # # bad + # Spree::Calculator::PriceSack + # + # # good + # class SpreeCalculatorPriceSackDeprecated < Base MSG = 'Spree::Calculator::PriceSack is deprecated.' diff --git a/lib/rubocop/cop/solidus/spree_default_credit_card_deprecated.rb b/lib/rubocop/cop/solidus/spree_default_credit_card_deprecated.rb index 3194c65..d7f34ec 100644 --- a/lib/rubocop/cop/solidus/spree_default_credit_card_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_default_credit_card_deprecated.rb @@ -3,16 +3,16 @@ module RuboCop module Cop module Solidus - # This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source + # This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source. + # + # @example # - # @example EnforcedStyle: # # bad # user.default_credit_card # # # good # user.wallet.default_wallet_payment_source # - # class SpreeDefaultCreditCardDeprecated < Base extend AutoCorrector include TargetSolidusVersion @@ -20,7 +20,6 @@ class SpreeDefaultCreditCardDeprecated < Base MSG = 'user.default_credit_card is deprecated. Please use user.wallet.default_wallet_payment_source instead.' - # @!method bad_method?(node) def_node_matcher :default_credit_card?, <<~PATTERN (send ... :default_credit_card) PATTERN diff --git a/lib/rubocop/cop/solidus/spree_gateway_bogus_deprecated.rb b/lib/rubocop/cop/solidus/spree_gateway_bogus_deprecated.rb index da55527..29f455c 100644 --- a/lib/rubocop/cop/solidus/spree_gateway_bogus_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_gateway_bogus_deprecated.rb @@ -3,29 +3,20 @@ module RuboCop module Cop module Solidus - # This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard call + # This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard. # This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version. # - # @example EnforcedStyle: + # @example # # bad # Spree::Gateway::Bogus.new - # - # # good - # Spree::PaymentMethod::BogusCreditCard.new - # - # # bad # Spree::Gateway::Bogus.create - # - # # good - # Spree::PaymentMethod::BogusCreditCard.create - # - # # bad # Spree::Gateway::Bogus.create! # # # good + # Spree::PaymentMethod::BogusCreditCard.new + # Spree::PaymentMethod::BogusCreditCard.create # Spree::PaymentMethod::BogusCreditCard.create! # - # class SpreeGatewayBogusDeprecated < Base extend AutoCorrector include TargetSolidusVersion @@ -33,7 +24,6 @@ class SpreeGatewayBogusDeprecated < Base MSG = 'Spree::Gateway::Bogus is deprecated. Please use Spree::PaymentMethod::BogusCreditCard instead.' - # @!method bad_method?(node) def_node_matcher :bad_class?, <<~PATTERN (send (... (... :Gateway) :Bogus) $_) PATTERN diff --git a/lib/rubocop/cop/solidus/spree_icon_deprecated.rb b/lib/rubocop/cop/solidus/spree_icon_deprecated.rb index dcddd31..cdffbd6 100644 --- a/lib/rubocop/cop/solidus/spree_icon_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_icon_deprecated.rb @@ -3,16 +3,16 @@ module RuboCop module Cop module Solidus - # This cop finds icon helper calls and suggest using solidus_icon + # This cop finds icon helper calls and suggest using solidus_icon. + # + # @example # - # @example EnforcedStyle: # # bad # helper.icon('example') # # # good # helper.solidus_icon('example') # - # class SpreeIconDeprecated < Base extend AutoCorrector include TargetSolidusVersion diff --git a/lib/rubocop/cop/solidus/spree_refund_call_perform.rb b/lib/rubocop/cop/solidus/spree_refund_call_perform.rb index a8c31aa..5fda868 100644 --- a/lib/rubocop/cop/solidus/spree_refund_call_perform.rb +++ b/lib/rubocop/cop/solidus/spree_refund_call_perform.rb @@ -4,7 +4,15 @@ module RuboCop module Cop module Solidus # This cop finds Spree::Refund.create(your: attributes) calls and - # replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call + # replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call. + # + # @example + # + # # bad + # Spree::Refund.create(your: attributes) + # + # # good + # Spree::Refund.create(your: attributes, perform_after_create: false).perform! # class SpreeRefundCallPerform < Base include TargetSolidusVersion @@ -16,7 +24,6 @@ class SpreeRefundCallPerform < Base RESTRICT_ON_SEND = %i[create].freeze - # @!method bad_method?(node) def_node_matcher :create_refund?, <<~PATTERN (send (const (const nil? :Spree) :Refund) :create ...) PATTERN diff --git a/lib/rubocop/cop/solidus/spree_t_deprecated.rb b/lib/rubocop/cop/solidus/spree_t_deprecated.rb index 44554c6..9f6ba11 100644 --- a/lib/rubocop/cop/solidus/spree_t_deprecated.rb +++ b/lib/rubocop/cop/solidus/spree_t_deprecated.rb @@ -3,43 +3,51 @@ module RuboCop module Cop module Solidus - # This cop finds Spree.t method calls and replaces them with the I18n,t method call + # This cop finds Spree.t method calls and replaces them with the I18n,t method call. # This cop is needed as the Spree.t version has been deprecated in future version. # + # @example + # # Without any parameters # - # @example EnforcedStyle: bar (default) # # bad # Spree.t(:bar) # # # good # I18n.t(:bar, scope: :spree) # + # @example + # # With the scope parameter + # # # bad # Spree.t(:bar, scope: [:city]) # # # good # I18n.t(:bar, scope: [:spree, :city]) # + # @example + # # With the scope and other parameters + # # # bad # Spree.t(:bar, scope: [:city], email: email) # # # good # I18n.t(:bar, scope: [:spree, :city], email: email) # + # @example + # # With the scope parameter as a string + # # # bad # Spree.t('bar', scope: 'admin.city') # # # good # I18n.t('bar', scope: 'spree.admin.city') # - # class SpreeTDeprecated < Base extend AutoCorrector MSG = 'Use I18n.t instead of Spree.t which has been deprecated in future versions.' RESTRICT_ON_SEND = %i[t].freeze - # @!method spree_t?(node) def_node_matcher :spree_t?, <<~PATTERN (send ($...) :t ...) PATTERN diff --git a/spec/rubocop/cop/solidus/class_eval_decorator_spec.rb b/spec/rubocop/cop/solidus/class_eval_decorator_spec.rb index fb47b3a..96476c6 100644 --- a/spec/rubocop/cop/solidus/class_eval_decorator_spec.rb +++ b/spec/rubocop/cop/solidus/class_eval_decorator_spec.rb @@ -4,7 +4,7 @@ it 'registers an offense when using `#bad_method`' do expect_offense(<<~RUBY) Product.class_eval do - ^^^^^^^^^^^^^^^^^^ Do not use `class_eval` flag. Use a decorator module instead. Check this link for an example https://guides.solidus.io/cookbook/redefining-checkout-steps\n + ^^^^^^^^^^^^^^^^^^ Do not use `class_eval` flag. Use a decorator module instead. More info: https://guides.solidus.io/customization/customizing-the-core.\n end RUBY diff --git a/spec/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated_spec.rb b/spec/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated_spec.rb index eefcf78..0769357 100644 --- a/spec/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated_spec.rb +++ b/spec/rubocop/cop/solidus/spree_calculator_percent_per_item_deprecated_spec.rb @@ -5,7 +5,7 @@ it 'registers an offense when using `#new`' do expect_offense(<<~RUBY) Spree::Calculator::PercentPerItem.new - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spree::Calculator::PercentPerItem is deprecated. + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spree::Calculator::PercentPerItem is deprecated. Use Spree::Calculator::PercentOnLineItem instead. RUBY end @@ -20,7 +20,7 @@ it 'registers an offense when using `#create`' do expect_offense(<<~RUBY) Spree::Calculator::PercentPerItem.create - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spree::Calculator::PercentPerItem is deprecated. + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Spree::Calculator::PercentPerItem is deprecated. Use Spree::Calculator::PercentOnLineItem instead. RUBY end From c933192b930321a8964ac513ccca7c1ff163c022 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 11:34:27 +0200 Subject: [PATCH 03/12] Add info about required solidus version in docs --- docs/cops_solidus.md | 60 +++++++++---------- .../cop/mixin/target_solidus_version.rb | 4 ++ tasks/cops_documentation.rake | 10 +++- 3 files changed, 42 insertions(+), 32 deletions(-) diff --git a/docs/cops_solidus.md b/docs/cops_solidus.md index e48accd..d191eb8 100644 --- a/docs/cops_solidus.md +++ b/docs/cops_solidus.md @@ -2,9 +2,9 @@ ## Solidus/ClassEvalDecorator -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | No | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - | - Solidus suggests a decorator module instead of `class_eval` when overriding some features. This cop finds any `class_eval` and asks to use a decorator module instead. @@ -34,9 +34,9 @@ end ## Solidus/ReimbursementHookDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | No | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - | 2.11 This cop finds reimbursement_success_hooks and reimbursement_failed_hooks calls and asks to remove them and subscribe to reimbursement_reimbursed event instead. @@ -64,9 +64,9 @@ reimbursement_failed_hooks.any? ## Solidus/SpreeCalculatorFreeShippingDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | No | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - | - This cop finds Spree::Calculator::FreeShipping calls. This cop is needed as they have been deprecated in future version. @@ -86,9 +86,9 @@ Spree::Calculator::FreeShipping ## Solidus/SpreeCalculatorPercentPerItemDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | Yes | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - | - This cop finds Spree::Calculator::PercentPerItem calls. This cop is needed as they have been deprecated in future version. @@ -109,9 +109,9 @@ Spree::Calculator::PercentOnLineItem ## Solidus/SpreeCalculatorPriceSackDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | No | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - | - This cop finds Spree::Calculator::PriceSack calls. This cop is needed as they have been deprecated in future version. @@ -131,9 +131,9 @@ Spree::Calculator::PriceSack ## Solidus/SpreeDefaultCreditCardDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | Yes | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - | 2.2 This cop finds user.default_credit_card suggest using user.wallet.default_wallet_payment_source. @@ -153,9 +153,9 @@ user.wallet.default_wallet_payment_source ## Solidus/SpreeGatewayBogusDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | Yes | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - | 2.1 This cop finds Spree::Gateway::Bogus calls and replaces them with the Spree::PaymentMethod::BogusCreditCard. This cop is needed as the Spree::Gateway::Bogus has been deprecated in future version. @@ -180,9 +180,9 @@ Spree::PaymentMethod::BogusCreditCard.create! ## Solidus/SpreeIconDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | Yes | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - | 2.3 This cop finds icon helper calls and suggest using solidus_icon. @@ -202,9 +202,9 @@ helper.solidus_icon('example') ## Solidus/SpreeRefundCallPerform -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | No | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | No | 0.1.0 | - | 2.11 This cop finds Spree::Refund.create(your: attributes) calls and replaces them with the Spree::Refund.create(your: attributes, perform_after_create: false).perform! call. @@ -225,9 +225,9 @@ Spree::Refund.create(your: attributes, perform_after_create: false).perform! ## Solidus/SpreeTDeprecated -Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged ---- | --- | --- | --- | --- -Enabled | Yes | Yes | 0.1.0 | - +Enabled by default | Safe | Supports autocorrection | VersionAdded | VersionChanged | Required Solidus Version +--- | --- | --- | --- | --- | --- +Enabled | Yes | Yes | 0.1.0 | - | - This cop finds Spree.t method calls and replaces them with the I18n,t method call. This cop is needed as the Spree.t version has been deprecated in future version. diff --git a/lib/rubocop/cop/mixin/target_solidus_version.rb b/lib/rubocop/cop/mixin/target_solidus_version.rb index b4e36ca..fa3966f 100644 --- a/lib/rubocop/cop/mixin/target_solidus_version.rb +++ b/lib/rubocop/cop/mixin/target_solidus_version.rb @@ -24,6 +24,10 @@ def minimum_solidus_version(version) def targeted_solidus_version?(version) Gem::Version.new(@minimum_solidus_version) <= Gem::Version.new(version) end + + def required_minimum_solidus_version + @minimum_solidus_version + end end # This method overrides the one in RuboCop::Cop::Base. diff --git a/tasks/cops_documentation.rake b/tasks/cops_documentation.rake index 07fe596..b8dd1f3 100644 --- a/tasks/cops_documentation.rake +++ b/tasks/cops_documentation.rake @@ -47,7 +47,7 @@ task generate_cops_documentation: :yard_for_generate_documentation do def properties(config, cop) header = [ 'Enabled by default', 'Safe', 'Supports autocorrection', 'VersionAdded', - 'VersionChanged' + 'VersionChanged', 'Required Solidus Version' ] config = config.for_cop(cop) safe_auto_correct = config.fetch('SafeAutoCorrect', true) @@ -56,12 +56,18 @@ task generate_cops_documentation: :yard_for_generate_documentation do else 'No' end + minimum_solidus_version = if cop.respond_to?(:required_minimum_solidus_version) + cop.required_minimum_solidus_version + else + '-' + end content = [[ config.fetch('Enabled') ? 'Enabled' : 'Disabled', config.fetch('Safe', true) ? 'Yes' : 'No', autocorrect, config.fetch('VersionAdded', '-'), - config.fetch('VersionChanged', '-') + config.fetch('VersionChanged', '-'), + minimum_solidus_version ]] "#{to_table(header, content)}\n" end From be96bfe95098fb3fa52f4c145b5b21c528dd224a Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 11:49:01 +0200 Subject: [PATCH 04/12] Add documentation section to the README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 0804436..4d19685 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,10 @@ require: After this simply use the `rubocop` command to start linting. +## Documentation + +You can read about each cop supplied by RuboCop Solidus in [the docs](docs/cops.md). + ## Creating new cops To create a new cop, run the following command: From cf3f798cc605517671c78fca4680465d6373edf5 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 12:11:41 +0200 Subject: [PATCH 05/12] Add documentation uri to gemspec In this way a documentation link will be shown in the Rubygems page. --- rubocop-solidus.gemspec | 1 + 1 file changed, 1 insertion(+) diff --git a/rubocop-solidus.gemspec b/rubocop-solidus.gemspec index 15fc4cb..dcf9393 100644 --- a/rubocop-solidus.gemspec +++ b/rubocop-solidus.gemspec @@ -20,6 +20,7 @@ Gem::Specification.new do |spec| spec.metadata['homepage_uri'] = spec.homepage spec.metadata['source_code_uri'] = 'https://www.github.com/solidusio/rubocop-solidus' spec.metadata['changelog_uri'] = 'https://www.github.com/solidusio/rubocop-solidus' + spec.metadata['documentation_uri'] = 'https://www.github.com/solidusio/rubocop-solidus/blob/master/docs/cops.md' # Specify which files should be added to the gem when it is released. # The `git ls-files -z` loads the files in the RubyGem that have been added into git. From dca064c847ab52addf68a3380d6962741907df0b Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 12:05:22 +0200 Subject: [PATCH 06/12] Add changelog entry --- .../new_create_automatic_docs_based_on_cops_descriptions.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/new_create_automatic_docs_based_on_cops_descriptions.md diff --git a/changelog/new_create_automatic_docs_based_on_cops_descriptions.md b/changelog/new_create_automatic_docs_based_on_cops_descriptions.md new file mode 100644 index 0000000..b3b4bee --- /dev/null +++ b/changelog/new_create_automatic_docs_based_on_cops_descriptions.md @@ -0,0 +1 @@ +* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][]) From 153f33654982141e406ac6b5a275396b81c181e1 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Thu, 3 Aug 2023 17:32:36 +0200 Subject: [PATCH 07/12] Fix wrong changelog uri in gemspec After adding the documentation uri to the gemspec we found a typo in the changelog uri too, so this commit fixes the typo. --- rubocop-solidus.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rubocop-solidus.gemspec b/rubocop-solidus.gemspec index dcf9393..de8cbe7 100644 --- a/rubocop-solidus.gemspec +++ b/rubocop-solidus.gemspec @@ -19,7 +19,7 @@ Gem::Specification.new do |spec| spec.metadata['homepage_uri'] = spec.homepage spec.metadata['source_code_uri'] = 'https://www.github.com/solidusio/rubocop-solidus' - spec.metadata['changelog_uri'] = 'https://www.github.com/solidusio/rubocop-solidus' + spec.metadata['changelog_uri'] = 'https://www.github.com/solidusio/rubocop-solidus/blob/master/CHANGELOG.md' spec.metadata['documentation_uri'] = 'https://www.github.com/solidusio/rubocop-solidus/blob/master/docs/cops.md' # Specify which files should be added to the gem when it is released. From 12cab6c0c04a8257bd52669d0eacd0103b0fcd08 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Fri, 28 Jul 2023 18:35:33 +0200 Subject: [PATCH 08/12] Remove rubocop extensions suggestions When we run rubocop, it will raise a tip regaring suggested exentions. Those extensions are not useful for us, so we disabled the tip. Result after running rubocop: Tip: Based on detected gems, the following RuboCop extension libraries might be helpful: * rubocop-rake (https://rubygems.org/gems/rubocop-rake) * rubocop-rspec (https://rubygems.org/gems/rubocop-rspec) You can opt out of this message by adding the following to your config (see https://docs.rubocop.org/rubocop/extensions.html#extension-suggestions for more options): AllCops: SuggestExtensions: false --- .rubocop.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.rubocop.yml b/.rubocop.yml index e625cef..b2fbef9 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -2,6 +2,7 @@ inherit_from: .rubocop_todo.yml AllCops: NewCops: enable + SuggestExtensions: false Naming/FileName: Exclude: From 958e493c7b8c8632ad118e07aae26245068fb199 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Fri, 28 Jul 2023 18:49:43 +0200 Subject: [PATCH 09/12] Improve CI GH action This commit contains some improvements for the CI: - Renamed from `Tests` to `CI` because it doesn't run only tests. - Removed `bundle install` step because it's already done in `Setup`. - Created single steps for each rake task. Especially the last point is useful because by separating the step/task, we can easily find and fix which task is failing (if any) and fix it. --- .github/workflows/{main.yml => ci.yml} | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) rename .github/workflows/{main.yml => ci.yml} (61%) diff --git a/.github/workflows/main.yml b/.github/workflows/ci.yml similarity index 61% rename from .github/workflows/main.yml rename to .github/workflows/ci.yml index 8638b27..694c454 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: Tests +name: CI on: push: @@ -23,9 +23,11 @@ jobs: with: ruby-version: ${{ matrix.ruby }} bundler-cache: true - - name: Install dependencies - run: | - gem install bundler - bundle install --jobs 4 --retry 3 - - name: Run the default task - run: bundle exec rake + - name: Lint files + run: bundle exec rake rubocop + - name: Run tests + run: bundle exec rake spec + - name: Verify documentation is up to date + run: bundle exec rake generate_cops_documentation + env: + CI: true From bdce2ffaa8ba41dbe2fea022b44295cbbcaa3ffd Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Tue, 1 Aug 2023 11:50:00 +0200 Subject: [PATCH 10/12] Improve README readability This commit contains an improvement on the README readability. Previously, all sections of the README had the same importance. Now we created 4 main sections (Getting started, Documentation, Contributing and License) and moved all other sub-sections under the right top-level section. --- README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4d19685..1b4aa4f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ Automatic Solidus code style checking tool. A RuboCop extension focused on enforcing Solidus best practices and coding conventions. -## Installation +## Getting started + +### Installation Add this line to your application's Gemfile: @@ -19,7 +21,7 @@ Or install it yourself as: $ gem install rubocop-solidus -## Usage +### Usage To Start using this extension in your application add the following lines to your `.rubocop.yml` file @@ -34,7 +36,13 @@ After this simply use the `rubocop` command to start linting. You can read about each cop supplied by RuboCop Solidus in [the docs](docs/cops.md). -## Creating new cops +## Contributing + +Bug reports and pull requests are welcome on GitHub at https://github.com/solidusio/rubocop-solidus. + +To contribute a new cop, please see the sections below. + +### Creating new cops To create a new cop, run the following command: @@ -44,7 +52,7 @@ $ bundle exec rake 'new_cop[Solidus/NameOfTheCop]' and then follow the instructions on the screen. -## Creating changelog entries +### Creating changelog entries Changelog entries are just files under the `changelog/` folder that will be merged into `CHANGELOG.md` at release time. You can create new changelog entries like this: @@ -55,7 +63,7 @@ $ bundle exec rake changelog:new|fix|change The type of the changelog correspond to "new feature", "bug-fix" and "changed" entries in the changelog. -### Changelog entry format +#### Changelog entry format Here are a few examples: @@ -72,7 +80,7 @@ Here are a few examples: * If this is a breaking change, mark it with `**(Breaking)**`. * At the end of the entry, add an implicit link to your GitHub user page as `([@username][])`. -## Release a new version +### Release a new version To release a new version, run the following command: @@ -93,10 +101,6 @@ To deploy the new version to RubyGems, run the following command: $ bundle exec rake release ``` -## Contributing - -Bug reports and pull requests are welcome on GitHub at https://github.com/solidusio/rubocop-solidus. - ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). From ba863d61831cd6e9de937b62d04be48d046032b4 Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Fri, 4 Aug 2023 15:15:48 +0200 Subject: [PATCH 11/12] Update Changelog --- CHANGELOG.md | 4 ++++ .../new_create_automatic_docs_based_on_cops_descriptions.md | 1 - 2 files changed, 4 insertions(+), 1 deletion(-) delete mode 100644 changelog/new_create_automatic_docs_based_on_cops_descriptions.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 36743fc..7cc350b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ ## master (unreleased) +### New features + +* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][]) + ## 0.1.3 (2023-07-28) ### New features diff --git a/changelog/new_create_automatic_docs_based_on_cops_descriptions.md b/changelog/new_create_automatic_docs_based_on_cops_descriptions.md deleted file mode 100644 index b3b4bee..0000000 --- a/changelog/new_create_automatic_docs_based_on_cops_descriptions.md +++ /dev/null @@ -1 +0,0 @@ -* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][]) From 55a9f17fab9c45c23b567d567efdb8335154732d Mon Sep 17 00:00:00 2001 From: Massimiliano Lattanzio Date: Fri, 4 Aug 2023 15:16:53 +0200 Subject: [PATCH 12/12] Release new version --- CHANGELOG.md | 2 ++ Gemfile.lock | 2 +- lib/rubocop/solidus/version.rb | 2 +- relnotes/v0.1.4.md | 5 +++++ 4 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 relnotes/v0.1.4.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7cc350b..b7dff02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ ## master (unreleased) +## 0.1.4 (2023-08-04) + ### New features * [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][]) diff --git a/Gemfile.lock b/Gemfile.lock index edb7076..e328b4e 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - rubocop-solidus (0.1.3) + rubocop-solidus (0.1.4) rubocop GEM diff --git a/lib/rubocop/solidus/version.rb b/lib/rubocop/solidus/version.rb index 99dfcc2..c9930a9 100644 --- a/lib/rubocop/solidus/version.rb +++ b/lib/rubocop/solidus/version.rb @@ -2,6 +2,6 @@ module RuboCop module Solidus - VERSION = '0.1.3' + VERSION = '0.1.4' end end diff --git a/relnotes/v0.1.4.md b/relnotes/v0.1.4.md new file mode 100644 index 0000000..0db93d8 --- /dev/null +++ b/relnotes/v0.1.4.md @@ -0,0 +1,5 @@ +### New features + +* [#51](https://github.com/solidusio/rubocop-solidus/pull/51): Create automatic documentation based on the cop's descriptions. ([@MassimilianoLattanzio][]) + +[@MassimilianoLattanzio]: https://github.com/MassimilianoLattanzio