makwa 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2da52aacefd38c1922e5e8b48277fca8106997a068b682d93698bd9e444da41f
-  data.tar.gz: a506c6b8ae75f3d093afdf455b84733f0d0984843561dde099bbbb9ffddc7e91
+  metadata.gz: b5b57daebaedd9cdfe6e14503bc559f2b3cc9dc40beeb3461c2070b1f2c659a1
+  data.tar.gz: 1f57dc2aa9f5376a14ae4bde76d88be11ba6ad897892f8adeb69272962426116
 SHA512:
-  metadata.gz: 8784e825031765550dce4b56c82aae5a872d403cf14f444cdb0a2afb00fd2603e14f28910a92f3415b60df351820a17f738264eb6bf3bacd050f3ac21ee79c43
-  data.tar.gz: ea5dde94eca0a95abda600e4bd8f129dc63413a855cdf3ffb9ee5f15176ee7f1edcd368216265aff272def00ca4795b647f7667bd6bbe58ec3a742ab361274bd
+  metadata.gz: 41aa06f6e10421a0c1fe9af084b36838670c1300f00bb359975482539537f0bf852903a28cb058a0ea8ee996bcb953f850ccc915a8ac99861aa2a74e11860182
+  data.tar.gz: 76f38892c52dbeec20840416e10196c702e34ad351c2fd7f366c1d43aad4b2eb21221fc8ff113a793a4f83716c8703bfe18e9be751e36774003f655f0c2e0b8a

data/.gitignore

@@ -8,3 +8,5 @@
 
 Gemfile.lock
 .byebug_history
+
+.DS_Store

data/CHANGELOG.md

@@ -1,10 +1,19 @@
 ## [Unreleased]
 
+## [1.0.0] - 2022-11-26
+
+- Upgrades ActiveInteraction from 4.x to 5.2.x. Please see the [ActiveInteraction CHANGELOG](https://github.com/AaronLasseigne/active_interaction/blob/main/CHANGELOG.md) for what has changed between v. 4.x and 5. There are some breaking changes.
+- Adds documentation.
+
+## [0.2.1] - 2021-11-03
+
+- Fixes bug where the `returning` attribute was not ignored correctly when assigning attrs under certain error conditions.
+
 ## [0.2.0] - 2021-10-27
 
-- Adds implementation
-- Updates ReturningInteraction to copy errors and values to returned object on invalid inputs
+- Adds implementation.
+- Updates ReturningInteraction to copy errors and values to returned object on invalid inputs.
 
 ## [0.1.0] - 2021-09-23
 
-- Initial release
+- Initial release.

data/README.md

@@ -1,36 +1,188 @@
 # Makwa
 
-Interactions for Ruby on Rails.
+Makwa is an extension of the [ActiveInteraction](https://github.com/AaronLasseigne/active_interaction) gem, bringing interactions to Ruby on Rails apps.
+
+> ActiveInteraction manages application-specific business logic. It's an implementation of service objects designed to blend seamlessly into Rails. It also helps you write safer code by validating that your inputs conform to your expectations. If ActiveModel deals with your nouns, then ActiveInteraction handles your verbs.
+
+<p align="right">Readme for ActiveInteraction.</p>
+
+Makwa improves the ergonomics around mutating ActiveRecord instances.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'makwa'
+gem "makwa"
 ```
 
 And then execute:
 
-    $ bundle install
+```shell
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install makwa
+```shell
+$ gem install makwa
+```
+
+Makwa extends the ActiveInteraction gem and will install it automatically as a dependency.
+
+Makwa is compatible with Ruby 2.7 or greater and Rails 5 or greater.
+
+## What does Makwa add to ActiveInteraction?
+
+Please read through the [ActiveInteraction Readme](https://github.com/AaronLasseigne/active_interaction) first and then come back here to see what Makwa adds to ActiveInteraction:
+
+### ReturningInteraction
+
+ReturningInteractions are a special kind of interaction, optimized for usage with Rails forms:
+
+The basic approach of ActiveInteraction (AI) when rendering ActiveRecord model forms is to pass an AI instance to the form. That approach works great for simple mutations of ActiveRecord instances. However, for this to work, the AI class has to implement all methods required for rendering your forms. That can get tricky when you need to traverse associations, or call complex decorators on your models. This approach also fails if the interaction's `#execute` method is never run because the input validations fail.
+
+ReturningInteraction (RI) chooses a different approach: It accepts the to-be-mutated ActiveRecord instance as an input argument and is guaranteed to return that instance, no matter if the interaction outcome is successful or not. The RI will merge all errors that occurred during execution to the returned ActiveRecord instance. This allows you to pass the actual ActiveRecord instance to your form, and you don't have to implement all methods required for the form to be rendered.
+
+Let's look at some example code to see the difference:
+
+The ActiveInteraction way
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    outcome = Users::Create.run(
+      params.fetch(:user, {})
+    )
+
+    if outcome.valid?
+      redirect_to(outcome.result)
+    else
+      @user = outcome
+      render(:new)
+    end
+  end
+end
+
+# app/interactions/users/create.rb
+module Users
+  class Create < ApplicationInteraction
+    string :first_name
+    string :last_name
+    array :role_ids, default: []
+
+    def execute
+      user = User.new(inputs)
+      errors.merge!(user.errors) unless user.save
+      user
+    end
+
+    def to_model
+      User.new
+    end
+  end
+end
+```
+
+The Makwa way
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    # Differences: Pass in the `:user` input and call `#run_returning!` instead of `#run`.
+    @user = Users::Create.run_returning!(
+      {user: User.new}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:new)
+    end
+  end
+end
+
+# app/interactions/users/create.rb
+module Users
+  class Create < ApplicationReturningInteraction
+    returning :user # This is different from AI: Specifies which input will be returned.
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    def execute_returning # Notice: Method is called `execute_returning`, not `execute`!
+      user.update(inputs.except(:user))
+      # No need to merge any errors. This will be done automatically by Makwa
+      return_if_errors!
+
+      compose(
+        Infrastructure::SendEmail,
+        recipient_email: user.email,
+        subject: "Welcome to Makwa",
+        body: "Lorem ipsum..."
+      )
+      # No need for an explicit return of user, also done by Makwa
+      # (via `returning` input filter).
+    end
+
+    # No need to implement the `#to_model` method and any other methods required to
+    # render your forms.
+  end
+end
+```
+
+### Other improvements
+
+Makwa offers **safe ways to check for errors**. Instead of `#valid?` or `#invalid?` use `#errors_empty?` or `#errors_any?`. Rails' `#valid?` method is a destructive method that will clear all errors and re-run validations. This will eradicate any errors you added in the body of the `#execute` or `#execute_returning` methods.
+
+Makwa offers a simple way to **exit early** from the interaction. Use `#return_if_errors!` at any point in the `#execute` method if errors make it impossible to continue execution of the interaction.
+
+Makwa offers **detailed logging** around interaction invocations (with inputs) and outcomes (with errors):
+
+```
+Executing interaction Users::SendWelcomeEmail (id#1234567)
+ ↳ called from Users::Create (id#7654321)
+ ↳ inputs: {first_name: "Giselher", last_name: "Wulla"} (id#7654321)
+ # ... execute interaction
+ ↳ outcome: failed (id#7654321)
+ ↳ errors: "Email is missing" (id#7654321)
+```
+
+To enable debug logging just define this method in your `ApplicationInteraction`:
+
+```ruby
+def debug(txt)
+  puts indent + txt
+end
+```
 
-## Usage
+### Further reading
 
-TODO: Write usage instructions here
+* [Usage](doc/usage_examples.md): More complex examples and conventions.
+* [About interactions](doc/about_interactions.md): Motivation, when to use them.
+* [Features and design considerations](doc/features_and_design_considerations.md)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+We have [instructions for releasing a new version](doc/how_to_release_new_version.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/makwa.
+Bug reports and pull requests are welcome on GitHub at https://github.com/animikii/makwa.
 
 ## License
 

data/doc/about_interactions.md

@@ -0,0 +1,42 @@
+# About Interactions
+
+## When to use interactions
+
+When to use an interaction:
+
+* Use interactions for all but the most trivial ActiveRecord mutating CRUD operations.
+* Replace **ALL** ActiveRecord `:after_...` callbacks with interactions. This refers to all after callbacks, not just save.
+* Replace **MOST** ActiveRecord `:before_...` callbacks with interactions. This refers to all `:before_…` callbacks, not just save. An exception that can remain as a callback could be a `:before_validation` callback to sanitize an email address (strip surrounding whitespace, lower case), however, if there is already an interaction to create/update a user, you may as well do it in the interaction.
+* Replace Model instance and class methods that implement complex behaviours with interactions. Note that you can still use the Model methods as interface, however, the implementation should live in an interaction.
+
+## ReturningInteractions
+
+ReturningInteractions are a special kind of interaction, optimized for usage with Rails forms.
+
+### Motivation
+
+When processing a Rails form submission, e.g., via :create or :update, if the inputs are not valid (and the interaction’s input validation fails), we still need a form object that we can use to re-render the form. When an ActiveInteraction’s input validation fails, we don’t get that. We just get the errors and the interaction itself. And the interaction may not be a suitable stand-in for the model object if it does not implement all the methods found on the model object (e.g., associations or decorators).
+
+This is where ReturningInteractions come into play. Instead of returning themselves when errors exist, they will always return the specified input value. And any errors are merged into the returned value. The convention is to use the ActiveRecord instance as returned input value. Then, if errors exist, the returned instance can be used as form object to re-render the form.
+
+### How they are different from regular interactions
+
+ReturningInteractions inherit from ActiveInteraction, however, they are different in the following ways:
+
+* They will always return the specified input, no matter what happens after you invoke them:
+  * If input validations fail, and the `#execute_returning` method is never reached.
+  * If associated ActiveModel validations fail.
+  * If exceptions are rescued.
+  * If the `#execute_returning` method returns early.
+  * If it follows the happy path, everything goes as expected, independently of what the `#execute_returning` method returns.
+* They merge any errors added to the returned input argument before returning it.
+* They inherit from ReturningInteraction.
+* They have an additional returning macro to specify which one of the inputs is guaranteed to be returned.
+* The `#execute` method is replaced with `#execute_returning`.
+
+### Additional notes
+
+* They require the returned input argument to implement the ActiveModel::Errors interface so that any errors can be merged.
+* They behave very similar to the Ruby `#tap` method.
+* Instead of an ActiveRecord instance, you can also pass the record’s id to a ReturningInteraction. This is possible thanks to ActiveInteraction’s record input filter type.
+* Convention for input arguments: Don’t nest object attrs in a hash since ActiveInteraction doesn’t have good input filter error reporting on nested values. It’s better to have all attrs as flat list, merged with the returned record. (NOTE: This may be addressed with ActiveInteraction v5)

data/doc/features_and_design_considerations.md

@@ -0,0 +1,3 @@
+# Features and design considerations
+
+TBD

data/doc/how_to_release_new_version.md

@@ -5,10 +5,9 @@
   * Update CHANGELOG.md
   * Commit changes
 * Prepare new release
-  * Bump version via one of
-    * `gem bump --tag --version major`
-    * `gem bump --tag --version minor`
-    * `gem bump --tag --version patch`
-  * The bump command will commit the new version and tag the commit.
+  * Assign new version in `lib/makwa/version.rb`
+  * Commit the change with "Bump makwa to <version>"
+  * Tag the commit of the new version with `v<version>`
+  * Push the changes
 * Distribute new release
-  * `gem release` - This will push the new release to rubygems.org.
+  * `gem push makwa` - This will push the new release to rubygems.org.

data/doc/usage_examples.md

@@ -0,0 +1,216 @@
+# Makwa Interaction Usage Examples
+
+## Specify your Application interactions
+
+All specific interactions will inherit from your app-wide interactions:
+
+```ruby
+# app/interactions/application_interaction.rb
+class ApplicationInteraction < Makwa::Interaction
+  def debug(txt)
+    # Uncomment the next line for detailed debug output
+    # puts indent + txt
+  end
+end
+```
+
+```ruby
+# app/interactions/application_interaction.rb
+class ApplicationReturningInteraction < Makwa::ReturningInteraction
+  def debug(txt)
+    # Uncomment the next line for detailed debug output
+    # puts indent + txt
+  end
+end
+```
+
+## Implement a regular interaction to wrap a 3rd party service
+
+This example interaction wraps an email sending service:
+
+```ruby
+# app/interactions/infrastructure/send_email.rb
+module Infrastructure
+  class SendEmail < ApplicationInteraction
+    string :recipient_email
+    string :subject
+    string :body
+
+    validates :recipient_email, presence: true, format: {with: /.+@.+/}
+    validates :subject, presence: true
+
+    def execute
+      ThirdPartyEmailService.send(
+        to: recipient_email,
+        subject: subject,
+        body: body
+      )
+    end
+  end
+end
+```
+
+## Implement a ReturningInteraction to create a user
+
+```ruby
+# app/users/create.rb
+module Users
+  class Create < ApplicationReturningInteraction
+    returning :user
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    validates :first_name, presence: true
+    validates :last_name, presence: true
+    validates :email, presence: true, format: {with: /.+@.+/}
+
+    def execute_returning
+      user.update(inputs.except(:user))
+      return_if_errors!
+
+      compose(
+        Infrastructure::SendEmail, # See the example above for details
+        recipient_email: user.email,
+        subject: "Welcome to Makwa",
+        body: "Lorem ipsum..."
+      )
+    end
+  end
+end
+```
+
+Use this interaction from the controller:
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def new
+    @user = User.new
+  end
+
+  def create
+    # Differences: Pass in the `:user` input and call `#run_returning!` instead of `#run`.
+    @user = Users::Create.run_returning!(
+      {user: User.new}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:edit)
+    end
+  end
+end
+```
+
+## Implement a ReturningInteraction to update a user
+
+```ruby
+# app/users/update.rb
+module Users
+  class Update < ApplicationReturningInteraction
+    returning :user
+
+    string :first_name
+    string :last_name
+    string :email
+    record :user
+
+    validates :first_name, presence: true
+    validates :last_name, presence: true
+    validates :email, presence: true, format: {with: /.+@.+/}
+
+    def execute_returning
+      user.update(inputs.except(:user))
+    end
+  end
+end
+```
+
+Use this interaction from the controller:
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  before_action :load_user
+
+  def edit
+  end
+
+  def update
+    @user = Users::Create.run_returning!(
+      {user: @user}.merge(params.fetch(:user, {}))
+    )
+
+    if @user.errors_empty?
+      redirect_to(@user)
+    else
+      render(:edit)
+    end
+  end
+end
+```
+
+## Usage conventions
+
+Interactions follow these conventions:
+
+* **Code location**: Interactions are stored in app/interactions.
+* **Naming**: Interaction names always start with a verb, optionally followed by an Object noun. The Interaction’s parent namespaces provide additional context. When referring to ActiveRecord models in an interaction’s parent namespace, use plural form. This is to avoid naming conflicts with ActiveRecord models. Examples:
+  * `users/create.rb`
+  * `facilitator/groups/close.rb`
+  * `nw_app_structure/nw_patch_items/nw_tables/change/prepare_form_object.rb`
+* **Inheritance**: Interactions inherit from ApplicationInteraction, ApplicationReturningInteraction, or one of their descendants.
+* **Invocation**: You can invoke an Interaction in one of the following ways:
+  * `.run` - always returns the Interaction outcome. You can then query the outcome with `#errors_empy?`, `#errors_any?`, `#result` and `#errors`. This is the primary way of invoking Interactions. Example: `outcome = NwAppStructure::NwPatches::Apply.run(id: "1234abcd")`
+  * `.run!` - the bang version returns the Interaction’s return value if successful, and raises an exception if not successful. This can be used as a convenience method where we want to assure that the interaction executes successfully, and where we want easy access to the return value.
+  * **ReturningInteractions** can only be invoked with `.run_returning!`.
+* **Input param safety**: Interactions validate, restrict, and coerce their input args. That means you don't need strong params. You can use raw controller params via `user_params: params.to_unsafe_h[:user]`.
+* **Error handling**:
+  * Rely on ActiveModel validations to add errors to the interaction.
+  * Use `errors.add` and `errors.merge!` to manually add errors to an interaction.
+  * When composing interactions, errors in nested interactions bubble to the top.
+  * Errors can be used for flow control, e.g., via `#return_if_errors!`.
+* **Outcome**: Regular interactions that are invoked with `.run` return an outcome:
+  * Outcome can be tested for presence/absence of any errors. Please use `#errors_empty?` and `#errors_any?` instead of `#valid?`. See caveat below related to `#valid?` for details.
+  * Outcome has a `#result` (return value of the #execute method).
+  * Outcome exposes any errors via an `ActiveModel::Errors` compatible API.
+* **Input arguments**:
+  * Input arguments to an interaction are always wrapped in a Hash. The hash keys correspond to the interaction’s input filters.
+  * As a general guideline, interactions receive the same types of arguments as the corresponding controller action would expect as `params`: Only basic Ruby data types like Hashes, Arrays, Strings, Numbers, Dates, Times, etc. This convention provides the following benefits:
+    * Provides the simplest API possible.
+    * Makes it easy to invoke an Interaction from a controller action: Just forward the params as is.
+    * Makes it easy to invoke an interaction from the console. You can type all input args as literals.
+    * Makes it easy to pass test data into an interaction.
+    * Makes it easy to serialize the invocation of an interaction, e.g., for a Sidekiq background job.
+    * We do not pass in ActiveRecord instances, but their ids instead. We rely on ActiveRecord caching to prevent multiple DB reads when passing the same record id into nested interactions. Exceptions:
+      * You can pass a descendent of ActiveModel, e.g., an ActiveRecord instance as the returned input to a ReturningInteraction. Use the record input filter type. It accepts both the ActiveRecord instance, as well as its id attribute. That way, you can still pass in basic Ruby types, e.g., in the console when invoking the interaction.
+      * In some use cases with nested interactions, we may choose to pass in an ActiveRecord instance to work around persistence concerns.
+  * When an interaction is concerned with an ActiveRecord instance, we pass the record’s id under the :id hash key (unless it’s a ReturningInteraction).
+
+## Caveat: Don’t use #valid?
+
+We need to address the issue where the supposedly non-destructive ActiveModel method `#valid?` is actually destructive. This affects both ActiveModel::Validations as well as ActiveInteraction. The `#valid?` method actually clears out any existing errors and re-runs ActiveModel validations. This causes any errors added outside of an ActiveModel::Validation to disappear, resulting in `#valid?` returning true when it shouldn’t.
+
+Don't use `#valid?`, use `#errors_empty?` instead.
+
+Don't use `#invalid?`, use `#errors_any?` instead.
+
+Rails source code at activemodel/lib/active_model/validations.rb, line 334:
+
+```ruby
+def valid?(context = nil)
+  current_context, self.validation_context = validation_context, context
+  errors.clear
+  run_validations!
+ensure
+  self.validation_context = current_context
+end
+```
+
+The official Rails way to circumvent the clearing of errors is to use errors.any? or errors.empty?
+
+We wrap this implementation detail (calling errors.any?) in a method that clearly communicates intent, prevents well intentioned devs from changing `#errors.empty?` to `#valid?`, and helps us audit code to make sure that we're not using the default `#valid?` method in connection with Interactions (Both on the interaction itself, and on any ActiveRecord instances it touches).

data/lib/makwa/interaction.rb

@@ -2,7 +2,7 @@
 
 module Makwa
   class Interaction < ::ActiveInteraction::Base
-    class Interrupt < Object.const_get("::ActiveInteraction::Interrupt")
+    class Interrupt < Object.const_get(:"::ActiveInteraction::Interrupt")
     end
 
     #
@@ -28,7 +28,7 @@ module Makwa
     #
 
     # Log execution of interaction, caller, and inputs
-    set_callback :type_check, :before, ->(interaction) {
+    set_callback :filter, :before, ->(interaction) {
       debug("Executing interaction #{interaction.class.name} #{interaction.id_marker}")
       calling_interaction = interaction.calling_interaction
       debug(" ↳ called from #{calling_interaction} #{interaction.id_marker}") if calling_interaction.present?
@@ -41,10 +41,10 @@ module Makwa
     # Log interaction's outcome and errors if any.
     set_callback :execute, :after, ->(interaction) {
       if interaction.errors_empty?
-        debug(" ↳ outcome: succeeded (id##{interaction.object_id})")
+        debug(" ↳ outcome: succeeded #{interaction.id_marker}")
       else
-        debug(" ↳ outcome: failed (id##{interaction.object_id})")
-        debug(" ↳ errors: #{interaction.errors.details} (id##{interaction.object_id})")
+        debug(" ↳ outcome: failed #{interaction.id_marker}")
+        debug(" ↳ errors: #{interaction.errors.details} #{interaction.id_marker}")
       end
     }
 

data/lib/makwa/returning_interaction.rb

@@ -46,10 +46,11 @@ module Makwa
       # Run validations (explicitly, don't rely on #valid?)
       validate
       if errors_any?
+        return_filter = self.class.instance_variable_get(:@return_filter)
         # Add errors and values to the result object (so that the form can render them) and return the result object
         return result
             .tap { |r| r.errors.merge!(errors) }
-            .tap { |r| r.assign_attributes(inputs.except(@return_filter)) }
+            .tap { |r| r.assign_attributes(inputs.except(return_filter)) }
       end
 
       # Otherwise run the body of the interaction (along with any callbacks) ...

data/lib/makwa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Makwa
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

data/makwa.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Interactions for Ruby on Rails apps."
   spec.homepage = "https://github.com/animikii/makwa"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.4.0"
+  spec.required_ruby_version = ">= 2.7.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/animikii/makwa"
@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "active_interaction", "~> 4.0"
+  spec.add_dependency "active_interaction", "~> 5.2.0"
 
   spec.add_development_dependency "standard"
   spec.add_development_dependency "byebug"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: makwa
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jo Hund
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-27 00:00:00.000000000 Z
+date: 2022-11-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_interaction
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -69,7 +69,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- doc/about_interactions.md
+- doc/features_and_design_considerations.md
 - doc/how_to_release_new_version.md
+- doc/usage_examples.md
 - lib/makwa.rb
 - lib/makwa/interaction.rb
 - lib/makwa/returning_interaction.rb
@@ -90,14 +93,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Interactions for Ruby on Rails apps.