request_migrations 0.1.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a07f06f1ea7b2b51851ff1490e1233363bc4d13bc6ac8918e7c1d886c9497ffd
-  data.tar.gz: 79f9bb8c317e906b4d4d6992811156103265d902f82ca0fcc1ac65a6e85327de
+  metadata.gz: 1575eecb9ad23c9dae9534b03a31acbcef8c6ed7bf46f4ffca1748ef21fcead4
+  data.tar.gz: 141dbbf4576e8b2da641ab32bd377173bbe61717d330c741c0b10c5cf9eff854
 SHA512:
-  metadata.gz: 595d53c2b5d25dd34d4212e9db9208b96dccf684ec03e4cd75fa485d5421c400cc0b465e4914d7613a3ef15c08757b93ce163cebf1cb886dccf14e7986ca16bb
-  data.tar.gz: 95cd329eee002333f976886c2394a538dc1f3e6231f093a4d7155b9330eaf0725dc9ed38e31c6ccc0d9e7fdeb6a32b7f54970dc6114064b6286b96888b0be4d2
+  metadata.gz: 119241518c4d8a9a954bd4918a6e2edbc0338938c7173953a406821f34f0f4da735e7819b7cc0e929be45c78a7da88f035f1456d5b98d53d6cb00b0fca1c8362
+  data.tar.gz: 5afffe316b08692daeaf2366fab161f23794b80326112a2b4c4ece1a13f0d40f8d61423aa81d4bf28c62274acf8a33dd63c01214295524cd7691c42203a71575

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.1
+
+- Fix application order of `request` migrations.
+
+## 1.0.0
+
+- Initial release.
+
 ## 0.1.0
 
 - Test release.

data/README.md

@@ -3,12 +3,17 @@
 [![Gem Version](https://badge.fury.io/rb/request_migrations.svg)](https://badge.fury.io/rb/request_migrations)
 
 **Make breaking API changes without breaking things!** Use `request_migrations` to craft
-backwards-compatible migrations for API requests, responses, and more. This is being
-used in production by [Keygen](https://keygen.sh) to serve millions of API requests per day.
+backwards-compatible migrations for API requests, responses, and more. Read [the blog
+post](https://keygen.sh/blog/breaking-things-without-breaking-things/).
+
+This gem was extracted from [Keygen](https://keygen.sh) and is being used in production
+to serve millions of API requests per day.
+
+![request_migrations diagram](https://user-images.githubusercontent.com/6979737/175964358-a2d8951d-46c6-4962-9f5e-0569cbf5972e.png)
 
 Sponsored by:
 
-[![Keygen logo](https://camo.githubusercontent.com/d50a6bd1f31fd4da523b8aa555a54356cc2d3e81eb8bc9123303787e44c5bb07/68747470733a2f2f6b657967656e2e73682f696d616765732f62616467652e706e67)](https://keygen.sh)
+[![Keygen logo](https://user-images.githubusercontent.com/6979737/175406169-bd8bf064-7343-4bd1-94b7-a773ecec07b8.png)](https://keygen.sh)
 
 _A software licensing and distribution API built for developers._
 
@@ -47,8 +52,9 @@ _We're working on improving the docs._
 
 - Define migrations for migrating a response between versions.
 - Define migrations for migrating a request between versions.
-- Define migrations for applying one-off migrations.
+- Define migrations for applying data migrations.
 - Define version-based routing constraints.
+- It's fast.
 
 ## Usage
 
@@ -126,7 +132,7 @@ Next, we'll need to configure `request_migrations` via an initializer under
 
 ```ruby
 RequestMigrations.configure do |config|
-  # Define a resolver to determine the current version. Here, you can perform
+  # Define a resolver to determine the target version. Here, you can perform
   # a lookup on the current user using request parameters, or simply use
   # a header like we are here, defaulting to the latest version.
   config.request_version_resolver = -> request {
@@ -138,7 +144,7 @@ RequestMigrations.configure do |config|
 
   # Define previous versions and their migrations, in descending order.
   config.versions = {
-    '1.0' => %i[combine_user_names_migration],
+    '1.0' => %i[combine_names_for_user_migration],
   }
 end
 ```
@@ -149,6 +155,14 @@ are applied:
 ```ruby
 class ApplicationController < ActionController::API
   include RequestMigrations::Controller::Migrations
+
+  # Optionally rescue from requests for unsupported versions
+  rescue_from RequestMigrations::UnsupportedVersionError, with: -> {
+    render(
+      json: { error: 'unsupported API version requested', code: 'INVALID_API_VERSION' },
+      status: :bad_request,
+    )
+  }
 end
 ```
 
@@ -177,7 +191,12 @@ end
 
 The `response` method accepts an `:if` keyword, which should be a lambda
 that evaluates to a boolean, which determines whether or not the migration
-should be applied.
+should be applied. An `ActionDispatch::Response` will be yielded, the
+current response (calls `controller#response`).
+
+The gem makes no assumption on a response's content type or what the migration
+will do. You could, for example, migrate the response body, or mutate the
+headers, or even change the response's status code.
 
 ### Request migrations
 
@@ -197,19 +216,25 @@ end
 
 The `request` method accepts an `:if` keyword, which should be a lambda
 that evaluates to a boolean, which determines whether or not the migration
-should be applied.
+should be applied. An `ActionDispatch::Request` object will be yielded,
+the current request (calls `controller#request`).
+
+Again, like with response migrations, the gem makes no assumption on what
+a migration does. A migration could mutate a request's params, or mutate
+headers. It's up to you, all it does is provide the request.
+
+Request migrations should [avoid using the `migrate` method](#avoid-migrate-for-request-migrations).
 
-### One-off migrations
+### Data migrations
 
 In our first scenario, where we combined our user's name attributes, we defined
 our migration using the `migrate` class method. At this point, you may be wondering
 why we did that, since we didn't use that method for the 2 previous request and
 response migrations above.
 
-Well, it comes down to support for one-off migrations (as well as offering
-a nice interface for pattern matching inputs).
-
-Let's go back to our first example, `CombineNamesForUserMigration`.
+Well, it comes down to support for data migrations (as well as offering a nice
+interface for pattern matching inputs). Let's go back to our first example,
+`CombineNamesForUserMigration`.
 
 ```ruby
 class CombineNamesForUserMigration < RequestMigrations::Migration
@@ -239,7 +264,7 @@ end
 ```
 
 What if we had [a webhook system](https://keygen.sh/blog/how-to-build-a-webhook-system-in-rails-using-sidekiq/)
-that we also needed to apply these migrations to? Well, we can use a one-off migration
+that we also needed to apply these migrations to? Well, we can use a data migration
 here, via the `Migrator` class:
 
 ```ruby
@@ -265,15 +290,19 @@ class WebhookWorker
 end
 ```
 
-Now, we've successfully applied a migration to both our API responses, as well
+This will apply the block defined in `migrate` onto our data. With that,
+we've successfully applied a migration to both our API responses, as well
 as to the webhook events we send. In this case, if our `event` matches the
 our user shape, e.g. `type: 'user'`, then the migration will be applied.
 
+In addition to data migrations, this allows for easier testing.
+
 ### Routing constraints
 
 When you want to encourage API clients to upgrade, you can utilize a routing `version_constraint`
-to define routes only available for certain versions. You can also utilize routing constraints
-to remove an API endpoint entirely.
+to define routes only available for certain versions.
+
+You can also utilize routing constraints to remove an API endpoint entirely.
 
 ```ruby
 Rails.application.routes.draw do
@@ -291,13 +320,13 @@ Rails.application.routes.draw do
 end
 ```
 
-Currently, routing constraints only work for the `:semver` version format.
+Currently, routing constraints only work for the `:semver` version format. (PRs welcome!)
 
 ### Configuration
 
 ```ruby
 RequestMigrations.configure do |config|
-  # Define a resolver to determine the current version. Here, you can perform
+  # Define a resolver to determine the target version. Here, you can perform
   # a lookup on the current user using request parameters, or simply use
   # a header like we are here, defaulting to the latest version.
   config.request_version_resolver = -> request {
@@ -324,9 +353,8 @@ RequestMigrations.configure do |config|
     ],
   }
 
-  # Use a custom logger. Must be a tagged logger. Defaults to
-  # using Rails.logger.
-  config.logger = ActiveSupport::TaggedLogging.new(...)
+  # Use a custom logger. Supports ActiveSupport::TaggedLogging.
+  config.logger = Rails.logger
 end
 ```
 
@@ -335,19 +363,53 @@ end
 By default, `request_migrations` uses a `:semver` version format, but it can be configured
 to instead use one of the following, set via `config.version_format=`.
 
-| Format     |                                                     |
-|:-----------|:----------------------------------------------------|
-| `:semver`  | Use semantic versions, e.g. `1.0`, `1.1, and `2.0`. |
-| `:date`    | Use date versions, e.g. `2020-09-02`, `2021-01-01`. |
-| `:integer` | Use integer versions, e.g. `1`, `2`, and `3`.       |
-| `:float`   | Use float versions, e.g. `1.0`, `1.1`, and `2.0`.   |
-| `:string`  | Use string versions, e.g. `a`, `b`, and `z`.        |
+| Format     |                                                      |
+|:-----------|:-----------------------------------------------------|
+| `:semver`  | Use semantic versions, e.g. `1.0`, `1.1`, and `2.0`. |
+| `:date`    | Use date versions, e.g. `2020-09-02`, `2021-01-01`.  |
+| `:integer` | Use integer versions, e.g. `1`, `2`, and `3`.        |
+| `:float`   | Use float versions, e.g. `1.0`, `1.1`, and `2.0`.    |
+| `:string`  | Use string versions, e.g. `a`, `b`, and `z`.         |
+
+All versions will be sorted according to the format's type.
+
+## Testing
+
+Using data migrations allows for easier testing of migrations. For example, using Rspec:
+
+```ruby
+describe CombineNamesForUserMigration do
+  before do
+    RequestMigrations.configure do |config|
+      config.current_version = '1.1'
+      config.versions        = {
+        '1.0' => [CombineNamesForUserMigration],
+      }
+    end
+  end
 
-### Tips and tricks
+  it 'should migrate user name attributes' do
+    migrator = RequestMigrations::Migrator.new(from: '1.1', to: '1.0')
+    data     = serialize(
+      create(:user, first_name: 'John', last_name: 'Doe'),
+    )
 
-Over the years, we're learned a thing or two about writing request migrations. We'll share tips here.
+    expect(data).to include(type: 'user', first_name: 'John', last_name: 'Doe')
+    expect(data).to_not include(name: anything)
 
-#### Use pattern matching
+    migrator.migrate!(data:)
+
+    expect(data).to include(type: 'user', name: 'John Doe')
+    expect(data).to_not include(first_name: 'John', last_name: 'Doe')
+  end
+end
+```
+
+## Tips and tricks
+
+Over the years, we're learned a thing or two about versioning an API. We'll share tips here.
+
+### Use pattern matching
 
 Pattern matching really cleans up the `:if` conditions, and overall makes migrations more readable.
 
@@ -382,7 +444,7 @@ end
 
 Just be sure to remember your `else` block when `case` pattern matching. :)
 
-#### Route helpers
+### Route helpers
 
 If you need to use route helpers in a migration, include them in your migration:
 
@@ -392,7 +454,7 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Separate by shape
+### Separate by shape
 
 Define separate migrations for different input shapes, e.g. define a migration for an `#index`
 to migrate an array of objects, and define another migration that handles the singular object
@@ -454,7 +516,7 @@ end
 
 Note that the `migrate` method now migrates an array input, and matches on the `#index` route.
 
-#### Always check response status
+### Always check response status
 
 Always check a response's status. You don't want to unintentionally apply migrations to error
 responses.
@@ -467,7 +529,9 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Don't match on URL pattern
+Also mind `204 No Content`, since the response body will be `nil`.
+
+### Don't match on URL pattern
 
 Don't match on URL pattern. Instead, use `response.request.params` to access the request params
 in a `response` migration, and use the `:controller` and `:action` params to determine route.
@@ -482,7 +546,7 @@ class SomeMigration < RequestMigrations::Migration
 end
 ```
 
-#### Namespace deprecated controllers
+### Namespace deprecated controllers
 
 When you need to entirely change a controller or service class, use a `V1x0::UsersController`-style
 namespace to keep the old deprecated classes tidy.
@@ -495,12 +559,36 @@ class V1x0::UsersController
 end
 ```
 
+### Avoid migrate for request migrations
 
-#### Avoid routing contraints
+Avoid using `migrate` for request migrations. If you do, then data migrations, e.g. for
+webhooks, will attempt to apply the request migrations. This may erroneously produce bad
+output, or even undo a response migration. Instead, keep all request migration logic,
+e.g. transforming params, inside of the `request` block.
+
+```ruby
+class SomeMigration < RequestMigrations::Migration
+  # Bad (side-effects for data migrations)
+  migrate do |params|
+    params[:foo] = params.delete(:bar)
+  end
+
+  request do |req|
+    migrate!(req.params)
+  end
+
+  # Good
+  request do |req|
+    req.params[:foo] = req.params.delete(:bar)
+  end
+end
+```
+
+### Avoid routing contraints
 
 Avoid using routing version constraints that remove functionality. They can be a headache
-during upgrades. Consider only making _additive_ changes. You should remove docs for old
-or deprecated endpoints to limit any new usage.
+during upgrades. Consider only making _additive_ changes. Instead, consider removing or
+hiding the documenation for old or deprecated endpoints, to limit any new usage.
 
 ```ruby
 Rails.application.routes.draw do
@@ -518,6 +606,61 @@ Rails.application.routes.draw do
 end
 ```
 
+### Avoid n+1s
+
+Avoid introducing n+1 queries in your migrations. Try to utilize the current data you have
+to perform more meaningful queries, returning only the data needed for the migration.
+
+```ruby
+class AddRecentPostToUsersMigration < RequestMigrations::Migration
+  description %(adds :recent_post association to a collection of users)
+
+  # Bad (n+1)
+  migrate if: -> data { data in [*, { type: 'user' }, *] do |data|
+    data.each do |record|
+      case record
+      in type: 'user', id:
+        recent_post = Post.reorder(created_at: :desc)
+                          .find_by(user_id: id)
+
+        record[:recent_post] = recent_post&.id
+      else
+      end
+    end
+  end
+
+  # Good
+  migrate if: -> data { data in [*, { type: 'user' }, *] do |data|
+    user_ids = data.collect { _1[:id] }
+    post_ids = Post.select(:id, :user_id)
+                   .distinct_on(:user_id)
+                   .where(user_id: user_ids)
+                   .reorder(created_at: :desc)
+                   .group_by(&:user_id)
+
+    data.each do |record|
+      case record
+      in type: 'user', id: user_id
+        record[:recent_post] = post_ids[user_id]&.id
+      else
+      end
+    end
+  end
+
+  response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+                                                                 action: 'index' } do |res|
+    data = JSON.parse(res.body, symbolize_names: true)
+
+    migrate!(data)
+
+    res.body = JSON.generate(data)
+  end
+end
+```
+
+Instead of potentially tens or hundreds of queries, we make a single purposeful query
+to get the data we need in order to complete the migration.
+
 ---
 
 Have a tip of your own? Open a pull request!

data/lib/request_migrations/configuration.rb

@@ -4,10 +4,35 @@ module RequestMigrations
   class Configuration
     include ActiveSupport::Configurable
 
-    config_accessor(:logger)                   { Rails.logger }
+    ##
+    # logger defines the logger used by request_migrations.
+    #
+    # @return [Logger] the logger.
+    config_accessor(:logger) { Logger.new("/dev/null") }
+
+    ##
+    # request_version_resolver defines how request_migrations should resolve the
+    # current version of a request.
+    #
+    # @return [Proc] the request version resolver.
     config_accessor(:request_version_resolver) { -> req { self.current_version } }
-    config_accessor(:version_format)           { :semver }
-    config_accessor(:current_version)          { nil }
-    config_accessor(:versions)                 { [] }
+
+    ##
+    # version_format defines the version format.
+    #
+    # @return [Symbol] format
+    config_accessor(:version_format) { :semver }
+
+    ##
+    # current_version defines the latest version.
+    #
+    # @return [String, Integer, Float, nil] the current version.
+    config_accessor(:current_version) { nil }
+
+    ##
+    # versions defines past versions and their migrations.
+    #
+    # @return [Hash<String, Array<Symbol, String, Class>>] past versions.
+    config_accessor(:versions) { {} }
   end
 end

data/lib/request_migrations/controller.rb

@@ -2,6 +2,8 @@
 
 module RequestMigrations
   module Controller
+    ##
+    # @private
     class Migrator < Migrator
       def initialize(request:, response:, **kwargs)
         super(**kwargs)
@@ -13,7 +15,7 @@ module RequestMigrations
       def migrate!
         logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
 
-        migrations.each_with_index { |migration, i|
+        migrations.reverse.each_with_index { |migration, i|
           logger.debug { "Applying migration #{migration} (#{i + 1}/#{migrations.size})" }
 
           migration.new.migrate_request!(request)
@@ -35,9 +37,24 @@ module RequestMigrations
       attr_accessor :request,
                     :response
 
-      def logger = RequestMigrations.logger.tagged(request&.request_id)
+      def logger
+        if RequestMigrations.config.logger.respond_to?(:tagged)
+          RequestMigrations.logger.tagged(request&.request_id)
+        else
+          RequestMigrations.logger
+        end
+      end
     end
 
+    ##
+    # Migrations is controller middleware that automatically applies migrations.
+    #
+    # @example
+    #   class ApplicationController < ActionController::API
+    #     include RequestMigrations::Controller::Migrations
+    #   end
+    #
+    # @raise [RequestMigrations::UnsupportedVersionError]
     module Migrations
       extend ActiveSupport::Concern
 
@@ -60,7 +77,7 @@ module RequestMigrations
       extend ActiveSupport::Concern
 
       included do
-        # TODO(ezekg) Implement controller-level version constraints
+        # TODO(ezekg) Implement controller-level version constraints.
       end
     end
   end

data/lib/request_migrations/gem.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RequestMigrations
-  VERSION = "0.1.0"
+  VERSION = "1.0.2"
 end

data/lib/request_migrations/migration.rb

@@ -1,7 +1,32 @@
 # frozen_string_literal: true
 
 module RequestMigrations
+  ##
+  # Migration represents a migration for a specific version.
+  #
+  # @example
+  #   class CombineNamesForUserMigration < RequestMigrations::Migration
+  #     description %(transforms a user's first and last name to a combined name attribute)
+  #
+  #     migrate if: -> data { data in type: 'user' } do |data|
+  #       first_name = data.delete(:first_name)
+  #       last_name  = data.delete(:last_name)
+  #
+  #       data[:name] = "#{first_name} #{last_name}"
+  #     end
+  #
+  #     response if: -> res { res.successful? && res.request.params in controller: 'api/v1/users',
+  #                                                                    action: 'show' } do |res|
+  #       data = JSON.parse(res.body, symbolize_names: true)
+  #
+  #       migrate!(data)
+  #
+  #       res.body = JSON.generate(data)
+  #     end
+  #   end
   class Migration
+    ##
+    # @private
     class ConditionalBlock
       def initialize(if: nil, &block)
         @if    = binding.local_variable_get(:if)
@@ -39,18 +64,40 @@ module RequestMigrations
         klass.response_blocks   = response_blocks.dup
       end
 
+      ##
+      # description sets the description.
+      #
+      # @param desc [String] the description
       def description(desc)
         self.description_value = desc
       end
 
+      ##
+      # request sets the request migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [ActionDispatch::Request] the current request.
       def request(if: nil, &block)
         self.request_blocks << ConditionalBlock.new(if:, &block)
       end
 
+      ##
+      # migrate sets the data migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [Any] the provided data.
       def migrate(if: nil, &block)
         self.migration_blocks << ConditionalBlock.new(if:, &block)
       end
 
+      ##
+      # response sets the response migration.
+      #
+      # @param if [Proc] the proc which determines if the migration should run.
+      #
+      # @yield [ActionDispatch::Response] the current response.
       def response(if: nil, &block)
         self.response_blocks << ConditionalBlock.new(if:, &block)
       end
@@ -58,18 +105,24 @@ module RequestMigrations
 
     extend DSL
 
+    ##
+    # @private
     def migrate_request!(request)
       self.class.request_blocks.each { |block|
         instance_exec(request) { block.call(self, _1) }
       }
     end
 
+    ##
+    # @private
     def migrate!(data)
       self.class.migration_blocks.each { |block|
         instance_exec(data) { block.call(self, _1) }
       }
     end
 
+    ##
+    # @private
     def migrate_response!(response)
       self.class.response_blocks.each { |block|
         instance_exec(response) { block.call(self, _1) }

data/lib/request_migrations/migrator.rb

@@ -2,11 +2,22 @@
 
 module RequestMigrations
   class Migrator
+    ##
+    # Migrator represents a versioned migration from one version to another.
+    #
+    # @param from [String, Integer, Float] the current version.
+    # @param to [String, Integer, Float] the target version.
     def initialize(from:, to:)
       @current_version = Version.new(from)
       @target_version  = Version.new(to)
     end
 
+    ##
+    # migrate! attempts to apply all matching migrations on data.
+    #
+    # @param data [Any] the data to be migrated.
+    #
+    # @return [void]
     def migrate!(data:)
       logger.debug { "Migrating from #{current_version} to #{target_version} (#{migrations.size} potential migrations)" }
 
@@ -26,11 +37,12 @@ module RequestMigrations
 
     def logger = RequestMigrations.logger
 
-    # TODO(ezekg) These should be sorted
     def migrations
       @migrations ||=
         RequestMigrations.config.versions
           .filter { |(version, _)| Version.new(version).between?(target_version, current_version) }
+          .sort
+          .reverse
           .flat_map { |(_, migrations)| migrations }
           .map { |migration|
             case migration

data/lib/request_migrations/railtie.rb

@@ -1,4 +1,6 @@
 module RequestMigrations
+  ##
+  # @private
   class Railtie < ::Rails::Railtie
     ActionDispatch::Routing::Mapper.send(:include, Router::Constraints)
   end

data/lib/request_migrations/router.rb

@@ -3,6 +3,8 @@
 module RequestMigrations
   module Router
     module Constraints
+      ##
+      # @private
       class VersionConstraint
         def initialize(constraint:)
           @constraint = Version::Constraint.new(constraint)
@@ -19,6 +21,20 @@ module RequestMigrations
         def resolver = RequestMigrations.config.request_version_resolver
       end
 
+      ##
+      # version_constraint is a router constraint that resolves routes for
+      # specific versions.
+      #
+      # @param constraint [String] the version constraint.
+      #
+      # @yield the block when the constraint is satisfied.
+      #
+      # @example
+      #   Rails.application.routes.draw do
+      #     version_constraint '> 1.0' do
+      #       resources :some_new_resource
+      #     end
+      #   end
       def version_constraint(constraint, &)
         constraints VersionConstraint.new(constraint:) do
           instance_eval(&)

data/lib/request_migrations/version.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module RequestMigrations
+  ##
+  # @private
   class Version
     include Comparable
 

data/lib/request_migrations.rb

@@ -2,6 +2,7 @@
 
 require "active_support/concern"
 require "semverse"
+require "logger"
 require "request_migrations/gem"
 require "request_migrations/configuration"
 require "request_migrations/version"
@@ -12,20 +13,60 @@ require "request_migrations/router"
 require "request_migrations/railtie"
 
 module RequestMigrations
+  ##
+  # UnsupportedMigrationError is raised when an invalid migration is provided.
   class UnsupportedMigrationError < StandardError; end
+
+  ##
+  # InvalidVersionFormatError is raised when an badly formatted version is provided.
   class InvalidVersionFormatError < StandardError; end
+
+  ##
+  # UnsupportedVersionError is raised when an unsupported version is requested.
   class UnsupportedVersionError < StandardError; end
+
+  ##
+  # InvalidVersionError is raised when an invalid version is provided.
   class InvalidVersionError < StandardError; end
 
-  SUPPORTED_VERSION_FORMATS = %i[semver date float integer string].freeze
+  ##
+  # SUPPORTED_VERSION_FORMATS is a list of supported version formats.
+  SUPPORTED_VERSION_FORMATS = %i[
+    semver
+    date
+    float
+    integer
+    string
+  ].freeze
 
-  def self.logger = @logger ||= RequestMigrations.config.logger.tagged(:request_migrations)
+  ##
+  # config returns the current config.
   def self.config = @config ||= Configuration.new
 
+  ##
+  # logger returns the configured logger.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= if RequestMigrations.config.logger.respond_to?(:tagged)
+                  RequestMigrations.config.logger.tagged(:request_migrations)
+                else
+                  RequestMigrations.config.logger
+                end
+  end
+
+  ##
+  # configure yields the config.
+  #
+  # @yield [config]
   def self.configure
     yield config
   end
 
+  ##
+  # supported_versions returns an array of supported versions.
+  #
+  # @return [Array<String, Integer, Float>]
   def self.supported_versions
     [RequestMigrations.config.current_version, *RequestMigrations.config.versions.keys].uniq.freeze
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: request_migrations
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-06-23 00:00:00.000000000 Z
+date: 2022-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails