# Ransack Migration Guide: How to Upgrade Between Versions Safely > Safely upgrade Ransack versions with this guide. Learn about breaking changes and compatibility requirements by combining info from the CHANGELOG, release docs, and README for a smooth transition. - Repository: [ActiveRecord Hackery/ransack](https://github.com/activerecord-hackery/ransack) - Tags: migration-guide - Published: 2026-02-23 --- **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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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: ```ruby # Gemfile gem 'ransack', '~> 4.4' # Replace with your target version ``` 4. **Run Bundler** to install the new version: ```bash 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):** ```ruby @search = Article.search(params[:q]) ``` **After (3.0.0+):** ```ruby @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`](https://github.com/activerecord-hackery/ransack/blob/main/CHANGELOG.md), [`docs/going-further/release_process.md`](https://github.com/activerecord-hackery/ransack/blob/main/docs/going-further/release_process.md), and [`README.md`](https://github.com/activerecord-hackery/ransack/blob/main/README.md). - The [`CHANGELOG.md`](https://github.com/activerecord-hackery/ransack/blob/main/CHANGELOG.md) is the authoritative source for breaking changes between versions. - Always check the [`README.md`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/CHANGELOG.md), the release process documentation at [`docs/going-further/release_process.md`](https://github.com/activerecord-hackery/ransack/blob/main/docs/going-further/release_process.md), and the [`README.md`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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.