Ransack Migration Guide: How to Upgrade Between Versions Safely

Ransack does not provide a single dedicated migration guide file; instead, upgrade instructions are distributed across the CHANGELOG, release process documentation, and README, which together document every breaking change and compatibility requirement.

If you are upgrading the activerecord-hackery/ransack gem in your Rails application, you need to know where the project maintains its version-to-version documentation. While you will not find a centralized "MIGRATION.md" file, the repository provides three canonical sources that function as a complete migration guide when used together.

Where Ransack Documents Version Changes

The Ransack project distributes upgrade-critical information across three specific files. Understanding where each piece of information lives will streamline your upgrade process.

Release Process Documentation

The file docs/going-further/release_process.md contains the semantic-versioning policy and the exact steps maintainers follow when publishing a new release. This document explains how the version constant is updated and how releases are tagged, which is essential if you are maintaining a fork or need to understand the release cadence.

CHANGELOG.md

The CHANGELOG.md file at the repository root is your primary reference for breaking changes. It lists every feature, bug-fix, and backward-incompatible change in chronological order. When migrating between versions, scan the entries between your current version and your target version, paying special attention to sections marked "Breaking Changes".

README and Compatibility Notes

The README.md file documents the supported Ruby and Rails versions for the current release. Before upgrading Ransack, verify that your application meets these minimum requirements to avoid runtime errors.

Step-by-Step Ransack Upgrade Process

Follow this sequence when upgrading the gem in your Rails application to ensure you do not miss breaking changes or compatibility issues.

1. Review the CHANGELOG for the version range you are crossing. Look for "Breaking Changes" headers that indicate code you must modify (for example, the removal of the #search method in version 3.0.0 or the introduction of attribute allow-listing in 4.0.0).

2. Check the README for Ruby and Rails version requirements. Upgrade your application's Ruby or Rails version if necessary before proceeding.

3. Update your Gemfile to specify the target version:

   # Gemfile
   
   gem 'ransack', '~> 4.4'  # Replace with your target version
   

4. Run Bundler to install the new version:

   bundle update ransack

5. Execute your test suite and address any failures related to the breaking changes identified in step 1.

Handling Breaking Changes in Ransack Upgrades

Major version bumps in Ransack often require specific code changes in your application. Here are the two most significant recent breaking changes and how to address them.

Upgrading to 3.0.0: Replacing #search

Version 3.0.0 removed the deprecated #search method that was previously available on Active Record models. If your application uses the old syntax, you must update it to use ransack instead.

Before (pre-3.0.0):

@search = Article.search(params[:q])

After (3.0.0+):

@search = Article.ransack(params[:q])

Refer to the CHANGELOG entry for version 3.0.0 for the complete list of removals.

Upgrading to 4.0.0: Attribute Allow-Listing

Version 4.0.0 introduced a security-focused breaking change that requires explicit allow-listing of searchable attributes. You must now define which attributes are ransackable in your models using ransackable_attributes or the ransackable_associations method.

Consult the CHANGELOG for version 4.0.0 to understand the specific configuration required for your models.

Summary

• Ransack does not maintain a single migration guide file; upgrade information is distributed across CHANGELOG.md, docs/going-further/release_process.md, and README.md.
• The CHANGELOG.md is the authoritative source for breaking changes between versions.
• Always check the README.md for Ruby and Rails compatibility requirements before upgrading.
• Major version upgrades (such as 2.x to 3.x or 3.x to 4.x) require specific code changes, such as replacing #search with #ransack or implementing attribute allow-listing.

Frequently Asked Questions

Is there a dedicated Ransack migration guide document?

No, the activerecord-hackery/ransack repository does not contain a single file named "MIGRATION.md" or similar. Instead, the project documents upgrade paths in the CHANGELOG.md, the release process documentation at docs/going-further/release_process.md, and the README.md. Together, these files provide the complete migration guidance.

What file contains the Ransack version constant?

The version constant is defined in lib/ransack/version.rb. This file contains the VERSION string that is updated by maintainers during the release process documented in docs/going-further/release_process.md. If you are maintaining a fork or contributing to the gem, this is the file you must modify to bump the version.

How do I handle the removal of the #search method in Ransack 3.0?

You must replace all instances of .search with .ransack on your Active Record models. For example, change Article.search(params[:q]) to Article.ransack(params[:q]). This breaking change is documented in the CHANGELOG.md under the 3.0.0 release section, which also lists any other methods that were removed or deprecated in that version.

Where can I find breaking changes for a specific Ransack version?

Breaking changes are listed in the CHANGELOG.md file at the root of the repository. Each version entry includes a "Breaking Changes" subsection when applicable. For example, version 4.0.0 documents the introduction of attribute allow-listing, and version 3.0.0 documents the removal of the #search method. This file is the definitive source for version-to-version migration requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}