Change deprecations to be removed in RubySaml 3.0.0, for SemVer reasons

johnnyshields · johnnyshields · commit 591bdaa5f226 · 2025-03-20T16:46:12.000+09:00
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -1,6 +1,6 @@
 # Ruby SAML Migration Guide
 
-## Updating from 1.x to 2.0.0
+## Upgrading from 1.x to 2.0.0
 
 **IMPORTANT: Please read this section carefully as it contains breaking changes!**
 
@@ -34,7 +34,7 @@ Note that the project folder structure has also been updated accordingly. Notabl
 `lib/onelogin/schemas` is now `lib/ruby_saml/schemas`.
 
 For backward compatibility, the alias `OneLogin = Object` has been set, so `OneLogin::RubySaml::` will still work
-as before. This alias will be removed in RubySaml version `2.1.0`.
+as before. This alias will be removed in RubySaml version `3.0.0`.
 
 ### Deprecation and removal of "XMLSecurity" namespace
 
@@ -101,7 +101,7 @@ end
 
 RubySaml now always uses double quotes for attribute values when generating XML.
 The `settings.double_quote_xml_attribute_values` parameter now always behaves as `true`,
-and will be removed in RubySaml 2.1.0.
+and will be removed in RubySaml 3.0.0.
 
 The reasons for this change are:
 - RubySaml will use Nokogiri instead of REXML to generate XML. Nokogiri does not support
@@ -154,7 +154,7 @@ a different `sp_uuid_prefix` is passed-in on subsequent calls.
 ### Deprecation of compression settings
 
 The `settings.compress_request` and `settings.compress_response` parameters have been deprecated
-and are no longer functional. They will be removed in RubySaml 2.1.0. Please remove `compress_request`
+and are no longer functional. They will be removed in RubySaml 3.0.0. Please remove `compress_request`
 and `compress_response` everywhere within your project code.
 
 The SAML SP request/response message compression behavior is now controlled automatically by the
@@ -166,13 +166,15 @@ compression may be achieved by enabling `Content-Encoding: gzip` on your webserv
 ### Deprecation of IdP certificate fingerprint settings
 
 The `settings.idp_cert_fingerprint` and `settings.idp_cert_fingerprint_algorithm` are deprecated
-and will be removed in RubySaml 2.1.0. Please use `settings.idp_cert` or `settings.idp_cert_multi` instead.
-The reasons for this deprecation are that (1) fingerprint cannot be used with HTTP-Redirect binding,
-and (2) fingerprint is theoretically susceptible to collision attacks.
+and will be removed in RubySaml 3.0.0. Please use `settings.idp_cert` or `settings.idp_cert_multi` instead.
+
+The reasons for this deprecation are:
+- Fingerprint cannot be used with HTTP-Redirect binding
+- Fingerprint is theoretically susceptible to collision attacks.
 
 ### Other settings deprecations
 
-The following parameters in `RubySaml::Settings` are deprecated and will be removed in RubySaml 2.1.0:
+The following parameters in `RubySaml::Settings` are deprecated and will be removed in RubySaml 3.0.0:
 
 - `#issuer` is deprecated and replaced 1:1 by `#sp_entity_id`
 - `#idp_sso_target_url` is deprecated and replaced 1:1 by `#idp_sso_service_url`
@@ -212,7 +214,7 @@ and `#format_private_key` methods. Specifically:
   stripped out.
 - Case 7: If no valid certificates are found, the entire original string will be returned.
 
-## Updating from 1.17.x to 1.18.0
+## Upgrading from 1.17.x to 1.18.0
 
 Version `1.18.0` changes the way the toolkit validates SAML signatures. There is a new order
 how validation happens in the toolkit and also the toolkit by default will check malformed doc
@@ -222,7 +224,7 @@ The SignedDocument class defined at xml_security.rb experienced several changes.
 We don't expect compatibilty issues if you use the main methods offered by ruby-saml, but if
 you use a fork or customized usage, is possible that you need to adapt your code.
 
-## Updating from 1.12.x to 1.13.0
+## Upgrading from 1.12.x to 1.13.0
 
 Version `1.13.0` adds `settings.idp_sso_service_binding` and `settings.idp_slo_service_binding`, and
 deprecates `settings.security[:embed_sign]`. If specified, new binding parameters will be used in place of `:embed_sign`
diff --git a/lib/ruby_saml.rb b/lib/ruby_saml.rb
@@ -20,5 +20,5 @@
 require 'ruby_saml/utils'
 require 'ruby_saml/version'
 
-# @deprecated This alias adds compatibility with v1.x and will be removed in v2.1.0
+# @deprecated This alias adds compatibility with v1.x and will be removed in v3.0.0
 OneLogin = Object
diff --git a/lib/ruby_saml/settings.rb b/lib/ruby_saml/settings.rb
@@ -248,13 +248,13 @@ def get_binding(value)
     {
       double_quote_xml_attribute_values: true
     }.each do |old_param, new_value|
-      # @deprecated Will be removed in v2.1.0
+      # @deprecated Will be removed in v3.0.0
       define_method(old_param) do
         removed_deprecation(old_param, new_value)
         new_value
       end
 
-      # @deprecated Will be removed in v2.1.0
+      # @deprecated Will be removed in v3.0.0
       define_method(:"#{old_param}=") do |_|
         removed_deprecation(old_param, new_value)
         new_value
@@ -268,13 +268,13 @@ def get_binding(value)
       assertion_consumer_logout_service_url: :single_logout_service_url,
       assertion_consumer_logout_service_binding: :single_logout_service_binding
     }.each do |old_param, new_param|
-      # @deprecated Will be removed in v2.1.0
+      # @deprecated Will be removed in v3.0.0
       define_method(old_param) do
         replaced_deprecation(old_param, new_param)
         send(new_param)
       end
 
-      # @deprecated Will be removed in v2.1.0
+      # @deprecated Will be removed in v3.0.0
       define_method(:"#{old_param}=") do |value|
         replaced_deprecation(old_param, new_param)
         send(:"#{new_param}=", value)
@@ -318,86 +318,86 @@ def get_sp_digest_method
       end
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def idp_cert_fingerprint=(value)
       idp_cert_fingerprint_deprecation
       @idp_cert_fingerprint = value
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def idp_cert_fingerprint_algorithm=(value)
       idp_cert_fingerprint_deprecation
       @idp_cert_fingerprint_algorithm = value
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def certificate_new
       certificate_new_deprecation
       @certificate_new
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def certificate_new=(value)
       certificate_new_deprecation
       @certificate_new = value
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def compress_request
       compress_deprecation('compress_request', 'idp_sso_service_binding')
       defined?(@compress_request) ? @compress_request : true
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def compress_request=(value)
       compress_deprecation('compress_request', 'idp_sso_service_binding')
       @compress_request = value
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def compress_response
       compress_deprecation('compress_response', 'idp_slo_service_binding')
       defined?(@compress_response) ? @compress_response : true
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def compress_response=(value)
       compress_deprecation('compress_response', 'idp_slo_service_binding')
       @compress_response = value
     end
 
     private
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def removed_deprecation(old_param, new_value)
-      Logging.deprecate "`RubySaml::Settings##{old_param}` is deprecated and will be removed in RubySaml 2.1.0. " \
+      Logging.deprecate "`RubySaml::Settings##{old_param}` is deprecated and will be removed in RubySaml 3.0.0. " \
                         "It no longer has any effect, and will behave as if always set to #{new_value.inspect}."
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def replaced_deprecation(old_param, new_param)
-      Logging.deprecate "`RubySaml::Settings##{old_param}` is deprecated and will be removed in RubySaml 2.1.0. " \
+      Logging.deprecate "`RubySaml::Settings##{old_param}` is deprecated and will be removed in RubySaml 3.0.0. " \
                         "Please set the same value to `RubySaml::Settings##{new_param}` instead."
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def idp_cert_fingerprint_deprecation
       Logging.deprecate '`RubySaml::Settings#idp_cert_fingerprint` and `#idp_cert_fingerprint_algorithm` are ' \
-                        'deprecated and will be removed in RubySaml v2.1.0. Please provide the full IdP certificate in ' \
+                        'deprecated and will be removed in RubySaml v3.0.0. Please provide the full IdP certificate in ' \
                         '`RubySaml::Settings#idp_cert` instead.'
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def certificate_new_deprecation
-      Logging.deprecate '`RubySaml::Settings#certificate_new` is deprecated and will be removed in RubySaml v2.1.0. ' \
+      Logging.deprecate '`RubySaml::Settings#certificate_new` is deprecated and will be removed in RubySaml v3.0.0. ' \
                         'Please set `RubySaml::Settings#sp_cert_multi` instead. ' \
                         'Please refer to documentation as `sp_cert_multi` has a different value type.'
     end
 
-    # @deprecated Will be removed in v2.1.0
+    # @deprecated Will be removed in v3.0.0
     def compress_deprecation(old_param, new_param)
       Logging.deprecate "`RubySaml::Settings##{old_param}` is deprecated and no longer functional. " \
-                        'It will be removed in RubySaml 2.1.0. ' \
+                        'It will be removed in RubySaml 3.0.0. ' \
                         "Its functionality is now handled by `RubySaml::Settings##{new_param}` instead: " \
                         '"HTTP-Redirect" will always be compressed, and "HTTP-POST" will always be uncompressed.'
     end
diff --git a/lib/ruby_saml/xml/deprecated.rb b/lib/ruby_saml/xml/deprecated.rb
@@ -7,30 +7,30 @@
   REXML::Security.entity_expansion_limit = 0
 
   module XMLSecurity
-    # @deprecated Will be removed in v2.1.0.
+    # @deprecated Will be removed in v3.0.0.
     # @api private
     class BaseDocument < REXML::Document
       # @deprecated Constants
       C14N = RubySaml::XML::C14N
       DSIG = RubySaml::XML::DSIG
       NOKOGIRI_OPTIONS = RubySaml::XML::NOKOGIRI_OPTIONS
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def canon_algorithm(algorithm)
-        RubySaml::Logging.deprecate 'XMLSecurity::BaseDocument#canon_algorithm is deprecated and will be removed in v2.1.0. ' \
+        RubySaml::Logging.deprecate 'XMLSecurity::BaseDocument#canon_algorithm is deprecated and will be removed in v3.0.0. ' \
                                     'Use RubySaml::XML.canon_algorithm instead.'
         RubySaml::XML.canon_algorithm(algorithm)
       end
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def algorithm(algorithm)
-        RubySaml::Logging.deprecate 'XMLSecurity::BaseDocument#algorithm is deprecated and will be removed in v2.1.0. ' \
+        RubySaml::Logging.deprecate 'XMLSecurity::BaseDocument#algorithm is deprecated and will be removed in v3.0.0. ' \
                                     'Use RubySaml::XML.hash_algorithm instead.'
         RubySaml::XML.hash_algorithm(algorithm)
       end
     end
 
-    # @deprecated Will be removed in v2.1.0.
+    # @deprecated Will be removed in v3.0.0.
     # @api private
     class Document < BaseDocument
       # @deprecated Constants
@@ -54,39 +54,39 @@ class Document < BaseDocument
       SHA512        = RubySaml::XML::SHA512
       ENVELOPED_SIG = RubySaml::XML::ENVELOPED_SIG
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def initialize(*args, **_kwargs)
-        RubySaml::Logging.deprecate 'XMLSecurity::Document is deprecated and will be removed in v2.1.0. ' \
+        RubySaml::Logging.deprecate 'XMLSecurity::Document is deprecated and will be removed in v3.0.0. ' \
                                     'Use RubySaml::XML::DocumentSigner.sign_document instead.'
         super(args[0])
       end
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def sign_document(*_args, **_kwargs)
         msg = 'XMLSecurity::Document#sign_document has been removed. ' \
               'Use RubySaml::XML::DocumentSigner.sign_document instead.'
         raise ::NoMethodError.new(msg)
       end
     end
 
-    # @deprecated Will be removed in v2.1.0.
+    # @deprecated Will be removed in v3.0.0.
     # @api private
     class SignedDocument < BaseDocument
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def initialize(*args, **_kwargs)
-        RubySaml::Logging.deprecate 'XMLSecurity::SignedDocument is deprecated and will be removed in v2.1.0.' \
+        RubySaml::Logging.deprecate 'XMLSecurity::SignedDocument is deprecated and will be removed in v3.0.0.' \
                                     'Use RubySaml::XML::SignedDocumentValidator.validate_document instead.'
         super(args[0])
       end
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def validate_document(*_args, **_kwargs)
         msg = 'XMLSecurity::SignedDocument#validate_document has been removed. ' \
               'Use RubySaml::XML::SignedDocumentValidator.validate_document instead.'
         raise ::NoMethodError.new(msg)
       end
 
-      # @deprecated Will be removed in v2.1.0.
+      # @deprecated Will be removed in v3.0.0.
       def extract_inclusive_namespaces
         msg = 'XMLSecurity::SignedDocument#extract_inclusive_namespaces has been removed.'
         raise ::NoMethodError.new(msg)
diff --git a/lib/xml_security.rb b/lib/xml_security.rb
@@ -2,8 +2,8 @@
 
 require 'ruby_saml/logging'
 RubySaml::Logging.deprecate 'Using `require "xml_security"` is deprecated and will be removed ' \
-                            'in RubySaml 2.1.0. Instead, please `require "ruby-saml"` and use ' \
+                            'in RubySaml 3.0.0. Instead, please `require "ruby-saml"` and use ' \
                             'the modules in RubySaml::XML instead.'
 
-# @deprecated This file adds compatibility with v1.x and will be removed in v2.1.0
+# @deprecated This file adds compatibility with v1.x and will be removed in v3.0.0
 require 'ruby_saml/xml'
