Deprecate usage of built-in cucumber wire protocol (#1564)

* Deprecate usage of built-in cucumber wire protocol

* Update CHANGELOG

* Make it work with future version of cucumber-ruby-wire

* Add an UPGRADING.md document

* Add a registry wrapper to avoid exposing RegistryAndMore

* Add a new InstallPlugin hook

That prevent changing the AfterConfiguration hook and allows to have a
dedicated hook for external plugins.

Author: aurelien-reeves

CHANGELOG.md

@@ -14,6 +14,21 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 
 ### Added
 
+- New hook: `InstallPlugin`
+
+  It is intended to be used to install an external plugin, like cucumber-ruby-wire.
+
+  It is fired just after the `AfterConfiguration` one. Two parameters are given:
+  the same `configuration` instance that is given to `AfterConfiguration`,
+  and a [`registry_wrapper`](./lib/cucumber/glue/registry_wrapper.rb) which allows
+  plugins to have access to specific internal methods.
+
+  See [cucumber-ruby-wire](https://github.com/cucumber/cucumber-ruby-wire/) for a
+  usage example.
+
+  ([1564](https://github.com/cucumber/cucumber-ruby/pull/1564)
+   [aurelien-reeves](https://github.com/aurelien-reeves))
+
 ### Fixed
 
 ### Changed
@@ -22,6 +37,18 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 
 ### Security fixes
 
+### Deprecated
+
+- The built-in Wire protocol
+
+  The Wire protocol is still officially supported, but as an optional plugin rather
+  than a built-in feature. See the
+  [UPGRADING.md](./UPGRADING.md#upgrading-to-710)
+  to update your code accordingly.
+
+  ([1564](https://github.com/cucumber/cucumber-ruby/pull/1564)
+   [aurelien-reeves](https://github.com/aurelien-reeves))
+
 ## [7.0.0](https://github.com/cucumber/cucumber-ruby/compare/v6.1.0...v7.0.0)
 
 ### Fixed

UPGRADING.md

@@ -0,0 +1,46 @@
+# Upgrading to 7.1.0
+
+## The wire protocol
+
+Usage of built-in wire protocol with `cucumber-ruby` will be deprecated in cucumber
+7.1.0, and removed in cucumber 8.0.0.
+
+The wire protocol will still be available by explicitely using the `cucumber-wire`
+gem.
+
+### Before cucumber 7.1.0
+
+Before cucumber 7.1.0, the wire protocol was automatically installed with cucumber,
+and automatically activated when it had detected a `.wire` file.
+
+### With cucumber 7.1.0
+
+The wire protocol will work as before, but you will notice a deprecation message.
+
+To prevent the deprecation message to be shown, add the gem `cucumber-wire` to your
+Gemfile alongside the `cucumber` one, and install it:
+
+```ruby
+# Gemfile
+
+# ...
+
+gem "cucumber"
+gem "cucumber-wire"
+
+# ...
+
+```
+```shell
+bundle install
+```
+
+And add `require 'cucumber/wire'` in your support code. If you do not have support
+code yet, create a new one. For example `features/support/wire.rb`.
+
+```ruby
+# features/support/wire.rb
+require 'cucumber/wire'
+```
+
+The wire protocol will be installed, and no deprecation message will be shown anymore.

lib/cucumber/glue/dsl.rb

@@ -113,6 +113,11 @@ def AfterConfiguration(&proc)
         Dsl.register_rb_hook('after_configuration', [], proc)
       end
 
+      # Registers a proc that will run after Cucumber is configured in order to install an external plugin.
+      def InstallPlugin(&proc)
+        Dsl.register_rb_hook('install_plugin', [], proc)
+      end
+
       # Registers a new Ruby StepDefinition. This method is aliased
       # to <tt>Given</tt>, <tt>When</tt> and <tt>Then</tt>, and
       # also to the i18n translations whenever a feature of a

lib/cucumber/glue/registry_and_more.rb

@@ -140,6 +140,12 @@ def after_configuration(configuration)
         end
       end
 
+      def install_plugin(configuration, registry)
+        hooks[:install_plugin].each do |hook|
+          hook.invoke('InstallPlugin', [configuration, registry])
+        end
+      end
+
       def add_hook(phase, hook)
         hooks[phase.to_sym] << hook
         hook

lib/cucumber/glue/registry_wrapper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Cucumber
+  module Glue
+    ##
+    # This class wraps some internals methods to expose them to external plugins.
+    class RegistryWrapper
+      def initialize(registry)
+        @registry = registry
+      end
+
+      ##
+      # Creates a new CucumberExpression from the given +string_or_regexp+.
+      #
+      # If +string_or_regexp+ is a string, it will return a new CucumberExpression::CucumberExpression
+      #
+      # If +string_or_regexp+ is a regexp, it will return a new CucumberExpressions::RegularExpression
+      #
+      # An ArgumentError is raised if +string_or_regexp+ is not a string or a regexp
+      def create_expression(string_or_regexp)
+        @registry.create_expression(string_or_regexp)
+      end
+
+      ##
+      # Return the current execution environment - AKA an isntance of World
+      def current_world
+        @registry.current_world
+      end
+    end
+  end
+end

lib/cucumber/runtime.rb

@@ -3,12 +3,14 @@
 require 'fileutils'
 require 'cucumber/configuration'
 require 'cucumber/create_meta'
+require 'cucumber/deprecate'
 require 'cucumber/load_path'
 require 'cucumber/formatter/duration'
 require 'cucumber/file_specs'
 require 'cucumber/filters'
 require 'cucumber/formatter/fanout'
 require 'cucumber/gherkin/i18n'
+require 'cucumber/glue/registry_wrapper'
 require 'cucumber/step_match_search'
 require 'cucumber/messages'
 require 'sys/uname'
@@ -70,8 +72,9 @@ def run!
       )
 
       load_step_definitions
-      install_wire_plugin
       fire_after_configuration_hook
+      fire_install_plugin_hook
+      install_wire_plugin
       # TODO: can we remove this state?
       self.visitor = report
 
@@ -112,6 +115,10 @@ def fire_after_configuration_hook #:nodoc:
       @support_code.fire_hook(:after_configuration, @configuration)
     end
 
+    def fire_install_plugin_hook #:nodoc:
+      @support_code.fire_hook(:install_plugin, @configuration, registry_wrapper)
+    end
+
     require 'cucumber/core/gherkin/document'
     def features
       @features ||= feature_files.map do |path|
@@ -261,7 +268,19 @@ def load_step_definitions
     end
 
     def install_wire_plugin
-      Cucumber::Wire::Plugin.new(@configuration, @support_code.registry).install if @configuration.all_files_to_load.any? { |f| f =~ /\.wire$/ }
+      return if Cucumber::Wire::Plugin.installed?
+      return unless @configuration.all_files_to_load.any? { |f| f =~ /\.wire$/ }
+
+      Cucumber::Wire::Plugin.new(@configuration, registry_wrapper).install
+      Cucumber.deprecate(
+        'See https://github.com/cucumber/cucumber-ruby/blob/main/UPGRADING.md#upgrading-to-710 for more info',
+        ' built-in usage of the wire protocol',
+        '8.0.0'
+      )
+    end
+
+    def registry_wrapper
+      Cucumber::Glue::RegistryWrapper.new(@support_code.registry)
     end
 
     def log

spec/cucumber/runtime_spec.rb

@@ -20,5 +20,26 @@ module Cucumber
         expect(subject.doc_string('Text')).to eq 'Text'
       end
     end
+
+    describe '#install_wire_plugin' do
+      it 'informs the user it is deprecated' do
+        stub_const('Cucumber::Deprecate::STRATEGY', Cucumber::Deprecate::ForUsers)
+        allow(STDERR).to receive(:puts)
+        allow_any_instance_of(Configuration).to receive(:all_files_to_load).and_return(['file.wire'])
+
+        begin
+          subject.run!
+        rescue NoMethodError
+          # this is actually expected
+        end
+
+        expect(STDERR).to have_received(:puts).with(
+          a_string_including([
+            'WARNING: # built-in usage of the wire protocol is deprecated and will be removed after version 8.0.0.',
+            'See https://github.com/cucumber/cucumber-ruby/blob/main/UPGRADING.md#upgrading-to-710 for more info.'
+          ].join(' '))
+        )
+      end
+    end
   end
 end