upgrading.md

Upgrading from the classic Ruby buildpack

This buildpack does not port all behaviors of the classic buildpack for Ruby , which is also known as "classic". This section outlines the known behaviors where the two buildpacks diverge.

Differences

• Rails 5+ support only. The classic buildpack supports Rails 2+. There are significant maintenance gains for buildpack authors starting in Rails 5 which was released in 2016. In an effort to reduce overall internal complexity this buildpack does not explicitly support Rails before version 5.
• Rails support is now based on the above application contract. Previously there was no official policy for dropping support for older Rails versions. Support was based on whether or not an older version could run on a currently supported Ruby version. With Rails LTS this can mean a very old version of Rails. Now we will actively support Rails versions currently under the Rails core maintenance policy provided those versions can run on a supported Ruby version. As Rails versions go out of official maintenance compatibility features may be removed with no supported replacement.
• Ruby versions come from the Gemfile.lock only. Before bundler started recording the Ruby version in the Gemfile.lock, Heroku would pull the Ruby version via running bundle platform --ruby to pull any ruby declaration such as ruby "3.1.2" from the Gemfile. This creates a bootstrapping problem, because you need a version of Ruby to run bundle platform to find the version of Ruby the application needs. Since the Ruby version is now recorded in the Gemfile.lock, this extra bootstrapping problem is less needed and applications should rely on their version being in their Gemfile.lock instead. To update the Ruby version in Gemfile.lock run bundle update --ruby.
• Default Ruby versions are no longer sticky. Before bundler started recording the Ruby version in the Gemfile.lock it was common for developers to forget to declare their Ruby version in their project. When that happens they would receive the default Ruby version from the classic buildpack. To guard against instability the classic buildpack would record that version and use it again on all future deploys where no explicit version was specified. Now it's less likely for an app to deploy without a ruby version in their Gemfile.lock, and we do not want to encourage relying on a default for stability (as this otherwise breaks dev-prod parity).
• The Node.js runtime will only be installed if there is a package.json file present at the root of the repository. A default Node.js version will no longer be installed based on the presence of gems that imply the dependency of a javascript runtime. Previously, the classic buildpack would install a version of Node.js if a gem such as execjs or webpacker was detected.
• Failure to detect rake tasks will fail a deployment. On all builds rake -p is called to find a list of all rake tasks. If this detection task fails then the previous behavior was to fail the build only if the sprockets gem was present. The reason was to allow API-only apps that don't need to generate assets to have a Rakefile that cannot be run in production (the most common reason is they're requiring a library not in their production gemfile group). Now all failures when loading a Rakefile will fail the build.
• Caching of public/assets is gated on the presence of rake assets:clean. Previously this behavior was gated on the existence of a certain version of the Rails framework.
• Caching of tmp/cache/assets (fragments) is gated on the presence of rake assets:clean. Previously this behavior was gated on the existence of a certain version of the Rails framework.