RSpec 4 plan

[pirj]

It's been in the air and mostly in sparse @JonRowe's comments (1, 2). This is an attempt to gather the ideas and start the discussion.

Release step-by-step plan

pre-4.0:

• [x] fix internal deprecation matchers https://github.com/rspec/rspec-support/issues/451
• [x] add deprecations for what we end up removing in 4.0
• • [x] implicit block syntax (https://github.com/rspec/rspec-expectations/pull/1139, https://github.com/rspec/rspec-core/pull/2800)
• • [x] https://github.com/rspec/rspec-core/pull/2880
• • should (monkey and non-monkey), syntax config options
• • globally-exposed DSL, and its config option
• • shared_context_metadata_behavior (discussion in https://github.com/rspec/rspec-core/issues/2832)
• • run_all_when_everything_filtered
• • ... a couple others
• • [x] https://github.com/rspec/rspec-mocks/pull/1418
• • should Mocks syntax
• • allow_message_expectations_on_nil example method
• • [x] https://github.com/rspec/rspec-expectations/pull/1301
• • operator matching (is_expected.to be is a replacement for should, not just is_expected.to)
• • legacy matcher support
• • include_chain_clauses_in_custom_matcher_descriptions
• • present tense predicates
• • ~[ ] deprecate currently_executing_a_context_hook and recommend using current_scope instead (https://github.com/rspec/rspec-core/pull/2895)~
• • ~[ ] ? AnyInstance~
• • ~[ ] ? DRb~

4.0.0:

• [x] Drop support for ~EOL~ Ruby versions 1.8.7 - 2.2 (https://github.com/rspec/rspec-core/pull/2787 https://github.com/rspec/rspec-support/pull/436 https://github.com/rspec/rspec-mocks/pull/1349 https://github.com/rspec/rspec-expectations/pull/1231)
• [x] remove monkey-patching (globally exposed DSL and .should) (https://github.com/rspec/rspec-core/pull/2803 et al., all interlinked)
• [x] Remove deprecated features
• • [x] implicit block expectation syntax (https://github.com/rspec/rspec-expectations/pull/1285)
• • [x] run_all_when_everything_filtered (https://github.com/rspec/rspec-core/pull/2845)
• • [x] shared_context_metadata_behavior (https://github.com/rspec/rspec-core/pull/2834)
• • [x] include_chain_clauses_in_custom_matcher_descriptions (https://github.com/rspec/rspec-expectations/pull/1279)
• • [x] legacy matcher support (https://github.com/rspec/rspec-expectations/pull/1253)
• • [x] raise where we previously warned (https://github.com/rspec/rspec-core/pull/2849)
• • [x] present-tense dynamic predicates (https://github.com/rspec/rspec-expectations/pull/1286)
• • [x] Remove deprecated :example_group example metadata sub-hash (https://github.com/rspec/rspec-core/pull/2851)
• • [x] Remove deprecated Hash-like behavior from example execution result (https://github.com/rspec/rspec-core/pull/2862)
• • [x] Various Core deprecations (https://github.com/rspec/rspec-core/pull/2864)
• • [x] Remove deprecated allow_message_expectations_on_nil example method (https://github.com/rspec/rspec-mocks/pull/1410)
• • [x] Remove match_regex matcher and StartAndEndWith matcher base class from Expectations (https://github.com/rspec/rspec-expectations/pull/1288)
• • ~[ ] Remove currently_executing_a_context_hook? (https://github.com/rspec/rspec-core/pull/2911)~
• [x] set new defaults
• • [x] strict_predicate_matchers (https://github.com/rspec/rspec-expectations/pull/1277)
• • [x] verify_partial_doubles = true (https://github.com/rspec/rspec-mocks/pull/1409)
• ~[ ] Remove DRb runner (https://github.com/rspec/rspec-core/pull/2866)~
• [ ] extensively test (our current projects, repos from https://github.com/pirj/real-world-rspec)
• [x] unify multi-condition filtering (ticket https://github.com/rspec/rspec-core/issues/1821)
• [x] add a warning when doc string is not a string (https://github.com/rspec/rspec-core/pull/2922)

post-4.0

• [ ] update RubyGems [new gem generator [1, 2]
• [ ] update rspec-rails/rspec-collection_matchers/rspec-its to support RSpec 4
• [ ] extract monkey-patching .should to a gem
• [ ] kwargs delegation
• [?] update transpec to facilitate migration from 3.x to 4.x (describe - > RSpec.describe?)
• [ ] Cleanup: CI scripts
• [ ] --no-document for gem
• [ ] unindent/dedent -> <<~
• [ ] rearrange gemfile/gemspec (runtime dependencies to gemspec, development - to gemfiles)
• [ ] figure out why rubocop passes while there are offences in lib (core, probably others too)
• [ ] set TargetRubyVersion for RuboCop, and bump to latest (that supports parsing 2.4, which even the edge should)
• [ ] tighten and improve minimum_coverage
• [ ] update rake, cucumber, aruba to latest versions (cucumber to 4.1 because 5.x depends on Ruby 2.5+, or even 3.x because of diff-lcs)

Ruby support

EOL Ruby means we support 2.5+, since 2.4 is EOL in April 2020 However, according to 2020 RoR community survey

70% use 2.5+ 81% use 2.4+ 89% use 2.3+

Do 2.3 and 2.4 cause any trouble? I could only find this:

        # 2.4 has improved BigDecimal formatting so we do not need
        # to provide our own.
        # https://github.com/ruby/bigdecimal/pull/42
        classes.delete(BigDecimalInspector) if RUBY_VERSION >= '2.4'

I can only think of RuboCop's TargetRubyVersion setting that has a minimum of 2.4. That means we won't be able to run rubocop on 2.3 CI build.

More on this in https://github.com/rspec/rspec/issues/25

Remove deprecated features/Introduce new defaults

• [x] shared_context_metadata_behavior
• [x] monkey-patching mode
• [x] should syntax (with implicit receiver only, where should can be backed by is_expected.to. extract to a gem?)
• [x] implicit block syntax (deprecated in https://github.com/rspec/rspec-expectations/pull/1139)

Consider deprecating long-hanging/obscure features

• ~[ ] DRb runner. I only know of Spork that was using it, but its 2.0.0-rc is years old now with no signs of life~

Cleanup

• [ ] rspec-core: "Ruby 1.9 has a bug that can lead to infinite recursion and a" Drafted in commits: ce2f4a0b 123e6ee7 https://github.com/rspec/rspec-core/pull/2787#pullrequestreview-540200286

  RSpec::Matchers.define(:be_one) do
    match { |actual| actual == 1 }
  end
  RSpec.describe do
    alias_method :b, :be_one
    it { expect(1).to be_one }
  end
  

• [ ] for all repos

  • [ ] bump cucumber to ~> 5.2.0, cucumber-ruby (undefined method with_filtered_backtrace') + fix deprec titletoname`
    • 1.3-2.0 don't work for me locally with a weird error: undefined method []' for nil:NilClass (NoMethodError) /Users/pirj/.rvm/gems/ruby-2.7.1@rspec-core/gems/cucumber-1.3.20/lib/cucumber/core_ext/proc.rb:17:in file_colon_line'
    • 2.4.0 spits "undefined method `with_filtered_backtrace'"
    • 3.2.0 - "undefined method 'ok?'"
    • 4.1 depends on diff-lcs (< 1.4, >= 1.3, ~> 1.3), while we depend on = 1.4.4
    • 5.2.0 Found tags option '~@wip'. '~@tag' is no longer supported, use 'not @tag' instead
  • [x] update diff-lcs ">= 1.4.4" (https://github.com/rspec/rspec-support/pull/477 and co)
  • [ ] update rake to latest
  • [ ] skip documentation yes | gem update --system --no-document yes | gem install bundler --no-document also on sub-builds?
  • [ ] rearrange Gemfile/gemspec e.g. core: simplecov, test-unit, aruba, rake To my best knowledge, add_development_dependency only affects local bundling. I've moved it over from the Gemfile. As far as I understand we can shuffle those dependencies between add_development_dependency and Gemfile without affecting anything. To me, it's better to keep those gems that we directly depend on here, while reserving the Gemfile to add version constraints for third-party dependencies like ffi and those that require a conditional, e.g. if RUBY_VERSION >= '2.4'
  • [ ] figure out why rubocop lib passes on core frozen string literal - run with --only Style/FrozenStringLiteralComment, why it doesn't detect offences without --only? lib/rspec/core/backport_random.rb excluded
  • [ ] <<- chomp gsub unindent dedent -> <<~
    • [ ] remove write_file_formatted in rspec-core

kwargs delegation

• 💚 https://github.com/rspec/rspec-expectations/issues/1221#issuecomment-716133588
• ⚠️ https://github.com/rspec/rspec-expectations/issues/1241#issuecomment-743437255
• https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/#a-compatible-delegation
• https://eregon.me/blog/2019/11/10/the-delegation-challenge-of-ruby27.html
• https://github.com/rspec/rspec-expectations/pull/1222/files#r513326762
• https://github.com/rspec/rspec-core/issues/2674
• https://github.com/rspec/rspec-core/pull/2716/files
• https://github.com/rspec/rspec-expectations/commit/964196a39e2ba2228add4c9c3b4f8982cb433f44