diff --git a/docs/upgrading.md b/docs/upgrading.md index d3aa70d3..3d2ab4a8 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -9,6 +9,7 @@ This buildpack does not port all behaviors of the [classic buildpack for Ruby ]( - 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](https://railslts.com/) this can mean a very old version of Rails. Now we will actively support Rails versions currently [under the Rails core maintenance policy](https://guides.rubyonrails.org/maintenance_policy.html) 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](https://github.com/heroku/heroku-buildpack-ruby/blob/168cb5d556f154e4eba57c797d04b18a4d8b354c/lib/language_pack/ruby.rb#L944-L946). - 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.